API 概览

本页列出所有推理接口共用的约定。各接口页面只描述该接口特有的参数和行为；遇到共性问题（鉴权、幂等、错误码、结果查询）时回到这里查。

基础地址#

api.tokentosea.com 是唯一公开入口。平台按请求体中的 model 精确路由到对应区域的执行节点（国内型号与海外型号使用不同节点），不做跨区域回退，也不自动重试。执行节点不接受直接访问。

鉴权#

在请求头中携带密钥，二选一：

Authorization: Bearer sk-relay_xxxxxxxx…
x-api-key: sk-relay_xxxxxxxx…

两个请求头同时存在时以 Authorization: Bearer 为准。实时音频 只接受 Authorization: Bearer。

密钥在 控制台 → 我的 Key 创建，明文只显示一次。服务端只保存密钥的 SHA-256 摘要，无法找回明文。每次请求都会重新校验：

• 密钥未撤销、未删除、未过期；
• 密钥所属账号状态正常、已绑定手机号，且密钥属于买家工作区；
• 请求的型号在密钥的调用范围内（指定型号或指定服务商，未限制则为全部型号）；
• 本次预留金额与 token 数不超过密钥在当前周期内的限额。

撤销或删除密钥立即生效，此后使用该密钥的请求返回 401；删除不可恢复。密钥的类型、范围和限额见鉴权与密钥。

格式校验：密钥必须是 16–2048 个可打印 ASCII 字符，否则直接返回 401 invalid_api_key。

请求格式#

multipart 请求中，messages、input、parameters、provider_options、content、voice_setting、audio_setting 可以写成 JSON 字符串（以 { 或 [ 开头），stream、n、duration、speed、sample_rate 按 JSON 字面量解析（例如 true、5）。

请求头#

幂等与请求 ID#

每个 POST 都可以携带 Idempotency-Key。格式为 16–128 个字符，只能包含字母、数字、_、.、:、-（正则 ^[\w.:-]{16,128}$），否则返回 400 idempotency_key_invalid。UUID 满足要求。

不带这个请求头时，网关自动生成 tts-auto-<uuid> 作为本次调用的键。无论哪种情况，响应都会在 X-Request-Id 和 X-TokenToSea-Request-Id 中返回本次使用的键。

结果只能用创建它的那把密钥查询。保存每次调用的键，网络中断或超时后用同一个键查询 GET /v1/results/{key}，或用同一个键、同一个请求体重发。不要换一个新键重新提交：那会被当作一次新的调用并再次计费。完整说明见幂等与重试。

响应#

对话、向量、重排等接口原样返回上游的成功响应体。生成文件的接口会把文件转存到私有存储，响应改为上面的规范化 data[]：只给出 TokenToSea 的签名下载链接与 asset_id，不暴露厂商的临时地址。少数型号的资源 ID 也会替换为平台 ID（例如 glm-tts-clone 返回的 voice、file_id，见 /v1/tools/invoke）。所有响应都不含费用字段，每次调用的实际扣费在 控制台 → 账单 中查看。

响应头#

结果信封#

异步受理、处理中、失败的调用，以及 GET /v1/results 的返回，都使用同一个结构：

{
  "id": "result_3f6c…（64 位十六进制）",
  "run_id": "cm2…",
  "status": "succeeded",
  "billing_status": "succeeded",
  "output": { "…": "完成后的输出" },
  "status_code": 200,
  "response_type": "application/json"
}

输出上限与预留#

• 未指定输出上限时，网关按型号的默认值补上：Chat Completions 使用该型号的输出字段（max_tokens 或 max_completion_tokens），Responses 使用 max_output_tokens；目前绝大多数型号的默认值为 4096。
• 输出上限必须在 1 到该型号的 max_output_tokens 之间，超出返回 400。
• 每次调用先按「最长输入 + 输出上限」与价格表中适用的最高档位预留金额，完成后按上游实际 usage 结算并释放余额。输出上限设得越大，需要的可用余额越多。
• 上游请求最长等待 21 分钟。耗时更长的媒体生成走异步任务。

计费规则（官方原价、原币种、汇率快照、6 位小数向上取整）见计费与余额。

错误#

网关生成的错误使用统一结构：

{
  "error": {
    "code": "model_operation_not_supported",
    "message": "可选：经过脱敏的上游错误描述，最长 300 字符"
  }
}

code 是稳定的机器可读值，请按它分支处理；message 只在上游返回了错误描述时出现，内容可能变化，不要解析。

完整的错误码表和处理建议见错误处理。

限制#

各项限制的完整说明见限制与配额。

接口索引#

使用官方 SDK#

协议兼容的接口可以直接使用厂商 SDK，只需替换地址与密钥：

使用 SDK 时注意：

1. 显式传入 Idempotency-Key。SDK 默认不发送它，遇到网络错误或部分状态码会自动重试；不带键的重试会被当作新的调用。Python 用 extra_headers={"Idempotency-Key": key}，Node.js 在第二个参数中传 { headers: { "Idempotency-Key": key } }。本文档示例同时把 SDK 的自动重试设为 0，由你的代码决定何时用同一个键重试。
2. 厂商扩展参数（如千问的 enable_thinking、DeepSeek / Kimi / 豆包的 thinking）在 OpenAI Python SDK 中放入 extra_body，Node.js 直接写在请求对象中。
3. 其余接口（图像、视频、语音、向量等）使用普通 HTTP 请求，本文档给出 requests 与 fetch 示例。

下一步#

• 快速开始：三步发出第一个请求
• GET /v1/models：查询型号能力与价格
• 结果查询：异步任务与断线恢复
• 错误处理：完整错误码与重试策略