跳转到主要内容

​
Key 格式

所有 ByteSpike key 都以 sk-byts- 开头。在 Console → API keys 生成；明文密钥只在 创建时展示一次，之后被掩码。要事后取回明文，在 console 用 per-key 揭示 流程，或者在管理 API 上调 GET /v1/keys/{id}/reveal。 
sk-byts-AbCdEf0123456789...
请把 key 当作数据库密码对待。不要 commit 到 git、不要在服务端日志里打出来、 不要塞到浏览器 bundle 里。网关在数据库里只存前缀-后缀对的 hash —— key 泄露 后秒级可撤销，但泄露内容本身不可恢复。

​
各协议的请求头布局

ByteSpike 接受你所调用协议的原生鉴权头。同一个 key 三种协议都能用 —— 挑你 客户端能讲的那种。
协议请求头示例
Anthropic Messagesx-api-keyx-api-key: sk-byts-...
OpenAI Chat Completions / ResponsesAuthorization: BearerAuthorization: Bearer sk-byts-...
Gemini Nativequery 参数 ?key=?key=sk-byts-...
你也可以在 Anthropic 端点上发 Authorization: Bearer，或者在 OpenAI 端点上 发 x-api-key —— 网关在两条路由上都接受两种形式。如果同时存在，x-api-key 优先。 网关绝不读取请求 body 来发现凭证。

​
Per-key 控制

每个 key 都有自己的配置，创建时设定，之后可在 console 修改：
字段作用默认值
nameconsole 里的显示标签 —— 挑个好记的，比如 prod-vision-pipeline必填
group_id该 key 可触达的路由分组。选 claude-default 意味着 key 只能调 Claude 模型；default 路由全部模型。详见 模型。必填（每 key 单值）
quota终身消费的硬上限（USD）。0 = 不限。0
expires_in_daysN 天后自动撤销。永不
rate_limit_5h滚动 5 小时窗口的 USD 上限。0 = 不限。0
rate_limit_1d滚动 24 小时窗口的 USD 上限。0
rate_limit_7d滚动 7 天窗口的 USD 上限。0
ip_whitelist允许该 key 调用的 CIDR 块列表。空 = 全部允许。[]
ip_blacklist明确拒绝的 CIDR 块列表。[]
custom_key可选 —— 自己指定密文字符串而不是让网关生成。在从其他 provider 的 key 体系迁移时有用。网关生成
一个 key 只绑定一个 路由分组 —— 目前没有多分组绑定。如果你需要单个客户端 访问多个分组（例如 Claude + DeepSeek），就按分组各建一把 key，按请求选用； 或者调用配置了跨分组兜底的模型。

​
Key 生命周期

​
创建

curl https://llm.bytespike.ai/api/v1/keys \
  -H "x-api-key: $BYTESPIKE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "prod-vision-pipeline",
    "group_id": 11,
    "quota": 200,
    "rate_limit_5h": 50,
    "ip_whitelist": ["52.0.0.0/8"],
    "expires_in_days": 90
  }'
响应包含明文 key —— 拿到一次后加密存好。后续通过 GET /v1/keys 读到的是 掩码形式（sk-byts-...****1234）。

​
轮换

POST /v1/keys/{id}/rotate 原地重新生成密文。旧密文在轮换时立即失效 —— 没有重叠窗口。部署时需要相应安排：先更新 config + 在新密文上验证，再触发 rotate；或者用两把 key 错峰轮换。

​
揭示

GET /v1/keys/{id}/reveal 返回你已经有权访问的 key 的明文。适用于运维者 丢失自己副本但仍持有有效会话的恢复场景。

​
删除

DELETE /v1/keys/{id} —— 立即生效，不可撤销。正在 in-flight 的请求会在 流中被 401 中断。

​
失败场景

错误信封的格式匹配你调用的协议。Anthropic 形式： 
{
  "type": "error",
  "error": { "type": "authentication_error", "message": "invalid x-api-key" }
}
OpenAI 形式： 
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "invalid x-api-key"
  }
}
场景HTTPOpenAI codeAnthropic type
key 缺失或格式错401invalid_api_keyauthentication_error
key 已撤销 / 删除401invalid_api_keyauthentication_error
key 有效但已过期401invalid_api_keyauthentication_error
IP 不在 ip_whitelist 内403permission_deniedpermission_error
IP 命中 ip_blacklist403permission_deniedpermission_error
配额 / 速率限制耗尽402insufficient_balancepermission_error
模型不在 key 的路由分组内503api_error (no available account)api_error
以上任何一种都不计费 —— 失败不消耗 credits。

​
通过程序管理 key

完整的管理接口在 /api/v1/keys 下。Cookie 鉴权（来自 console）和 x-api-key 鉴权（用任意活动 key）都支持。
Verb + 路径作用
GET /api/v1/keys列出你的 key（密文掩码）
GET /api/v1/keys/{id}单个 key（掩码）
GET /api/v1/keys/{id}/reveal明文（慎用）
POST /api/v1/keys创建
PUT /api/v1/keys/{id}更新 name / quota / 速率限制 / IP 规则 / 状态
POST /api/v1/keys/{id}/rotate原地重新生成密文
DELETE /api/v1/keys/{id}硬删除

​
上线前测试 key

Console → Models 每个模型旁都 有 Test 按钮。Console 会从你的 key 集合中自动挑出正确的那把 —— 即 group_id 与该模型实际匹配的那把。这里返回 200 就证明 key + 分组 + 模型 三者匹配，再接入客户端。 也可以从 API 触发测试拨号： 
curl https://llm.bytespike.ai/api/v1/dial/test \
  -H "Cookie: $SESSION_COOKIE" \
  -d '{"model": "claude-sonnet-4-6", "protocol": "anthropic", "keyId": 42}'