快速开始

公共信息

适用于所有 TokenRa 请求的通用规则：请求地址、鉴权方式，以及错误处理。

BASE URL

Base URL

用途	Base URL	适用客户端
兼容 OpenAI：对话、Responses、图片、视频	`https://tokenra.io/v1`	OpenAI SDK、LangChain 等大多数工具
Anthropic Messages	`https://tokenra.io`	Anthropic SDK、Claude Code（会自动拼接 `/v1/messages`）
你的 Key 可用的模型	`GET https://tokenra.io/v1/models`	任意 HTTP 客户端

AUTH

鉴权

方式	写法	适用范围
Bearer Token（推荐）	`Authorization: Bearer sk-...`	所有接口
x-api-key	`x-api-key: sk-...`	`/v1/messages` 和 `/v1/models`（Anthropic 格式）
Google 风格	`x-goog-api-key` 请求头或 `?key=` 参数	Gemini 原生路径 `/v1beta/models`

只在服务端使用 Key

不要把 Key 写进浏览器或移动端代码。Key 泄露后，请在控制台删除并重新创建。

CONVENTIONS

请求约定

请求体为 UTF-8 编码的 JSON，带 Content-Type: application/json；图片编辑接口使用 multipart/form-data。
流式响应为 SSE：逐行返回 data:，最后一行是 data: [DONE]。
推理模型和图片生成可能需要几十秒，客户端超时建议不低于 120 秒，或使用流式输出。

ASYNC

异步任务（视频）

视频接口会立即返回 task_id，之后每 10–15 秒查询 GET /v1/video/generations/{task_id}，直到进入终态。

data.status	含义
`NOT_START` / `SUBMITTED` / `QUEUED`	已受理，等待开始。
`IN_PROGRESS`	生成中。
`SUCCESS`	完成，下载 `result_url`。
`FAILURE`	失败，原因见 `fail_reason`，预扣费用会退回。

ERRORS

错误码

错误以 error 对象返回，message 末尾带有 request id，联系支持时请提供。

{
  "error": {
    "message": "Invalid token (request id: 202610231454005716007698268d9d6k7qSUTYb)",
    "type": "new_api_error",
    "code": ""
  }
}

HTTP	error.code	含义	处理建议
`401`	—	API Key 缺失、错误或已删除，message 为 `Invalid token`。	检查 `Authorization: Bearer` 请求头，并在控制台核对 Key。
`400`	—	请求体不是合法 JSON。	修正 JSON，并带上 `Content-Type: application/json`。
`500`	`invalid_request`	缺少必填字段，例如未传 `messages`。	按 message 补全字段，重试无效。
`403`	`insufficient_user_quota`	账户余额或套餐额度不足。	在控制台充值后重试。
`503`	`model_not_found`	模型 ID 不存在，或你的分组下没有可用渠道。	在模型列表或 `GET /v1/models` 中核对模型 ID。
`429`	—	请求过于频繁。	指数退避后重试。
`5xx`	—	上游服务商出错或超时。	稍后重试几次；持续出错时保留 request id 联系支持。

RETRIES

限流与重试

429 和 5xx 可按指数退避重试（例如 1 秒、2 秒、4 秒），重试几次后停止。
400、401、403 和 model_not_found 不要重试，先修正请求。
同一 IP 并发请求过多时，可能收到 HTTP 503 和一个 HTML 页面而不是 JSON。请降低并发、退避后重试，并且不要假设所有错误响应都是 JSON。

BILLING

用量与计费

文本模型在 usage 中返回输入、输出、缓存命中和推理 token；图片模型按次计费，视频模型按任务计费。
请求失败时预扣的额度会退回，最终以控制台的使用日志为准。
各模型的实时价格见模型广场。