鉴权与 API Key | 同思智算

网关 API Key（gk_）、Authorization Bearer 头、能力 scope 与 401/403 鉴权错误。

无界模型云的所有 /v1/* 调用都用网关 API Key 鉴权——Key 形态、Authorization 头、能力 scope 与鉴权错误码如下。

API Key 形态

API Key 以 gk_ 为前缀，在控制台 https://ai.tos.run 创建。Key 在创建时完整展示一次，请妥善保存。控制台与用量统计中只展示 Key 的前缀（前若干位），不会再次展示完整明文。

gk_1a2b3c4d5e6f7a8b9c0d1e2f

鉴权头

所有 API 调用通过 HTTP Authorization 头传入 Key，使用 Bearer 方案：

Authorization: Bearer gk_xxxxxxxxxxxxxx

必须带 Bearer 方案前缀。裸写 gk_...（不带 Bearer ）会被拒绝。鉴权失败返回 401，错误码 missing_api_key。

curl "https://api.tos.run/v1/chat/completions?provider=anthropic" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-x",
    "messages": [{ "role": "user", "content": "你好" }]
  }'

import os, requests

resp = requests.post(
    "https://api.tos.run/v1/chat/completions",
    params={"provider": "anthropic"},
    headers={"Authorization": f"Bearer {os.environ['TOS_API_KEY']}"},
    json={
        "model": "claude-sonnet-4-x",
        "messages": [{"role": "user", "content": "你好"}],
    },
)
print(resp.status_code, resp.json())

const resp = await fetch(
  "https://api.tos.run/v1/chat/completions?provider=anthropic",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TOS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "claude-sonnet-4-x",
      messages: [{ role: "user", content: "你好" }],
    }),
  },
);
console.log(resp.status, await resp.json());

能力 scope

每个 API Key 按能力（capability）授权一组 scope。网关按请求路径判断需要哪个 scope，Key 不含对应 scope 时返回 403。

端点	需要的 scope
`/v1/chat/completions`	`ai:chat`
`/v1/messages`	`ai:chat`
`/v1/responses`	`ai:chat`
`/v1/images/generations`	`ai:image`
`/v1/images/edits`	`ai:image`
`/v1/audio/transcriptions`（数据面）/ `/v1/transcribe`（master）	`ai:asr`
`/v1/audio/speech`（数据面）/ `/v1/synthesize`（master）	`ai:tts`
`/v1/recognize`（master）	`ai:ocr`
`/v1/vision-segment/predictions`（master）	`ai:vision-segment`
`/v1/vision-segment/video`（master）	`ai:vision-segment`

对话三件套（/v1/chat/completions、/v1/messages、/v1/responses）在数据面要求 ai:chat scope。建议给对话 Key 同时授予 ai:chat 与 ai:llm，以兼容不同部署形态。

通配 scope ai:* 授予对所有能力的访问权——含 ai:* 的 Key 不再逐路径检查具体能力 scope。

按最小权限原则给 Key 授权：只面向对话的应用授予 ai:llm，只生图的应用授予 ai:image，避免一把 ai:* 的 Key 在所有应用间共享。给不同应用使用不同的 Key，便于审计、限额和停用。

鉴权错误码

数据面鉴权失败时返回扁平结构的错误体：顶层 error 字段即错误码，message 是人类可读描述（注意这与业务错误的嵌套 { error: { type, message } } 不同）。

HTTP 状态	错误码（`error`）	含义
`401`	`missing_api_key`	缺少 API key，或 `Authorization` 头不是 `Bearer gk_...` 形态
`401`	`invalid_api_key`	API key 无效或已被吊销
`403`	`insufficient_scope`	Key 有效，但缺少当前路径所需的能力 scope

401 缺少 Key 的实际返回：

{
  "error": "missing_api_key",
  "message": "API key required (Authorization: Bearer gk_...)"
}

403 示例（用一把只有 ai:chat 的 Key 调用图像接口）：

{
  "error": "insufficient_scope",
  "message": "API key lacks scope for /v1/images/generations"
}

排查建议：

收到 missing_api_key：确认请求带了 Authorization: Bearer gk_...，注意 Bearer 前缀和空格。
收到 invalid_api_key：确认 Key 没拼错、未过期、未在控制台被吊销。
收到 insufficient_scope：在控制台给该 Key 补上对应能力 scope（如调用图像接口需 ai:image），或换一把权限足够的 Key。

接入建议

生产环境把 API Key 放在服务端，不要暴露到浏览器或客户端。
给不同应用使用不同 Key，便于审计、限额与停用。
按能力最小授权，避免长期共享 ai:* 的高权限 Key。

更多请见快速开始与模型发现与目录。