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

# Kimi K3.1 Pro

> Kimi K3.1 Pro 與高速版官轉接入指南：模型選型、OpenAI 相容呼叫、思考分檔、流式輸出、工具呼叫，以及快取引數和實測邊界。

## 概述

**Kimi K3.1 Pro** 是月之暗面的思考模型，適合程式碼開發、複雜推理和多步工具任務。API易提供 `kimi-k3.1-pro` 與 `kimi-k3.1-pro-highspeed` 兩款官轉模型，使用同一套請求格式；切換型號只需修改 `model`。

> [!NOTE]
>
> **先選標準版，再按時延需求切換高速版。** 兩款均始終開啟思考，可用 `reasoning_effort` 調整思考深度。高速版的輸入、輸出與快取寫入單價更高，適合對響應速度要求更高的互動流程。

> [!WARNING]
>
> **1 小時快取本輪未驗證通過，不作為已支援能力。** 基礎對話、流式、工具呼叫等已通過；快取引數參考與本輪驗證邊界見下方說明。

> **[快速接入](#快速開始)**
>
> 使用 OpenAI SDK 或 HTTP，直接呼叫 Chat Completions。

> **[模型與價格](#模型選型與價格)**
>
> 對照標準版與高速版，以及輸入、輸出、快取的計費方式。

> **[思考與工具](#工具呼叫)**
>
> 按任務選擇思考檔位，正確回傳工具呼叫歷史。

> **[上下文快取](#上下文快取)**
>
> 瞭解官方快取引數與 API易本輪實測邊界。

## 模型選型與價格

兩款模型按實際 token 用量計費，**API易當前配置單價與官網一致**。單位均為 **美元 / 1M tokens**；普通輸入與輸出扣費已核對，快取檔位為配置價，不代表本輪已驗證快取結算：

| 計費專案 | `kimi-k3.1-pro` | `kimi-k3.1-pro-highspeed` |
| - | - | - |
| 普通輸入 | \$2.00 | \$4.00 |
| 輸出（含思考） | \$10.00 | \$20.00 |
| 快取讀取（配置價） | \$0.20 | \$0.20 |
| 快取寫入：5 分鐘（配置價） | \$2.00 | \$4.00 |
| 快取寫入：1 小時（配置價） | \$4.00 | \$8.00 |

> [!NOTE]
>
> 模型價格與官網對齊，且可能隨官網調整；上表僅供參考，具體以頂部導航「模型價格」欄目為準：[模型價格](https://docs.apiyi.com/zh-Hant/models/index.md)。

| 型號 | 建議用途 | 選擇依據 |
| - | - | - |
| `kimi-k3.1-pro` | 日常開發、推理、文件處理、批次工具任務 | 以成本為先的預設選擇 |
| `kimi-k3.1-pro-highspeed` | 互動式智慧體、需要更快返回的工作流 | 為更低時延接受更高 token 單價 |

### 充值加贈後的實際成本

滿足 [充值加贈活動](https://docs.apiyi.com/zh-Hant/faq/recharge-promotions.md) 條件時，**充值送 20％** 相當於使用 1 份充值金額獲得 1.2 份可用額度：實際成本為掛牌價的 `1 ÷ 1.2 ≈ 83.33％`，即**約 8.3 折**。

這一折算作用於可用額度，模型掛牌單價不變。活動門檻、加贈比例與適用規則以活動頁為準。

## 基礎能力實測

API易於 **2026-10-25 (UTC+8)** 對兩款模型完成以下基礎用例驗證：

| 能力 | `kimi-k3.1-pro` | `kimi-k3.1-pro-highspeed` |
| - | - | - |
| 非流式文本對話 | 通過 | 通過 |
| 流式文本輸出 | 通過 | 通過 |
| JSON 物件輸出 | 通過 | 通過 |
| 函式呼叫及工具結果回傳 | 通過 | 通過 |
| 影像理解 | 通過 | 通過 |
| Responses 基礎呼叫 | 通過 | 通過 |
| Messages 基礎呼叫 | 通過，需顯式取樣引數 | 通過，需顯式取樣引數 |
| 普通輸入與輸出計費日誌核查 | 與掛牌單價一致 | 與掛牌單價一致 |

本頁以 Chat Completions 為主要接入示例；已有 Responses 整合也可使用 `POST /v1/responses`。影像理解用例採用 Base64 資料輸入。

Messages 介面 `POST /v1/messages` 也已通過基礎驗證；請顯式傳入 `top_p: 0.95` 與 `temperature: 1`，避免預設取樣引數轉換引發報錯。

> [!NOTE]
>
> 上表驗證了基礎呼叫與結果語義，並核對普通輸入、輸出扣費；不代表已窮舉所有引數、最大上下文或長時間執行表現。快取有效期和計費需單獨驗證，見下方快取說明。

## 快速開始

使用 API易令牌，通過 `POST /v1/chat/completions` 呼叫。先以 `reasoning_effort: "low"` 跑通接入，再根據任務複雜度提高思考檔位。

```bash cURL theme={null}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro",
    "messages": [
      {"role": "user", "content": "解釋 Python 字典與列表的區別，並各舉一個使用場景。"}
    ],
    "reasoning_effort": "low",
    "max_completion_tokens": 8192
  }'
```

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",
    timeout=300,
)

response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[
        {"role": "user", "content": "解釋 Python 字典與列表的區別，並各舉一個使用場景。"}
    ],
    reasoning_effort="low",
    max_completion_tokens=8192,
)

message = response.choices[0].message
print(message.content)
print(response.usage)
```

> [!TIP]
>
> 把模型名做成配置項。需要高速版時，改成 `kimi-k3.1-pro-highspeed`，其餘接入程式碼可以複用。

## 思考控制與關鍵引數

兩款模型**始終開啟思考**。用 `reasoning_effort` 控制深度，而非沿用 Kimi K2.5 的 `enable_thinking` 開關。

| 引數 | 用法 |
| - | - |
| `reasoning_effort` | `low`、`high`、`max`；官方預設 `max` |
| `max_completion_tokens` | 為本次輸出設定預算；預算包含思考與最終回答 |
| `stream` | 設為 `true` 接收流式輸出 |
| `stream_options.include_usage` | 流式請求設為 `true`，獲取末塊用量 |
| `tools` | 定義由你的應用執行的函式工具 |
| `prompt_cache_options` | 配置隱式上下文快取及有效期 |

> [!WARNING]
>
> 不要把 `max_completion_tokens` 設得過小。思考會先消耗輸出預算，預算耗盡時可能只得到思考內容，最終回答為空或不完整。檢查 `finish_reason`，並按任務需要增加預算。

官方固定取樣引數為 `temperature=1`、`top_p=0.95`、`n=1`、`presence_penalty=0`、`frequency_penalty=0`。本頁 Chat Completions 示例省略這些引數；Messages 介面按上方說明顯式傳入取樣引數。避免從其他模型複製不相容的配置。

### 如何讀取回答

最終回答在 `choices[0].message.content`，思考內容在 `choices[0].message.reasoning_content`。展示最終回答時讀取 `content`；需要單獨展示思考過程時，再讀取 `reasoning_content`。

思考 token 按輸出價格計費，不能只用使用者可見的回答長度估算費用。以響應 `usage` 和控制台日誌為準。

## 流式輸出

思考階段和正文階段分別通過 `delta.reasoning_content`、`delta.content` 返回。末尾還可能有 `choices` 為空的用量塊，解析時先檢查 `chunk.usage`，再讀取 `choices`。

```python theme={null}
stream = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "user", "content": "設計一個帶重試機制的任務佇列。"}],
    reasoning_effort="low",
    max_completion_tokens=8192,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.usage is not None:
        print("\nUsage:", chunk.usage)
    if not chunk.choices:
        continue

    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        # 將思考內容寫入獨立區域，避免混入最終答案。
        pass
    if delta.content:
        print(delta.content, end="", flush=True)
```

## 工具呼叫

模型負責生成函式名和引數，實際工具由你的應用執行。收到 `tool_calls` 後，把**完整 assistant 訊息**追加到歷史，包含 `reasoning_content` 與 `tool_calls`；再追加對應 `tool_call_id` 的工具結果，發起下一輪請求。

```python theme={null}
import json

messages = [{"role": "user", "content": "查詢訂單 A100 的配送狀態。"}]
tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "查詢指定訂單的配送狀態",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
            "additionalProperties": False,
        },
    },
}]

response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=messages,
    tools=tools,
    reasoning_effort="low",
    max_completion_tokens=8192,
)
message = response.choices[0].message
messages.append(message.model_dump(exclude_none=True))

if message.tool_calls:
    for call in message.tool_calls:
        arguments = json.loads(call.function.arguments)
        # 示例結果；生產環境應校驗引數後呼叫真實訂單服務。
        result = {"order_id": arguments["order_id"], "status": "已發貨"}
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })

    final = client.chat.completions.create(
        model="kimi-k3.1-pro",
        messages=messages,
        tools=tools,
        reasoning_effort="low",
        max_completion_tokens=8192,
    )
    print(final.choices[0].message.content)
else:
    print(message.content)
```

> [!WARNING]
>
> 工具呼叫輪次不要只保留 `content`。遺漏 `reasoning_content` 或 `tool_calls` 可能破壞後續推理與工具結果關聯。先校驗工具名、引數與執行權限，再執行模型請求的操作。

## 上下文快取

官方快取機制適合反覆使用的長系統提示詞、知識文件與程式碼上下文。穩定內容放在訊息前部，每次變化的問題放在末尾。

> [!WARNING]
>
> **本輪未驗證通過，不作為 API易已支援的 1 小時快取能力。** 兩款模型分別用獨立長字首測試 5 分鐘和 1 小時策略，請求均成功，但未返回有效快取讀寫計數；間隔約 5 分半後的四組回讀及後續短間隔複用均未觀察到快取命中。1 小時請求的日誌也只出現普通輸入計費，未觀察到 1 小時快取寫入費用。

以上結論只代表本輪測試結果，不能據此斷言該能力在所有請求中均不支援。生產預算請先按普通輸入價格估算；確認自己的請求出現快取用量和對應計費後，再計入快取節省。以下引數與機制僅供官方格式參考。

### 選擇快取有效期

Chat Completions 使用**請求體頂層** `prompt_cache_options`，預設有效期為 5 分鐘。選擇 1 小時時傳：

```python theme={null}
response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[
        {"role": "system", "content": LONG_STABLE_CONTEXT},
        {"role": "user", "content": "根據上面的資料，列出三個關鍵結論。"},
    ],
    reasoning_effort="low",
    max_completion_tokens=8192,
    extra_body={
        "prompt_cache_options": {"mode": "implicit", "ttl": "1h"}
    },
)
print(response.usage)
```

`LONG_STABLE_CONTEXT` 代表你需要重複使用的長文本。後續請求保持該字首一致，再替換最後的問題。

> [!NOTE]
>
> **快取有效期在首次寫入時確定。** 對已存在的 5 分鐘快取改傳 `ttl: "1h"`，不會直接把它升級為 1 小時；命中會按原有有效期續期。需要對照兩種策略時，應使用不同的新字首分別寫入。

### 讀取與寫入如何計費

* **快取讀取**：複用已有字首，按快取讀取單價計費。
* **快取寫入**：新字首進入快取，按所選 5 分鐘或 1 小時寫入單價計費。
* **普通輸入**：未納入快取的輸入部分，按普通輸入單價計費。
* **輸出**：思考和最終回答都按輸出單價計費。

以上是官方計費分類。本輪只驗證了普通輸入和輸出扣費，未驗證到快取讀寫結算。排查費用時，同時檢查響應 `usage`、快取讀取/建立欄位和控制台計費日誌，不能只看引數是否被接受。

## 技術規格與接入建議

| 專案 | 說明 |
| - | - |
| 模型 ID | `kimi-k3.1-pro`、`kimi-k3.1-pro-highspeed` |
| 官方上下文視窗 | 1,048,576 tokens |
| 本頁主端點 | `POST https://api.apiyi.com/v1/chat/completions` |
| 思考模式 | 始終開啟；`reasoning_effort` 選擇 `low` / `high` / `max` |
| 最終回答欄位 | `choices[0].message.content` |
| 思考欄位 | `choices[0].message.reasoning_content` |
| 官方快取選項 | 預設 5 分鐘；可請求 1 小時；平臺實測邊界見快取說明 |

**1. 先用低思考檔跑通**

先發送短請求，確認模型名、令牌、響應解析正確，再增加上下文長度。

**2. 為思考保留輸出預算**

根據 `finish_reason` 與用量調整 `max_completion_tokens`，複雜任務再提高 `reasoning_effort`。

**3. 長任務優先用流式**

分別處理思考與正文，並讀取末塊用量；客戶端和中間代理都應留出足夠超時。

**4. 先驗證快取再擴大流量**

用固定長字首做重複請求，對照快取用量與計費日誌，確認業務請求確實命中。

## 常見問題

> **高速版是否只是不同的模型名？**
>
> 兩款使用相同接入格式，高速版定位於更低時延，單價更高。實際速度受提示詞長度、思考深度、輸出長度和當時負載影響，應以你的業務樣本評估。

> **能像 Kimi K2.5 一樣關閉思考嗎？**
>
> K3.1 Pro 系列始終開啟思考。用 `reasoning_effort: "low"` 控制開銷，不要沿用舊版 `enable_thinking` 引數。

> **為什麼最終回答很短，輸出計費卻更多？**
>
> 輸出包含思考 token。最終回答字元數不能代表完整輸出用量，請檢視響應 `usage` 和控制台日誌。

> **1 小時快取是否只需把舊請求的 ttl 改成 1h？**
>
> 按官方機制，已存在的快取沿用首次寫入時的有效期，需要從新字首開始傳 `ttl: "1h"`。但 API易本輪尚未驗證到 1 小時保留與寫入計費，不能把傳參成功當作支援證明。

> **充值送 20％為什麼是約 8.3 折？**
>
> 因為同樣金額可使用 1.2 倍額度，折算為 `1 ÷ 1.2 ≈ 83.33％`。這需要滿足活動條件，詳見 [充值加贈活動](https://docs.apiyi.com/zh-Hant/faq/recharge-promotions.md)。

## 相關文件

* [API 使用手冊](https://docs.apiyi.com/zh-Hant/api-manual.md)
* [函式呼叫基礎](https://docs.apiyi.com/zh-Hant/api-capabilities/openai/function-calling.md)
* [推理模型響應處理](https://docs.apiyi.com/zh-Hant/api-capabilities/openai/reasoning-models.md)
* [模型價格](https://docs.apiyi.com/zh-Hant/models/index.md)
* [充值加贈活動](https://docs.apiyi.com/zh-Hant/faq/recharge-promotions.md)

官方資料核對入口：`platform.moonshot.ai/docs/guide/kimi-k3-1-pro-quickstart`、`platform.kimi.ai/docs/guide/context-caching`、`platform.moonshot.ai/docs/pricing/chat`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.