> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Kimi Chat Completion API 申請及使用

> Kimi 整合指南 - Ace Data Cloud

Kimi 是月之暗面推出的 AI 模型系列。當前推薦的 `kimi-k3` 面向長程編程、Agent、複雜推理和知識工作，可透過 OpenAI 兼容的 Chat Completions API 調用。

本文檔主要介紹 Kimi Chat Completion API 操作的使用流程，利用它我們可以輕鬆使用官方 Kimi 的對話功能。

## 申請流程

要使用 Kimi Chat Completion API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 獲取您的 API Token，留作備用。

![](https://cdn.acedata.cloud/5hmkdg.jpg)

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。

**一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用餘額。

> 📘 完整文檔：[Kimi Chat Completion API →](https://platform.acedata.cloud/documents/kimi-chat-completions)

## 基本使用

接下來就可以在界面上填寫對應的內容，如圖所示：

<p>
  <img src="https://cdn.acedata.cloud/ej5ozg.png" width="400" className="m-auto" />
</p>

第一次使用該接口時，至少需要填寫三個內容：`authorization` 可直接從下拉列表選擇；`model` 用於選擇 Kimi 模型，推薦使用 `kimi-k3`；`messages` 是對話消息數組，每條消息包含 `role` 和 `content`，其中 `role` 支持 `user`、`assistant`、`system` 和 `tool`。

同時您可以注意到右側有對應的調用代碼生成，您可以複製代碼直接運行，也可以直接點擊「Try」按鈕進行測試。

<p>
  <img src="https://cdn.acedata.cloud/six7e3.png" width="400" className="m-auto" />
</p>

以下是使用 `reasoning_effort: max` 獲得的真實 K3 響應（省略未使用的擴展字段）：

```json theme={null}
{
  "id": "msg_2D4Btbg1WgvkNE3tCYkR4xGA",
  "object": "chat.completion",
  "created": 1784466588,
  "model": "kimi-k3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 86,
    "completion_tokens": 206,
    "total_tokens": 292
  }
}
```

返回結果一共有多個字段，介紹如下：

* `id`，生成此次對話任務的 ID，用於唯一標識此次對話任務。
* `model `，選擇的 Kimi 官網模型。
* `choices` Kimi 針對提問詞給予的回答信息。
* `usage `：針對本次問答對 token 的統計信息。

其中 `choices` 是包含了 Kimi 的回答信息，它裡面的 `choices` 是 Kimi回答的具體信息，可以發現如圖所示。

<p>
  <img src="https://cdn.acedata.cloud/tv9rul.png" width="400" className="m-auto" />
</p>

可以看到，`choices` 裡面的 `content` 字段包含了 Kimi 回覆的具體內容；K3 還可能返回 `reasoning_content`，用於表示推理過程。

## K3 推理強度

`kimi-k3` 始終啟用推理。請求體頂層支持 `reasoning_effort` 字段，當前唯一受支持的值是 `max`；省略該字段時同樣使用 `max`。`standard`、`high` 或其他字符串可能被部分兼容上游寬鬆接受，但不保證改變推理行為，請勿依賴。

```bash theme={null}
curl https://api.acedata.cloud/kimi/chat/completions \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "審查這段代碼並給出修復方案"}],
    "reasoning_effort": "max"
  }'
```

使用 OpenAI SDK 時可直接傳遞該字段：

```python theme={null}
response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "設計一個可靠的任務隊列"}],
    reasoning_effort="max",
)
```

多輪對話和工具調用時，請將上一輪完整的 assistant 消息回傳到 `messages`，包括 `reasoning_content` 和 `tool_calls`。

### 官方參考

* [Thinking Effort](https://platform.kimi.ai/docs/guide/use-thinking-effort)：說明 Kimi K3 始終啟用推理，當前 `reasoning_effort` 唯一支持的值為 `max`。
* [Model Parameter Reference](https://platform.kimi.ai/docs/api/models-overview)：對比 K3 與 K2 系列的推理參數、上下文窗口和工具調用差異。
* [Create Chat Completion](https://platform.kimi.ai/docs/api/chat)：Moonshot 官方 Chat Completions 請求、響應和 OpenAPI 字段定義。

## 流式響應

該接口也支持流式響應，這對網頁對接十分有用，可以讓網頁實現逐字顯示效果。

如果想流式返回響應，可以更改請求頭裡面的 `stream ` 參數，修改為 `true`。

修改如圖所示，不過調用代碼需要有對應的更改才能支持流式響應。

<p>
  <img src="https://cdn.acedata.cloud/a3nzpw.png" width="400" className="m-auto" />
</p>

將 `stream` 修改為 `true` 之後，API 將逐行返回對應的 JSON 數據，在代碼層面我們需要做相應的修改來獲得逐行的結果。

Python 樣例調用代碼：

```python theme={null}
import requests

url = "https://api.acedata.cloud/kimi/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "kimi-k3",
    "messages": [{"role":"user","content":"Hello"}],
    "reasoning_effort": "max",
    "stream": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

下面節選同一次真實 K3 Max 流式響應中的起始、推理、正文、結束和用量數據塊：

```json theme={null}
data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"","role":"assistant"},"finish_reason":null}],"usage":null}

data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"reasoning_content":"這"},"finish_reason":null}],"usage":null}

data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}],"usage":null}

data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":null}

data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[],"usage":{"prompt_tokens":172,"completion_tokens":168,"total_tokens":340}}

data: [DONE]
```

可以看到，響應裡面有許多 `data` ，`data` 裡面的 `choices` 即為最新的回答內容，與上文介紹的內容一致。`choices` 是新增的回答內容，您可以根據結果來對接到您的系統中。同時流式響應的結束是根據 `data` 的內容來判斷的，如果內容為 `[DONE]`，則表示流式響應回答已經全部結束。返回的 `data` 結果一共有多個字段，介紹如下：

* `id`，生成此次對話任務的 ID，用於唯一標識此次對話任務。
* `model `，選擇的 Kimi 官網模型。
* `choices`，Kimi 針對提問詞給予的回答信息。

JavaScript 也是支持的，比如 Node.js 的流式調用代碼如下：

```javascript theme={null}
const options = {
  method: "post",
  headers: {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    "model": "kimi-k3",
    "messages": [{"role":"user","content":"你好"}],
    "stream": true
  })
};

fetch("https://api.acedata.cloud/kimi/chat/completions", options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

Java 樣例代碼：

```java theme={null}
JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "kimi-k3");
jsonObject.put("messages", [{"role":"user","content":"你好"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/kimi/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.print(response.body!!.string())
```

其他語言可以另外自行改寫，原理都是一樣的。

## 多輪對話

如果您想要對接多輪對話功能，需要對 `messages` 字段上傳多個提問詞，多個提問詞的具體示例如下圖所示：

<p>
  <img src="https://cdn.acedata.cloud/g85v2a.png" width="400" className="m-auto" />
</p>

Python 樣例調用代碼：

```python theme={null}
import requests

url = "https://api.acedata.cloud/kimi/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "kimi-k3",
    "messages": [{"role":"assistant","content":"你好！我今天能幫助你什麼？"},{"role":"user","content":"你是什麼模型？"}],
    "reasoning_effort": "max"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

透過上傳多個提問詞，就可以輕鬆實現多輪對話。以下是該請求獲得的真實 K3 Max 響應（省略未使用的擴展字段）：

```json theme={null}
{
  "id": "msg_Rqp8nPGBDHWwBlL4VpxuafOp",
  "object": "chat.completion",
  "created": 1784466628,
  "model": "kimi-k3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我是 Kimi，一個由 Moonshot AI (月之暗面) 開發的 AI 助手。我這裡沒有具體的公共模型版本標識可以分享。"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 134,
    "completion_tokens": 346,
    "total_tokens": 480
  }
}
```

可以看到，`choices` 包含的信息與基本使用的內容是一致的，這個包含了 Kimi 針對多個對話進行回覆的具體內容，這樣就可以根據多個對話內容來回答對應的問題了。

## 錯誤處理

在調用 API 時，如果遇到錯誤，API 會返回相應的錯誤代碼和信息。例如：

* `400 token_mismatched`：錯誤請求，可能是由於缺少或無效的參數。
* `400 api_not_implemented`：錯誤請求，可能是由於缺少或無效的參數。
* `401 invalid_token`：未授權，無效或缺少授權令牌。
* `429 too_many_requests`：請求過多，您已超過速率限制。
* `500 api_error`：內部伺服器錯誤，伺服器出現問題。

### 錯誤響應示例

```
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "獲取失敗"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

透過本文檔，您已經了解了如何使用 Kimi Chat Completion API 實現普通對話、流式響應、多輪對話，以及透過 `reasoning_effort` 控制 K3 的推理強度。