对接方入口：第三方接入指南（5 分钟接入） · 完整 v1 API 参考（24 端点）

baozi API 文档中心

通过统一接口调用全球 70+ 大模型。OpenAI 兼容协议，三方通过 M2M OAuth 2.0 client_credentials 接入，5 分钟拿到第一批 Key。

📚 文档清单（4 篇，全部对齐 v1 API）

📘 v1 API 参考（主文档） →

公开给三方。24 端点完整定义 + OAuth 2.0 client_credentials 鉴权 + 5 scope 矩阵 + 请求/响应示例 + 错误码对照表。

📗 三方接入指南 →

公开给三方。6 步 curl 完整跑通「拿 token → 查套餐 → 下单 → 创 Key → 列 Key → 撤销 Key」。推荐从这里开始。

📙 admin-packages（内部） →

不公开给三方。/api/v1/admin/* 端点（用户 / 配额 / grant），需要 baozi:admin role。查询套餐 GET /api/v1/packages 是公开接口，不在本文档范围，详见 v1 API 参考。

📕 API 规范化现状 →

K-275 改造记录。24 端点自检表 + 老 /api/admin/* → 新 /api/v1/admin/* 301/307 重定向清单 + URL 自检脚本。

🔐 三方鉴权：M2M OAuth 2.0 client_credentials

所有三方接入必须用 OAuth 2.0 client_credentials 拿 access token，再用 token 调业务端点。不支持 OIDC 用户流程（OIDC 是 baozi 个人用户登录用的）。

5 个 scope（写在 m2m_clients.scopes JSON 数组里）

scope	端点
`packages:read`	GET /api/v1/packages · GET /api/v1/packages/:id（公开，其实不需要 token）
`tokens:read`	GET /api/v1/tokens · GET /api/v1/tokens/:id · GET /api/v1/m2m/me
`tokens:write`	POST /api/v1/tokens · DELETE /api/v1/tokens/:id
`orders:read`	GET /api/v1/orders · GET /api/v1/orders/:id
`orders:write`	POST /api/v1/orders

固定测试 client（5 scope 全开，对接方立即可用）

client_id:     baozi-e2e-fixed-2026
client_secret: 找助手要（trust@ohoooho.com）
scopes:        packages:read · tokens:read · tokens:write · orders:read · orders:write（全开）
token 有效期:   2 小时
DB note:       FIXED · DO NOT DELETE（不轮换）

5 分钟接入 curl（完整 6 步）

# 1. 拿 access_token
TOKEN=$(curl -s -X POST https://baozi.ohoooho.com/api/v1/m2m/auth \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"baozi-e2e-fixed-2026","client_secret":"YOUR_SECRET"}' \
  | jq -r .data.access_token)

# 2. 查套餐（公开，但带 token 也行）
curl -s https://baozi.ohoooho.com/api/v1/packages \
  -H "Authorization: Bearer $TOKEN" | jq '.data | length'
# → 21 个套餐

# 3. 创订单 + 创 Key
curl -s -X POST https://baozi.ohoooho.com/api/v1/tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"package_id":"bz-chat","end_user_email":"end-user@example.com","billing_period":"month"}'

# 4. 列 Key
curl -s "https://baozi.ohoooho.com/api/v1/tokens?end_user_email=end-user@example.com" \
  -H "Authorization: Bearer $TOKEN"

# 5. 撤销 Key
curl -s -X DELETE "https://baozi.ohoooho.com/api/v1/tokens/$TOKEN_ID" \
  -H "Authorization: Bearer $TOKEN"

❌ 已废弃的路径（不要再用）

老路径	新路径	状态
`/api/third-party/keys`	`POST /api/v1/tokens`	已废弃
`/api/third-party/orders/:id`	`GET /api/v1/orders/:id`	已废弃
`/api/third-party/packages`	`GET /api/v1/packages`	已废弃
`/api/admin/*`	`/api/v1/admin/*`	已 301/307 重定向

完整 24 端点状态表见 API 规范化现状 § URL 自检清单。