身份验证
Half Off Dev API 密钥的用法：密钥可以放在哪四个位置、如何免费验证密钥、可能遇到的 401 错误，以及密钥的安全管理。
Half Off Dev 只有一种凭证：与预付余额绑定的 API 密钥。同一个密钥可以调用 Claude、GPT 和 Gemini，而且放在你的 SDK 或命令行客户端默认使用的请求头里就行，无需额外编写鉴权代码。
创建密钥#
在 API 密钥页面创建。密钥格式为 ho- 加 40 位字母和数字，只在创建时显示一次。Half Off Dev 只保存密钥的哈希值，所以密钥丢了就找不回来，只能吊销后重新创建。
本文档的所有示例都从 $HALFOFF_API_KEY 读取密钥：
export HALFOFF_API_KEY="ho-..."消费上限、模型白名单和过期时间的设置方法见 API 密钥。
密钥放在哪里#
不需要为 Half Off Dev 专门选择请求头：下面四种形式在所有端点上都有效，客户端默认怎么发就怎么发。
| 形式 | 示例 | 常见发送方 |
|---|---|---|
| Bearer 令牌 | Authorization: Bearer ho-... | OpenAI SDK、Codex CLI、Claude Code（ANTHROPIC_AUTH_TOKEN）、OpenAI 兼容应用 |
x-api-key 请求头 | x-api-key: ho-... | Anthropic SDK |
x-goog-api-key 请求头 | x-goog-api-key: ho-... | Google Gen AI SDK、Gemini CLI |
key 查询参数 | ?key=ho-... | Gemini REST 示例 |
如果一个请求同时带了多种，Half Off Dev 按以下顺序取第一个：Authorization: Bearer → x-api-key → x-goog-api-key → ?key=。
优先用请求头
写在 URL 里的密钥会被记进代理日志和终端历史记录。只有客户端无法设置请求头时，才考虑用 ?key=。
免费验证密钥#
计算 token 数会像真实请求一样校验密钥和模型，但不产生任何费用。返回 200 并带有 input_tokens，就说明密钥有效且有权调用该模型。
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": "这个密钥能用吗？"}]
}'公开端点#
模型目录对外公开，注册前就能查看模型 ID 和价格。发给这些端点的密钥会被忽略。
| 端点 | 返回内容 |
|---|---|
GET /v1/models | 全部模型，含上下文长度、价格和渠道组 |
GET /v1beta/models | 同一份目录，Gemini 格式 |
所有模型请求都需要密钥，计算 token 数也不例外。
401 错误#
密钥缺失、无效、已吊销或已过期时返回 401，响应体格式与你调用的 API 一致。
| 原因 | 错误信息 |
|---|---|
| 请求中没有密钥 | Missing API key |
| 密钥不存在或已吊销，或账户已停用 | Invalid or revoked API key |
| 密钥已过有效期 | This API key has expired |
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid or revoked API key"}}密钥本身有效，也可能因为自身的限制被拒绝：模型不在白名单内返回 403，消费上限用完返回 402，触发速率限制返回 429。这些限制的说明见 API 密钥，所有状态码见错误码。