halfoff.dev文档
获取密钥
API 参考

模型接口

Half Off Dev 上 Messages、Chat Completions、Responses、Gemini 和模型列表接口的请求与响应参考，以及各接口支持的请求头。

下面这些就是各厂商自己的接口，由 https://halfoff.dev 提供。请求体和响应体遵循厂商的结构并原样透传，所以本页只列出最常用的参数，其余参数请查看各厂商的官方文档。故障转移、缓存等所有接口共有的行为，见网关如何工作。

所有端点都接受以下任一方式传递密钥：Authorization: Bearer、x-api-key、x-goog-api-key，或 ?key= 查询参数。错误按你调用的接口格式返回，参阅错误。

Response headers

x-halfoff-request-idstring

本次调用的 ID，例如 req_6f1c0b9e2d4a47a1b8c3d5e7，可在日志中查到。成功响应、容量不足的 429 和 502 错误都会带上。

x-halfoff-groupstring

处理本次调用的渠道分组。

x-halfoff-channelstring

该分组的渠道标签，URL 编码。

x-halfoff-queued-msinteger

等待容量的毫秒数。没有等待时不出现。

retry-afterinteger

需要等待的秒数。由密钥限制或容量繁忙引起的 429 响应会带上。

列出模型#

GET/v1/models

返回你当前可以调用的全部模型，包括上下文窗口、价格和提供服务的渠道分组。无需密钥。返回结构兼容 OpenAI 和 Anthropic SDK 的 models.list()。价格即 Half Off Dev 实际收取的价格，为官方定价的一半。字段说明见模型与价格。

Response fields

dataarray

每个模型一项。

has_moreboolean

始终为 false：一次返回完整列表。

curl https://halfoff.dev/v1/models
Response
{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-5.5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Sonnet 5.5",
      "created": 1700000000,
      "created_at": "2025-01-01T00:00:00Z",
      "owned_by": "Anthropic",
      "context_length": 1000000,
      "pricing": {
        "input": 1,
        "output": 5,
        "cache_read": 0.05,
        "cache_write": 1.25,
        "unit": "USD per 1M tokens"
      },
      "groups": ["claude-value"]
    }
  ],
  "has_more": false,
  "first_id": "claude-fable-5.1",
  "last_id": "gpt-5.6-luna"
}

创建消息#

POST/v1/messages

即 Anthropic Messages API。设置 stream 可接收服务器发送事件。扩展思考、工具调用和提示缓存的用法与 Anthropic 文档完全一致。指南：Anthropic Messages。

Headers

x-api-keystring必填

你的 Half Off Dev 密钥，也可以用 Authorization: Bearer。

anthropic-versionstring默认 2023-06-01

原样转发给模型。

anthropic-betastring

原样转发。

x-halfoff-groupstring

本次调用使用的渠道分组，例如 claude-value。密钥已绑定分组时忽略。

x-session-idstring

稳定的会话 id，让每一轮都发往持有该会话缓存的渠道。

Body parameters

modelstring必填

GET /v1/models 中的模型 id，例如 claude-sonnet-5.5。claude-sonnet-5-5 等写法会解析为同一个模型。

messagesarray必填

到目前为止的对话，user 与 assistant 轮次交替。

max_tokensinteger必填

最多生成多少 token。

systemstring or array

系统提示词。文本块支持 cache_control。

streamboolean默认 false

以服务器发送事件流式返回。

thinkingobject

扩展思考设置。

output_configobject

输出设置，如 effort 和 format。

toolsarray

模型可以调用的工具。

tool_choiceobject

模型如何选择工具。

metadataobject

请求元数据。

curl https://halfoff.dev/v1/messages \
  -H "x-api-key: $HALFOFF_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5.5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "给一个记账 App 起个名字。"}]
  }'
Response
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {"type": "text", "text": "叫“小账本”怎么样？"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 10
  }
}

计算消息 token#

POST/v1/messages/count_tokens

估算一个 Messages 请求会用多少输入 token，但不实际运行。免费，余额为零也能用。结果是近似值：适合检查上下文窗口和做预算，实际扣费以真实调用返回的 usage 为准。参阅 Anthropic 的 token 计数指南。

Headers

x-api-keystring必填

你的 Half Off Dev 密钥，也可以用 Authorization: Bearer。

x-halfoff-groupstring

用来校验模型的渠道分组。密钥已绑定分组时忽略。

Body parameters

modelstring必填

模型 id，与 POST /v1/messages 相同。

messagesarray必填

要计数的消息。

systemstring or array

一并计入的系统提示词。

toolsarray

一并计入的工具定义。

curl https://halfoff.dev/v1/messages/count_tokens \
  -H "x-api-key: $HALFOFF_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5.5",
       "messages": [{"role": "user", "content": "这段提示词有多长？"}]}'
Response
{
  "input_tokens": 16
}

创建对话补全#

POST/v1/chat/completions

即 OpenAI Chat Completions API。GET /v1/models 中的每个模型都支持这种格式，Claude 和 Gemini 也不例外。流式请求会自动带上 stream_options.include_usage: true，最后一个分块包含 usage。指南：OpenAI Chat Completions。

Headers

Authorizationstring必填

Bearer 加你的 Half Off Dev 密钥。

openai-betastring

原样转发。

x-halfoff-groupstring

本次调用使用的渠道分组，例如 gpt-value。密钥已绑定分组时忽略。

x-session-idstring

稳定的会话 id，让每一轮都发往持有该会话缓存的渠道。

Body parameters

modelstring必填

GET /v1/models 中的模型 id，例如 gpt-6.1-sol。

messagesarray必填

到目前为止的对话：system 或 developer、user、assistant 和 tool 消息。

streamboolean默认 false

以服务器发送事件流式返回，以 data: [DONE] 结束。

max_completion_tokensinteger

生成 token 的上限，含推理 token。

reasoning_effortstring

推理模型的思考力度，可选值因模型而异。

toolsarray

模型可以调用的函数。

tool_choicestring or object

模型如何选择函数。

response_formatobject

要求输出 JSON 或符合某个 JSON Schema。

prompt_cache_keystring

提高缓存命中率，同时作为路由用的会话 id。

userstring

终端用户 id。没有更具体的标识时，用作会话 id。

curl https://halfoff.dev/v1/chat/completions \
  -H "Authorization: Bearer $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [{"role": "user", "content": "把“早上好”翻译成法语。"}]
  }'
Response
{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1791700000,
  "model": "gpt-6.1-sol",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Bonjour."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 17,
    "completion_tokens": 3,
    "total_tokens": 20,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

创建响应#

POST/v1/responses

即 OpenAI Responses API，Codex CLI 用的就是它。仅支持 GPT 模型，其他模型返回 404。服务端不保存任何响应，所以每次都要在 input 中发送完整对话。指南：OpenAI Chat Completions。

Headers

Authorizationstring必填

Bearer 加你的 Half Off Dev 密钥。

openai-betastring

原样转发。

x-halfoff-groupstring

本次调用使用的渠道分组，例如 gpt-value。密钥已绑定分组时忽略。

x-session-idstring

稳定的会话 id，让每一轮都发往持有该会话缓存的渠道。

Body parameters

modelstring必填

GET /v1/models 中的 GPT 模型 id，例如 gpt-6.1-sol。

inputstring or array必填

一段提示词，或以输入项列表表示的对话。

instructionsstring

系统指令。响应会原样回显，未发送时为 null。

streamboolean默认 false

流式返回带类型的服务器发送事件，以携带 usage 的 response.completed 结束。

max_output_tokensinteger

生成 token 的上限，含推理 token。

reasoningobject

推理设置，如 effort，可选值因模型而异。

toolsarray

模型可以调用的函数及其他工具。

storeboolean

请传 false：响应不会保存以供之后读取。

prompt_cache_keystring

提高缓存命中率，同时作为路由用的会话 id。

curl https://halfoff.dev/v1/responses \
  -H "Authorization: Bearer $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "input": "用一句话给我一个 git 小技巧。",
    "store": false
  }'

生成内容#

POST/v1beta/models/{model}:generateContent

即 Gemini API。指南：Gemini。

Path parameters

modelstring必填

模型 id，例如 gemini-3.1-pro。Google 的写法如 gemini-3.1-pro-preview 会解析为同一个模型。

Headers

x-goog-api-keystring必填

你的 Half Off Dev 密钥，也可以用 Authorization: Bearer 或 ?key= 查询参数。

x-halfoff-groupstring

本次调用使用的渠道分组，例如 gemini-value。密钥已绑定分组时忽略。

x-session-idstring

稳定的会话 id，让每一轮都发往持有该会话缓存的渠道。

Body parameters

contentsarray必填

到目前为止的对话，由 user 和 model 轮次组成，每轮包含若干 parts。

systemInstructionobject

系统指令，形式为包含文本 part 的 content 对象。

generationConfigobject

输出设置：maxOutputTokens、temperature、responseMimeType、thinkingConfig 等。

toolsarray

函数声明及其他工具。

toolConfigobject

模型如何选择函数。

safetySettingsarray

按类别设置的安全阈值。

curl "https://halfoff.dev/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "什么是俳句？"}]}]}'
Response
{
  "candidates": [
    {
      "content": {"role": "model", "parts": [{"text": "俳句是一种三行日本短诗，音节为 5-7-5。"}]},
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 17,
    "thoughtsTokenCount": 80,
    "totalTokenCount": 102
  },
  "responseId": "mFHoaNC1Lo3HqtsP"
}

流式生成内容#

POST/v1beta/models/{model}:streamGenerateContent

请求与 generateContent 相同，只是以流的形式返回。加上 alt=sse 会得到服务器发送事件，每个事件是一段部分响应；SDK 会自动帮你加。不加的话，返回的是一个逐步输出的 JSON 数组。参阅流式输出。

Query parameters

altstring

设为 sse 以接收服务器发送事件。推荐使用。

路径参数、请求头和请求体与生成内容完全相同。

curl -N "https://halfoff.dev/v1beta/models/gemini-3-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "说出三原色。"}]}]}'
Response
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"红、黄"}]}}],"usageMetadata":{"promptTokenCount":6,"candidatesTokenCount":3,"totalTokenCount":9}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"、蓝。"}]},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":6,"candidatesTokenCount":6,"totalTokenCount":12}}

计算 Gemini token#

POST/v1beta/models/{model}:countTokens

估算 contents 中的 token 数，不运行模型。免费，余额为零也能用。结果是近似值。Gemini 参考文档。

Body parameters

contentsarray必填

要计数的内容，结构与 generateContent 相同。

路径参数和请求头与生成内容完全相同。

curl "https://halfoff.dev/v1beta/models/gemini-3.1-pro:countTokens" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "这段提示词有多长？"}]}]}'
Response
{
  "totalTokens": 8
}

以 Gemini 格式列出模型#

GET/v1beta/models

列出可通过 Gemini 端点调用的模型，结构与 Gemini API 一致。无需密钥。Google Gen AI SDK 的 models.list() 调用的就是它。价格只在 GET /v1/models 中提供。

cURL
curl https://halfoff.dev/v1beta/models
Response
{
  "models": [
    {
      "name": "models/gemini-3.1-pro",
      "displayName": "Gemini 3.1 Pro",
      "inputTokenLimit": 1048576,
      "supportedGenerationMethods": ["generateContent", "streamGenerateContent", "countTokens"]
    }
  ]
}
← 上一页
简介
API 参考
下一页 →
错误
API 参考