API 参考¶

基础地址¶

用途	配置值
API 基础地址、Claude Code `ANTHROPIC_BASE_URL`	`https://api.routefast.ai`
OpenAI SDK、Codex provider 的 Base URL	`https://api.routefast.ai/v1`

以下路径均相对于 API 基础地址；客户端自动追加路径时，注意不要重复添加 /v1。

鉴权¶

推荐使用 Bearer Token：

Authorization: Bearer sk-routefast-...

Anthropic 兼容客户端也可使用：

x-api-key: sk-routefast-...

使用其中一种正确的鉴权方式即可。密钥只通过 HTTPS 发送，不要放在 URL 查询参数中；服务端会拒绝查询参数里的 key 或 api_key。

文档覆盖的端点¶

方法	路径	用途	协议
`GET`	`/v1/models`	获取当前密钥对应模型目录	OpenAI 兼容
`POST`	`/v1/responses`	GPT 请求与 Codex 接入	OpenAI Responses
`POST`	`/v1/chat/completions`	兼容聊天客户端	OpenAI Chat Completions
`POST`	`/v1/messages`	Claude 消息请求和 Claude Code	Anthropic Messages
`POST`	`/v1/messages/count_tokens`	请求前预估消息 Token	Anthropic 兼容
`GET`	`/v1/sub2api/billing`	查询当前密钥的生效计费倍率	RouteFast/sub2api 扩展

接口使用说明¶

场景	文档用法	注意事项
GPT 文本、Claude 文本	下方最小请求	使用对应分组的 Key，并填写模型目录中的精确模型 ID
Codex CLI、Claude Code	对应客户端接入教程	按教程配置地址、密钥与模型，首次使用先发送简单文本请求
HTTP/SSE 流式输出	请求增加 `stream: true`	检查流内完成或错误事件，不能仅凭 HTTP `200` 判断成功
模型列表、计费倍率	上表对应 `GET` 接口	返回内容取决于 Key 和实例配置
Token 预估	`POST /v1/messages/count_tokens`	预估结果不是最终计费依据
工具调用、结构化输出、图片输入、扩展思考、缓存选项	按实际模型和协议选用	支持情况取决于模型、分组与上游配置，使用前确认具体能力
WebSocket、服务端状态延续、其他端点	不作为当前入门路径	使用前联系支持确认适用条件

本文介绍 GPT/Codex 与 Claude/Claude Code 接入。图片生成、音频、视频、微调、Batch 或 Assistants 等服务不在本文介绍范围；如有相关需求，请先联系支持确认。

OpenAI Responses¶

POST /v1/responses
Authorization: Bearer <ROUTEFAST_API_KEY>
Content-Type: application/json

最小请求：

{
  "model": "gpt-5.6-terra",
  "input": "你好"
}

流式调用在请求体中增加 "stream": true。完整 SDK 示例见 GPT API 接入。

示例模型必须先在你的 Key 对应模型目录中确认。模型或上游不支持的可选字段可能返回 4xx；工具、图片输入、结构化输出和状态延续等应按具体模型验证，不能从一条文本请求成功推断全部能力可用。

OpenAI Chat Completions¶

POST /v1/chat/completions
Authorization: Bearer <ROUTEFAST_API_KEY>
Content-Type: application/json

最小请求：

{
  "model": "gpt-5.6-terra",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}

Anthropic Messages¶

POST /v1/messages
Authorization: Bearer <ROUTEFAST_API_KEY>
anthropic-version: 2023-06-01
Content-Type: application/json

最小请求：

{
  "model": "claude-sonnet-5",
  "max_tokens": 256,
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}

使用 Anthropic 客户端时保留其协议版本头；SDK 或 Claude Code 通常会自动发送。具体设置见 Claude Code 接入。

模型列表¶

GET /v1/models
Authorization: Bearer <ROUTEFAST_API_KEY>

返回结果与密钥分组和服务端模型配置有关。文档中的模型表是快照，接入时优先检查这个接口。模型出现在列表中表示被列入当前目录，不保证请求时上游一定有容量。

不带 client_version 的常规请求用于获取 OpenAI 风格模型列表；客户端可能使用带版本参数的专用模型目录，不要把两种返回格式混用。

计费倍率¶

GET /v1/sub2api/billing
Authorization: Bearer <ROUTEFAST_API_KEY>

响应示例：

{
  "object": "sub2api.key_billing",
  "schema_version": 1,
  "billing_scope": "token",
  "group_rate_multiplier": 0.5,
  "resolved_rate_multiplier": 0.5,
  "peak_rate_enabled": false,
  "effective_rate_multiplier": 0.5,
  "observed_at": "2026-09-07T00:00:00Z"
}

示例只说明字段形态，不代表你的实际倍率。该接口不返回账户余额、完整价格表或全部限额。详情见计费与用量和额度、并发与限流。

错误格式与状态码¶

错误可能产生于入口鉴权、网关处理或上游，不是所有响应都使用同一个 JSON 外壳。客户端应保留 HTTP 状态、code、error.code、error.type 及脱敏消息。

入口鉴权错误示例：

{
  "code": "INVALID_API_KEY",
  "message": "Invalid API key"
}

Responses 路径的 Key 总额度耗尽示例：

{
  "error": {
    "message": "API key 额度已用完",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

不同端点与错误透传配置可能使用其他响应形态。

状态码	常见含义	建议
`400`	参数、格式或上下文错误	检查请求体、模型字段和协议
`401`	缺少/错误/停用的 Key，或用户状态异常	先修正凭证和账户状态
`403`	分组或 IP 权限、Key 过期、余额不足等	根据具体错误码处理；充值不解决所有 `403`
`404`	错误路径、未支持端点，或 `model_not_found`	核对 Base URL、请求方法和精确模型 ID
`429`	Key 额度、费用窗口、RPM、并发或上游限制	先判断类型；额度耗尽时不要循环重试
`502`	上游异常，也可能是上游鉴权失败	保留错误体；持续失败联系支持
`503`	临时容量、鉴权服务或计费服务不可用	有限退避，持续失败联系支持

不要依赖错误文案做稳定的程序分支；优先使用状态码和机器可读错误字段。详细映射见故障排查。

流式响应不只检查 HTTP 状态¶

SSE 一旦发送响应头或心跳，HTTP 状态可能已经固定为 200。此后发生的错误会写在流内：Responses 路径可能以 response.failed 终止，Messages 等路径可能返回错误事件或 type: error 数据。

客户端需要识别正常完成、失败和未完成状态。收到心跳、部分文字或 HTTP 200 都不能单独证明整次生成成功；网络 EOF 也不能替代协议的完成信号。重发前结合用量记录检查原请求，避免自动重复执行整个任务。

请求 ID¶

优先保存服务端响应头中的 X-Client-Request-ID，以及实际返回的其他请求 ID。服务端会生成关联 ID；不要假定你发送的同名请求头会原样成为服务端 ID。

应用可以另外维护自己的本地追踪号，并记录它与响应 ID 的对应关系。请求 ID 用于排障，不是重试去重或免除重复计费的幂等保证。报障需要时间与时区、响应 ID、端点、模型、HTTP 状态及脱敏错误体，见故障排查中的报障模板。