API 参考 · Half Off Dev 文档

API 参考

通过 Half Off Dev 的原生接口调用 Claude、GPT 和 Gemini：基础地址、认证头、响应头、速率限制与重试规则。

Half Off Dev 没有自创一套新 API，而是在同一个域名下直接提供你的代码和 SDK 已经在用的三种接口：Anthropic Messages、OpenAI Chat Completions（以及 Responses）和 Gemini。一个密钥、一个预付费余额全部搞定。请求和响应都遵循各家官方的结构，官方 SDK 只需换掉 base URL 和密钥。Half Off Dev 额外加的东西很少：几个响应头、密钥级别的限制，以及自己的计费。

模型接口

每个接口的请求与响应结构，附 cURL、Python、Node.js 示例。

错误

状态码、三种格式的错误体，以及可直接用的重试代码。

认证

各 SDK 的密钥放在哪里。

快速开始

发出你的第一个半价请求。

基础地址#

所有接口都通过 HTTPS 从 https://halfoff.dev 提供。把 SDK 的 base URL 设成第二列的值即可。

接口	SDK base URL	端点
Anthropic Messages	`https://halfoff.dev`	`POST /v1/messages`、`POST /v1/messages/count_tokens`
OpenAI Chat Completions	`https://halfoff.dev/v1`	`POST /v1/chat/completions`
OpenAI Responses（GPT 模型）	`https://halfoff.dev/v1`	`POST /v1/responses`
Gemini	`https://halfoff.dev`	`POST /v1beta/models/{model}:generateContent`、`:streamGenerateContent`、`:countTokens`
模型列表	—	`GET /v1/models`、`GET /v1beta/models`

其他路径（例如 OpenAI 的 Embeddings 接口）一律返回 404。

认证#

所有端点都接受 Bearer 令牌，也接受各厂商自己的认证头，因此每个 SDK 用默认配置就行。

HTTP

Authorization: Bearer ho-...

请求头	谁会发送
`Authorization: Bearer ho-...`	OpenAI SDK、普通 HTTP 客户端
`x-api-key: ho-...`	Anthropic SDK
`x-goog-api-key: ho-...`	Google Gen AI SDK

模型列表无需密钥，其余端点都需要。详见认证。

请求与响应格式#

收发都是 JSON。 请求体用 JSON，并带上 content-type: application/json；响应同样是 JSON。
流式输出。 Anthropic 和 OpenAI 请求设 "stream": true 后返回服务器发送事件（text/event-stream）。Gemini 的 :streamGenerateContent 返回流式 JSON 数组，加上 ?alt=sse 则返回服务器发送事件，与 Google 官方一致。参阅流式输出。
CORS 对所有来源开放。 但这不代表适合在浏览器里直接调用：写进前端代码的密钥，任何人都能拿走。

响应头#

除了厂商自带的响应头，模型响应还会附带：

响应头	含义
`x-halfoff-request-id`	本次调用的唯一 ID，日志中可查。联系支持时请提供。
`x-halfoff-group`	处理本次调用的渠道分组
`x-halfoff-channel`	该渠道分组的简短说明，URL 编码
`x-halfoff-queued-ms`	等待容量的毫秒数（仅在发生等待时出现）
`retry-after`	出现在 `429` 响应中：重试前需要等待的秒数

版本#

各接口沿用厂商自己的版本机制。SDK 发什么就照发什么：Anthropic 用 anthropic-version 和 anthropic-beta，OpenAI 用 openai-beta，Gemini 与 Google 官方一样走 /v1beta 路径。Half Off Dev 只转发这些厂商头，不转发其他厂商头，因此依赖其他厂商头的功能无法使用。

响应中可能随时增加新字段，客户端请忽略不认识的字段。

速率限制#

限制	作用范围	超出后
密钥上设置的每分钟请求数和并发数	该密钥发出的请求	`429`，带 `retry-after`
模型容量	所有模型请求。短时突发会先排队等几秒。	`429`，通常带 `retry-after`

详见速率限制与故障转移和 API 密钥。

重试与幂等#

某个渠道出错时，Half Off Dev 会先在其他渠道上重试，全部失败才返回错误，所以你收到的 5xx 已经重试过了。即便如此，你这边也应该对 429 和 5xx 做指数退避重试，并遵守 retry-after。其他 4xx 需要修改请求，原样重发没有意义。官方 Anthropic 和 OpenAI SDK 默认重试两次；跑大批量任务时可以调大 max_retries（Node.js 中为 maxRetries）。

接口不支持幂等键，这在一种情况下很重要：在你这边超时的请求，服务端可能已经完成并扣费。 重发就可能付两次钱。长文本生成请给足客户端超时，或者改用流式。列出模型和计算 token 随时可以放心重复。

现成的重试函数见错误。

错误#

错误按你调用的接口格式返回，所以各 SDK 会抛出它们平常就会抛的异常。比如用已吊销的密钥发 OpenAI 格式请求，会收到：

JSON

{"error": {"message": "Invalid or revoked API key", "type": "authentication_error", "code": "authentication_error"}}

全部状态码及各格式的示例错误体见错误。