鉴权与 API Key

所有 JELLYTOKEN 推理 API 均需要 API Key。Key 在控制台创建，格式与传递方式如下。

---

1. Key 格式

uas_<32位随机字母数字>

示例：

uas_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6

• 前缀固定为 uas_
• 平台通过 Key 识别账号身份与 Key 状态（启用/禁用等）

---

2. 传递方式

以下三种方式任选其一（优先级从高到低）：

方式 1：Authorization Bearer（推荐）

Authorization: Bearer uas_你的密钥

符合 OAuth 2.0 习惯，OpenAI / Anthropic 官方 SDK 默认支持。

方式 2：X-API-Key

X-API-Key: uas_你的密钥

方式 3：Query 参数

GET /v1/models?api-key=uas_你的密钥

不推荐用 Query 传递 Key（易进入访问日志）。

---

3. 在 SDK 中配置

OpenAI Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://aiservice.jellytoken.com/v1"),
)

环境变量：

export API_KEY=uas_xxx
export API_BASE_URL=https://aiservice.jellytoken.com
export OPENAI_BASE_URL=$API_BASE_URL/v1

cURL

curl -H "Authorization: Bearer ${API_KEY}" \
     -H "Content-Type: application/json" \
     ...

---

4. 控制台 Key 生命周期

创建后明文仅展示一次；遗失完整 Key 时，在 密钥管理 通过 短信验证 再次复制。

---

5. 请求追踪（Request ID）

建议传入自定义请求 ID，便于与平台排查：

x-request-id: your-trace-id-001

或：

request-id: your-trace-id-001

成功调用推理类接口时，响应头会回显平台解析后的 ID（未传入则自动生成）：

x-request-id: your-trace-id-001

异步任务还可在 requestContext.request_id 中传入；提交、轮询、取消均会回显 x-request-id（见下文「异步任务」）。

会回显 x-request-id 的接口（常见）

通常不会回显 x-request-id 的接口

供应商原生接口兼容在鉴权失败等部分场景下，也可能没有 x-request-id。

异步任务

异步任务会跨多次 HTTP 调用，建议区分 taskId 与 x-request-id：

推荐做法：

1. 提交成功后保存 taskId 与 submit 响应头 x-request-id
2. 轮询、取消时可在请求头继续传入 submit 时的 x-request-id，便于在你方日志中串联多次调用
3. 联系平台支持时，提供 submit 的 x-request-id 或 taskId

其他说明

• 供应商原生接口兼容（/bailian、/ark）成功响应时，响应头 x-request-id 为平台 ID，不是百炼/火山方舟返回值；勿与响应 JSON 里的 id 混淆。
• JSON 中的 taskId 不是 Request ID：查单用 taskId，排查用响应头 x-request-id。
• 部分极早失败的响应（如路径不存在）可能没有 x-request-id。

---

6. 安全最佳实践

1. 服务端调用：Key 只放在后端，不要写入前端或移动端包体
2. 最小权限：按项目/环境拆分 Key
3. 轮换：定期新建 Key 并禁用旧 Key
4. 监控：结合 数据统计 发现异常峰值
5. 余额：关注 财务管理 余额，避免 insufficient_balance（402）

---

7. 鉴权失败示例

HTTP 401（未带 Key）：

{
  "error": {
    "message": "Missing API Key. Use \"Authorization: Bearer <api-key>\" ...",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

HTTP 401（Key 无效）：

{
  "error": {
    "message": "Invalid API Key",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

HTTP 403（无模型权限）：

{
  "error": {
    "message": "Model access denied",
    "type": "access_denied",
    "code": "access_denied"
  }
}

以上为 OpenAI 兼容入口（/v1/chat/completions 等）形态。Anthropic 入口（/v1/messages）结构为 { "type": "error", "error": { "type", "message" } }，稳定错误码含义相同；未带 Key 时 Anthropic 路径的 error.type 为 authentication_error。详见 错误码与限流。