兼容 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，这样客户端就不会一直重试。