鉴权与令牌

积木平台对外提供两类接口，鉴权方式不同：

绝大多数开发者只需要模型调用接口的 Bearer 令牌。管理接口面向控制台前端与运维脚本，本文仅说明其鉴权边界。 错误响应结构见 错误处理与请求追踪。

模型调用接口鉴权

所有 /v1、/v2 接口（含模型查询）都要求携带 API 令牌：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

获取令牌

1. 登录积木控制台，进入「令牌」页面。
2. 点击「添加令牌」，设置名称、额度与可选的模型范围限制。
3. 创建完成后，令牌会保存在列表中，可随时回来复制、编辑或删除。

令牌以 sk- 开头，后接 48 位字符。禁用或删除令牌后立即失效。 令牌的程序化创建与管理见 令牌管理。

使用示例

curl https://api.jimu.chat/v2/models \
  -H "Authorization: Bearer $JIMU_API_KEY"

import os
import requests

resp = requests.get(
    "https://api.jimu.chat/v2/models",
    headers={"Authorization": f"Bearer {os.environ['JIMU_API_KEY']}"},
)
print(resp.json())

const resp = await fetch("https://api.jimu.chat/v2/models", {
  headers: { Authorization: `Bearer ${process.env.JIMU_API_KEY}` },
});
console.log(await resp.json());

令牌安全须知

管理接口鉴权

/api 前缀的管理接口使用控制台登录会话（Cookie）鉴权，并额外要求请求头：

Jimu-Api-User: <用户 ID>

请求头中的用户 ID 必须与会话登录用户一致，否则返回 401。该机制用于防止跨用户操作。

程序化调用的鉴权获取链路

管理接口面向控制台前端，但也支持程序化访问，获取链分两步：

1. 登录拿会话：POST /api/user/login，请求体 {"username": "<用户名或邮箱>", "password": "<密码>"} —— 只有这两个字段，username 位同时接受用户名与邮箱。 成功后响应种下会话 Cookie，body 里不含任何令牌（浏览器/控制台场景到此为止，后续请求自动携带 Cookie）。 凭证错误时返回 HTTP 200 且 success 为 false，不是 4xx，判断成败要看 success 字段。 若该账号启用了两步验证，本次不完成登录，而是返回 {"success": true, "data": {"require_2fa": true}}， 需再调 POST /api/user/login/2fa 完成。
2. 换取 access token（脚本场景）：携带会话调 GET /api/user/self/token， 响应 data 就是 access token 字符串本身。 该接口每次调用都会重新生成并覆盖旧 token，旧 token 立即失效——不要在每次请求前都调它，取到后自行保存。

两步有强顺序依赖：没有会话直接调 GET /api/user/self/token 会返回 401。

登录验证码

登录接口可能要求人机校验。程序化调用场景建议在控制台完成登录后换取 access token，或使用积木客户端的 一键鉴权，不需要处理验证码。

拿到 access token 后，程序化调用管理接口的完整请求头组合：

Authorization: Bearer <ACCESS_TOKEN>   # GET /api/user/self/token 返回的 data 字符串
Jimu-Api-User: <USER_ID>                # 数字用户 ID（不是用户名），可从 GET /api/user/self 的响应中获取

两个头缺一不可：缺 Authorization 返回「未登录且未提供 access token」， 缺 Jimu-Api-User 返回「无权进行此操作，未提供 Jimu-Api-User」，格式不合法返回「无权进行此操作，Jimu-Api-User 格式错误」， ID 与会话用户不匹配同样返回 401。