认证与密钥

TokenToSea API 用 API Key 认证。本页说明如何在请求中携带密钥、各类密钥能调用什么、如何限制一把密钥的范围与花费，以及安全地轮换和删除密钥。

在请求中携带密钥#

HTTP 请求任选一种请求头：

• 密钥必须是 16–2048 个可打印 ASCII 字符，否则返回 401 invalid_api_key。
• 实时音频 WebSocket 只接受 Authorization: Bearer，见实时音频。
• 推理接口不接受查询参数，不要把密钥放在 URL 中。

密钥类型#

所有密钥都在控制台 → 我的 Key 管理。

第三方应用通过 TokenToSea 登录 获得的 OAuth 访问令牌只能调用 /api/v1/connect/* 委托接口，不能调用 api.tokentosea.com。

密钥何时有效#

每次请求都会实时检查以下条件，任一不满足即拒绝：

• 密钥未撤销、未删除、未过期；
• 密钥创建者的账号处于正常状态，并已完成手机号验证；
• 密钥是在「买家」身份下创建的全能密钥或模型密钥（调用模型时）。

每个工作区最多保留 50 把未撤销的全能密钥与模型密钥。

创建密钥#

1. 打开我的 Key，选择 新建密钥。
2. 密钥类型：全能密钥、模型密钥或工具密钥。
3. 调用范围（全能密钥与模型密钥）：全部模型、指定服务商或指定模型，见下文。
4. 限额与有效期：限额周期、token 上限、金额上限和到期时间，均可留空。
5. 保存显示的完整密钥。密钥在你的浏览器中用安全随机数生成，平台只接收并保存它的 SHA-256 摘要，之后无法再查看明文。可以下载为文本文件，或复制控制台提供的 cURL 示例直接测试。

调用范围#

全能密钥和模型密钥可以限制能调用的型号：

同时设置服务商和型号时，型号必须同时满足两个条件才可调用。服务商标识与 GET /v1/models 返回的 owned_by 一致：

范围外的型号不会出现在该密钥的 GET /v1/models 结果中；直接调用返回 403（错误码见错误处理）。

限额与有效期#

限额在受理请求时检查：窗口内已结算的用量、所有进行中调用的预留量，加上本次请求的预留量，超过上限即拒绝（403）。预留量是按请求上限估算的保守值，因此接近上限时，一个实际用量很小的请求也可能被拒绝。预留规则见计费与结算。

验证密钥#

GET /v1/models 返回这把密钥当前可调用的型号，是检查密钥是否有效、范围是否正确的最快方式。

curl https://api.tokentosea.com/v1/models \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY"

import os

import requests

response = requests.get(
    "https://api.tokentosea.com/v1/models",
    headers={"Authorization": f"Bearer {os.environ['TOKENTOSEA_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
models = response.json()["data"]
print(len(models), "个可调用型号")
for model in models[:5]:
    print(model["id"], model["owned_by"], model["region"], model["modality"])

const response = await fetch('https://api.tokentosea.com/v1/models', {
  headers: { Authorization: `Bearer ${process.env.TOKENTOSEA_API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { data } = await response.json();
console.log(`${data.length} 个可调用型号`);
for (const model of data.slice(0, 5)) console.log(model.id, model.owned_by, model.region, model.modality);

返回结构与字段说明见 GET /v1/models。注意不要与 https://tokentosea.com/api/v1/models 混淆，后者只列出订单专用密钥对应的已购模型。

撤销与删除#

轮换密钥#

不停机轮换的推荐步骤：

1. 新建一把范围和限额相同的密钥。
2. 把新密钥部署到所有调用方，并确认新请求都使用新密钥。
3. 等待旧密钥发起的异步任务完成并取回结果。
4. 撤销或删除旧密钥。

怀疑密钥泄露时不要等待，立即撤销，然后在账单中检查异常扣费。更多建议见安全最佳实践。

认证相关错误#

下一步#

• 用官方 SDK 接入
• 安全最佳实践
• 计费与结算