相容 OpenAI 的 API

這是什麼

相容 OpenAI 的 API 讓支援 OpenAI chat completions 格式的工具使用 ToRun 的聊天模型，並從你的 ToRun 帳戶付費。opencode 等程式開發代理可以在使用 ToRun 的 MCP 工具的同時，把 ToRun 當作它的模型供應商。

位址與登入

使用與 MCP 伺服器相同的開發者金鑰：請參閱開發者金鑰。在加入相容 OpenAI 的 API 之前建立的金鑰會收到 403 insufficient_scope。金鑰的權限永遠不會改變，所以請建立一把新金鑰。

這個 API 有兩個端點：GET /v1/models 和 POST /v1/chat/completions。/v1 下的任何其他路徑都會回應 404 not_found。

模型

GET /v1/models 會先列出 torun/auto，再依模型 ID 列出你的方案可以使用的所有文字模型。每個模型會說明：

• 它能讀取多少文字（context_length），以及能寫多長的回覆（max_completion_tokens），
• 它能否呼叫工具（supports_tools）和讀取圖片（supports_vision），
• 它以每百萬 token 多少 Runs 計的價格（pricing：input 和 output）。

torun/auto 讓 ToRun 為每個請求挑選模型：請求中有圖片時挑選能讀取圖片的模型，送出 tools 時挑選能呼叫工具的模型。

Chat completions

POST /v1/chat/completions 接受：

• messages，角色包括 system、developer（視同 system）、user、assistant 和 tool，
• tools 和 tool_choice（auto、none、required 或一個指定的函式）：你的工具自己的工具會以工具呼叫的形式回傳給它，ToRun 從不執行它們，
• 帶有 json_object 的 response_format。json_schema 會被接受，回覆也是 JSON，但不會強制套用該 schema，
• temperature（0 到 2）、top_p（0 到 1）、max_completion_tokens 或 max_tokens、stop（最多 4 個序列）、seed 和 reasoning_effort，
• stream 和 stream_options.include_usage。

大於 1 的 n、logprobs、top_logprobs、音訊以及文字以外的任何輸出都會以 400 unsupported_parameter 拒絕，而不是被忽略。

圖片

以內嵌方式傳送圖片，也就是在 image_url 部分中使用 data:image/...;base64,...，每個請求最多 20 MB。以連結傳送的圖片會以 400 image_url_not_supported 拒絕：ToRun 不會擷取它。與在應用程式中一樣，圖片會經過安全檢查。

串流

使用 "stream": true 時，回覆會以 chat.completion.chunk 形式的 server-sent events 送達：

• 第一個區塊帶有 assistant 角色，工具呼叫會帶著各自的 index 串流傳送。
• 沒有內容要傳送時，每 15 秒會收到一行 : keepalive 註解；SSE 剖析器會略過它。
• data: [DONE] 表示成功的串流結束。
• 使用 stream_options.include_usage 時，最後一個區塊的 choices 為空，並帶有 usage。
• 串流開始後發生的失敗會以一個 data: {"error": ...} 事件送達，沒有 [DONE]。

非串流呼叫會在 110 秒後以 504 timeout 終止。請以 "stream": true 傳送長請求。

用量

usage 包含 prompt_tokens、completion_tokens、total_tokens、prompt_tokens_details.cached_tokens 和 completion_tokens_details.reasoning_tokens，以及 torun_credits：這次呼叫花費了多少 Runs。

在 opencode 中使用

開發者頁面上的 opencode 設定會在 MCP 伺服器旁將 ToRun 加入為模型供應商：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "torun": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ToRun",
      "options": { "baseURL": "https://mcp.torun.ai/v1", "apiKey": "{env:TORUN_API_KEY}" },
      "models": { "torun/auto": { "name": "ToRun Auto" } }
    }
  }
}

任何其他支援 OpenAI 聊天 API 的工具都以同樣的方式運作。該頁面的 OpenAI API 分頁顯示了這個呼叫：

curl https://mcp.torun.ai/v1/chat/completions \
  -H "Authorization: Bearer $TORUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "torun/auto", "messages": [{"role": "user", "content": "Hello"}]}'

呼叫如何付費

API 呼叫花費的 Runs 與在應用程式中進行相同使用時相同。只有付費資金會支付這些呼叫：先是你的付費方案額度，如果你在金鑰上允許，再是你的錢包。免費額度從不支付 API 呼叫。金鑰的每月和每日上限同樣適用，回覆也會像聊天回覆一樣經過安全檢查。

限制

每把金鑰每分鐘可以向此 API 傳送 60 個請求，並同時執行 4 個 completions。超過時，API 會回應 429 rate_limit_exceeded，並帶有 Retry-After 標頭。

錯誤

每個錯誤的形式為 {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}。message 會使用請求的 Accept-Language 標頭所要求的語言。

無法付費的請求會收到 402，而不是 429，這樣用戶端就不會一直重試。