Kimi K3.1 Pro API 串接與 Agent 使用指南

Kimi K3.1 Pro 是 Moonshot AI 的 K3.1 系列模型，適用於程式碼、3D 創作、金融研究與長程 Agent 工作。透過官方 API 呼叫時，模型 ID 為 kimi-k3.1-pro，OpenAI SDK 的 Base URL 為 https://api.moonshot.cn/v1。模型一律啟用思考模式，推理強度可設為 low、high 或 max，預設為 max。官方快速入門

本文依據官方介面說明介紹串接、推理、視覺輸入與工具循環。廠商公布的基準結果屬於廠商評測；下文不會將其描述為貴數智能的實測結果。

核心資訊

項目	已核實資訊
官方模型 ID	kimi-k3.1-pro
官方 API Base URL	https://api.moonshot.cn/v1
推理強度	low、high、max；預設 max
思考模式	一律啟用
上下文	官方文件稱支援 100 萬 token
高速型號	kimi-k3.1-pro-highspeed；為獨立型號，可用性與價格請查閱對應平台目錄
文件核驗日期	2026-10-24

以上能力與型號資訊以官方 Kimi K3.1 Pro 文件為準。模型版本、存取資格與費用可能變動；本站目前可用的模型與價格請查看模型價格。

這次升級適合用在哪些工作？

K3.1 Pro 的亮點在於多步驟工作：讀取需求、產生工程、檢查結果，再依據回饋修改。百萬 token 上下文可容納更多資料，但長任務能否成功仍取決於工具、環境與驗收條件。官方介紹著重於程式碼、3D 創作與金融研究；以下案例分別來自第三方體驗與廠商展示，並非本站的執行結果。

3D 相機：檢查結構是否真的隨參數改變

劉小排在《國產模型又往前走了一大步：Kimi K3.1 Pro 實測》中，請多個模型製作可互動的相機模型。他表示 K3.1 Pro 產生了 34 個可選部件與 9 片光圈葉片，35 項光學讀數符合他的檢查要求；第二輪將鏡頭從 50mm 改為 85mm 時，模型也改變了幾何結構，而非只更換標籤。

同一案例仍有缺陷：匯出單位未依要求處理，機身框架與光圈之間也有間隙問題。對設計工作而言，更有用的驗收方式是同時檢查尺寸、互動、匯出檔案與二次修改，而不只是看一張算圖。作者使用了不同的程式工具環境，因此這些體驗不能視為控制變因一致的模型排名。

遊戲地圖：先產生工具，再讓 Agent 使用

同一位作者也製作了瀏覽器版 Terraria 地圖編輯器，要求方塊放置符合遊戲規則，匯出的地圖能回到遊戲中執行；接著讓 K3.1 Pro 使用產生的編輯器搭建場景。這類任務結合檔案格式理解、介面開發與工具操作，比產生一段展示用程式碼更接近真實工作流程。作者認為 Kimi 與比較模型各有視覺方面的優點；這是個人觀察，並非普遍的審美結論。

金融研究：檢查公式與引用，而不只閱讀結論

《機器之心》的編輯澤南、張倩與 Panda 所整理的介紹資料，包含財務建模、研究報告與 3D 工程案例。官方文件也展示了可調整營運假設的財務模型，以及附有來源的研究報告。這些案例值得參考的是驗收要求：修改假設後公式是否會連動、關鍵數字能否追溯至原始檔案、報告引用能否逐一開啟。廠商展示不等於對任何金融任務的正確性保證。官方能力與案例介紹

截至本文核驗時，官方表示計畫在 11 月 4 日前開放完整權重；本文不會將計畫描述為已經發布，也不會把官方應用中的 3D 功能視為 API 內建的建模工具。

API 基本呼叫

官方範例使用 Python 3.9+ 與 OpenAI SDK。API Key 應存放在環境變數中，不要寫進原始碼或提交至版本庫。

python3 -m pip install --upgrade 'openai>=1.0'
export MOONSHOT_API_KEY="your-api-key"

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

result = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "user", "content": "請用三點說明如何設計可靠的程式碼審查流程。"}],
    reasoning_effort="high",
)
print(result.choices[0].message.content)

直接連線至 Moonshot 時，請使用 Moonshot 核發的 Key 與上述官方 Base URL。若使用相容 API 的第三方服務，應改用該服務提供的 Base URL、Key 與模型目錄，不要將官方憑證交給第三方。貴數智能目前支援的型號與計費方式，請以模型價格頁為準。

如何選擇推理強度

K3.1 Pro 一律處於思考模式；reasoning_effort 控制推理強度，而不是切換思考開關。官方提供 low、high、max 三個級別，預設值為 max。官方推理強度說明

• 簡短問答或結構明確的轉換工作，可先試用 low。
• 多步驟程式碼修改、分析與規劃工作，可從 high 開始。
• 需要較深入推理的複雜工作，可比較 max 的品質、延遲與實際費用。

以上是工作流程選擇建議，不是模型效能保證。正式環境應使用自己的任務集評估正確率、延遲與成本。

多輪對話：保留完整 assistant message

官方要求在多輪對話與工具回傳時，將 API 回傳的完整 assistant message 加入下一次請求，而不只是保留文字 content。工具呼叫等結構化欄位可能是後續流程所需的一部分。官方多輪對話說明

messages = [{"role": "user", "content": "先列出遷移計畫，再說明風險。"}]
first = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=messages,
    reasoning_effort="high",
)
messages.append(first.choices[0].message)
messages.append({"role": "user", "content": "將風險部分改寫成檢查清單。"})
second = client.chat.completions.create(model="kimi-k3.1-pro", messages=messages)
print(second.choices[0].message.content)

若應用程式需要跨請求持續保存對話，應儲存通訊協定所需的訊息欄位，並依官方文件確認 SDK 對訊息物件的序列化方式。

工具呼叫與 Agent 循環

工具由應用程式定義並執行：模型產生工具呼叫，應用程式驗證參數、呼叫實際函式，再將工具結果與模型關聯。不要直接將模型輸出視為可信任命令執行。

import json

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_order",
        "description": "查詢訂單狀態",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]
messages = [{"role": "user", "content": "查詢訂單 A-104 的狀態"}]
response = client.chat.completions.create(
    model="kimi-k3.1-pro", messages=messages, tools=tools
)
assistant = response.choices[0].message
messages.append(assistant)  # 保留完整 assistant message

for call in assistant.tool_calls or []:
    args = json.loads(call.function.arguments)
    # 實際應用程式應先驗證參數與使用者權限，再呼叫受控的業務函式。
    tool_result = {"order_id": args["order_id"], "status": "processing"}
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps(tool_result),
    })

final = client.chat.completions.create(
    model="kimi-k3.1-pro", messages=messages, tools=tools
)
print(final.choices[0].message.content)

官方工具呼叫指南也要求每個工具結果都以相應的 tool_call_id 回傳，並在後續輪次保留完整 assistant message。應用程式必須自行實作身分驗證、參數檢查、逾時、冪等性與稽核。

視覺輸入：使用物件陣列

官方文件規定，視覺訊息的 content 是物件陣列，而不是序列化字串。範例透過 Base64 Data URL 傳送圖片；也可依官方支援的檔案流程使用 ms:// 檔案參照。不要假設模型能直接讀取一般公開網路圖片 URL。官方視覺輸入說明

import base64
from pathlib import Path

image_data = base64.b64encode(Path("diagram.png").read_bytes()).decode()
response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {
                "url": f"data:image/png;base64,{image_data}"
            }},
            {"type": "text", "text": "描述圖中的系統元件及連線關係。"},
        ],
    }],
)
print(response.choices[0].message.content)

實際串接前應確認圖片格式、大小與檔案介面限制；將敏感圖片傳送至外部模型前，也應確認組織的資料處理規範。

如何解讀官方基準與第三方體驗

Moonshot 文件披露，K3.1 Pro 在 Terminal-Bench 4.0 的得分為 65.7%，並列出與 GPT-6 Astra、Claude Opus 5.5 的比較；這些數字是廠商公布的基準資訊，應搭配任務集、測試設定與發布日期解讀，不能推論為所有程式碼工作的成功率。官方模型介紹與基準

第三方作者劉小排分享了相機 3D 互動作品等體驗，並提出個人模型比較判斷。這是作者的第三方體驗，不是貴數智能的測試，也不等於統一且可重現的橫向評測。評估模型時，建議使用自己的程式碼庫、設計限制與失敗樣本，記錄提示詞、工具、重試次數、延遲與費用。

串接檢查清單

1. 確認使用的是官方直連或相容服務，並搭配相應的模型 ID、Base URL 與 Key。
2. 從較低推理強度開始，使用具代表性的任務逐步比較品質、延遲與帳單。
3. 多輪對話與 Agent 情境要保存完整 assistant message，並正確關聯工具結果。
4. 視覺訊息應以物件陣列建構；本機圖片使用官方支援的編碼或檔案流程。
5. 為工具執行設定權限範圍、參數檢查、逾時與失敗處理。
6. 上線前確認目前的模型目錄、可用區域與價格，避免沿用舊設定。

常見問題

Kimi K3.1 Pro 的 API 模型 ID 是什麼？

官方文件提供的 ID 是 kimi-k3.1-pro。高速型號為 kimi-k3.1-pro-highspeed，兩者不能混用在同一個模型設定中。

推理強度的預設值是多少？

官方文件列出 low、high、max，預設為 max；模型本身一律啟用思考模式。

可以直接傳送圖片 URL 嗎？

官方文件明確表示不支援公開網路圖片 URL。請使用視覺物件陣列與 Base64 Data URL，或依檔案流程使用 ms:// 參照。

為什麼 Agent 必須回傳完整 assistant message？

其中可能包含工具呼叫等結構化欄位。只儲存文字內容會遺失後續互動所需的資訊；工具結果也必須使用對應的 tool_call_id。

貴數智能是否提供 Kimi K3.1 Pro？

本站可用型號、路由與價格，請以模型價格頁目前顯示為準；官方直連能力不等於本站已提供，也不代表本站支援高速型號。

延伸閱讀

• 查看模型價格與可用型號
• 瀏覽貴數智能部落格

---

官方資料核驗日期：2026-10-24。模型能力、API 參數與存取條件可能更新，請以 Moonshot Kimi API 文件為準。