快速入门

身份验证

用 API 密钥验证 TokenLab API 请求

API 密钥

模型调用和私有资源需要 API 密钥。GET /v1/models、GET /v1/models/{model} 等公开发现接口无需密钥;查询成功不能验证密钥是否可用,请按快速开始发送一次模型请求。请使用已经保存的完整密钥,列表中的前缀不能用于认证。

对于兼容 OpenAI 的端点,请按如下方式发送:

Authorization: Bearer sk-your-api-key

对于兼容 Anthropic 的 /v1/messages 请求,你也可以使用:

x-api-key: sk-your-api-key

兼容 Gemini 的 /v1beta/* 请求还可以用 x-goog-api-key: sk-your-api-key。优先用请求头,不要用 ?key= 查询参数,因为 URL 常会进入日志。

管理令牌

管理 API 使用单独的令牌:

Authorization: Bearer mt-your-management-token

管理令牌只用于 /v1/management/*。打开所选工作区的 API → Tokens 创建或替换令牌。创建或替换后,完整令牌只显示一次,请当场安全保存。

管理令牌不能调用模型,普通的 sk-... API 密钥也不能调用管理 API。

获取 API 密钥

  1. 登录 TokenLab Console
  2. 打开 API 密钥
  3. 创建一把新密钥
  4. 起一个好认的名字
  5. 马上复制。完整密钥只显示一次
  • 不要把 API 密钥写进前端代码
  • 不要把 API 密钥提交到版本库
  • 用环境变量或密钥管理器保存
  • 定期轮换密钥
  • 删掉不用的密钥

使用 API 密钥

环境变量和完整的首次请求见快速开始。按所选 API 格式使用对应 SDK,密钥只保留在服务端。

密钥设置

每把 API 密钥都可以在 Console 里设置,也可以用管理 API设置:

设置描述
消费上限不限额:密钥可以使用工作区全部余额。固定额度:用量达到指定金额后,密钥返回 402 quota_exceeded
允许的模型密钥只能调用列出的模型,其他模型返回 403 model_not_allowed。留空表示不在密钥层限制
交付方式这把密钥的请求使用 Auto、Verified 或 Official。留空则使用工作区默认值。见计费与定价
有效期到期后密钥返回 401 expired_api_key
状态inactive(暂停)的密钥返回 401 invalid_api_key;revoked(已撤销)的密钥不能再启用

密钥前缀

所有 TokenLab API 密钥都以 sk- 开头。

错误响应

状态码类型代码描述
401invalid_api_keyinvalid_api_keyAPI 密钥缺失、无效、已停用或撤销
401expired_api_keyexpired_api_keyAPI 密钥已过期
402insufficient_balanceinsufficient_balance账户余额不足
402quota_exceededquota_exceeded已达到 API 密钥用量上限
403permission_errormodel_not_allowed这把密钥不能使用所请求的模型
403permission_erroruser_suspended、account_restricted账号当前不能使用 API
429rate_limit_exceededrate_limit_exceeded同一 IP 认证失败次数过多。等待 Retry-After 并修正密钥,不要对 401 循环重试

示例:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

本页内容