API 参考文档

概览

tokencoup 网关是架在百度千帆前面的一层轻量、兼容 OpenAI 格式的代理。它增加网关级鉴权、限流、用量计量与计费，不改写请求体。

版本与模式写在 URL 路径里，而不是请求头里。这样数据驻留边界是显式的，也能杜绝「用国内版 key 服务海外请求」这条被永久禁止的路径（C2/S3 拦截）。

快速开始

• 创建网关 API Key（rf_…），其套餐决定 RPM 与 token 配额。
• 选择模式 A（自带千帆 key）—— 两个版本都支持。
• 向 /cn/a/… POST 一个 OpenAI 风格的 chat 请求体。

BASE=https://api.tokencoup.com

curl -s "$BASE/cn/a/v1/chat/completions" \
  -H "X-Gateway-Key: rf_YOUR_GATEWAY_KEY" \
  -H "Authorization: Bearer YOUR_QIANFAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-4.0-8k",
    "messages": [{"role": "user", "content": "用一句话打个招呼。"}]
  }'

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "ernie-4.0-8k",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "你好！"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 12, "completion_tokens": 5, "total_tokens": 17}
}

鉴权

存在两个不同的 key，混淆它们是接入时最高频的错误。

端点

POST 用于推理：路径前两段选择版本与模式，其余部分原样转发给千帆上游。GET 提供两个只读端点：/v1/usage（本地台账）与 /v1/models（上游透传）。GET 同样需要鉴权并受限流约束，但不消耗 token、不计费。

{
  "model": "ernie-4.0-8k",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "用两句话总结：……"}
  ],
  "temperature": 0.7,
  "stream": false
}

用量查询（GET，本地真值）

GET /cn/{a|b}/v1/usage 返回网关自身 subscriptions 与 usage_ledger 表中的实测数值。它不请求上游、不计量、不计费。配额与 RPM 取自 gateway/plans.py —— 与价格页构建时注入的是同一份真源。

curl -s http://127.0.0.1:8081/cn/a/v1/usage \
  -H 'X-Gateway-Key: rf_...'

模型列表（GET，透传）

GET /cn/{a|b}/v1/models 在与推理相同的版本/key 校验（C2 S3）下透传给千帆上游。2026-11-12 已实跑核实：公开端点 https://api.baiduqianfan.ai/v1/models 无需鉴权即返回 HTTP 200，含 17 个模型、其中 14 个带公开单价。tokencoup 不改写这份清单 —— 首页模型价格表是 site/fetch_models.py 生成的带时间戳快照。mock 模式不发起网络请求，返回空列表。

curl -s http://127.0.0.1:8081/cn/a/v1/models \
  -H 'X-Gateway-Key: rf_...' -H 'Authorization: Bearer <你的千帆key>'

流式输出（SSE）

在请求体中设 stream: true。响应为 Content-Type: text/event-stream，采用 OpenAI 风格的 data: 分块，以 data: [DONE] 结束。v0.3 采用缓冲透传：先读完上游 SSE 再一次性写出，尚未实现逐块 flush，客户端不应假定逐 token 延迟。

curl -N http://127.0.0.1:8081/cn/a/v1/chat/completions \
  -H 'X-Gateway-Key: rf_...' -H 'Authorization: Bearer <你的千帆key>' \
  -H 'Content-Type: application/json' \
  -d '{"model":"ernie-4.0-8k","messages":[{"role":"user","content":"hi"}],"stream":true}'

data: {"id":"mock-chunk-1","object":"chat.completion.chunk","mock":true,"choices":[...]}

data: [DONE]

两种模式：BYOK 与按量转售

错误码

错误是带 error 机器码的 JSON 对象，部分带 detail。千帆上游的错误按原始状态码与响应体原样透传。

{
  "error": "quota_exceeded",
  "detail": "subscription token quota exhausted; upgrade plan or wait for reset"
}

限流

限流按网关 key 维度，采用 60 秒滑动窗口（配置 REDIS_URL 走 Redis，否则内存回退）。检查发生在上游调用之前，因此 429 不消耗 token。

建议：对 429 与 5xx 采用带抖动的指数退避；401、402、403 请先修正请求，不要盲目重试。

数据驻留（国内版）

国内版仅提供模式 A。上游为千帆国内版端点，log_prompt=true 以满足境内合规要求；请求不经过 Cloudflare 边缘，保持 S2 闭合路径。

机器可读规范

三类路径的 OpenAPI 3.1 描述发布在 openapi.json，可直接导入 Postman、Insomnia 或用 SDK 生成器生成客户端。

常见问题

需要自己有千帆账号吗？

模式 A：需要。模式 B：不需要，tokencoup 提供国际版 key 池。

prompt 会被存储吗？

国际版不会（log_prompt=false、collect_logs=false）。国内版按境内合规要求开启 prompt 日志。

国内版千帆 key 能打国际版端点吗？

不能。这正是被永久禁止的 C2/S3 路径，网关返回 403 key_edition_mismatch。

什么时候扣费？

仅模式 B、仅成功（200）响应。失败请求会写一条零金额台账，但不扣配额。

支持流式输出吗？

v0.2 不支持 —— 参考服务器读取并转发单个 JSON 响应。请设 stream: false。