API 参考文档

概览

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

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

快速开始

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

BASE=https://api.tokencoup.com

curl -s "$BASE/intl/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 /intl/{a|b}/v1/usage 返回网关自身 subscriptions 与 usage_ledger 表中的实测数值。它不请求上游、不计量、不计费。配额与 RPM 取自 gateway/plans.py —— 与价格页构建时注入的是同一份真源。

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

模型列表（GET，透传）

GET /intl/{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/intl/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/intl/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 与按量转售

模式 B 快速开始（仅国际版）

模式 B 不需要千帆 key。你按 token 付费使用 tokencoup 的国际版千帆 key 池，网关在校验网关 key 之后自行注入池内 key 到上游。

curl -s "https://api.tokencoup.com/intl/b/v1/chat/completions" \
  -H "X-Gateway-Key: rf_YOUR_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "ernie-4.0-8k", "messages": [{"role": "user", "content": "你好"}]}'

const res = await fetch('https://api.tokencoup.com/intl/b/v1/chat/completions', {
  method: 'POST',
  headers: {
    'X-Gateway-Key': process.env.TOKENCOUP_GATEWAY_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'ernie-4.0-8k',
    messages: [{ role: 'user', content: '你好' }],
  }),
});
console.log(res.status, await res.json());

计费与配额

仅模式 B计费。用量在成功（200）响应后计入台账并扣减订阅的 token 配额。原型按 len(body)/4 估算 token；生产须改为读取上游返回的 usage 字段。

超额单价 每 1,000 token $0.002（占位值）。配额耗尽返回 402 quota_exceeded。USD→CNY 汇率（7.2）与税率均为占位；上线前 EU 客户须处理 VAT。

错误码

错误是带 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 请先修正请求，不要盲目重试。

数据驻留与隐私（国际版）

国际版实现的是 C2 / S1 设计目标：请求转发至千帆国际版上游并带 X-Data-Region: overseas 标记，log_prompt=false —— 不持久化 prompt。审计记录只含版本、模式、key id 与 token 数。X-Data-Region 只是内部路由标记，不决定上游在哪里处理数据，也不是驻留证据。 海外驻留目前是目标，待百度书面确认。

Cloudflare AI Gateway 仅前置在国际版路径：300 秒边缘缓存、600 次/60 秒限流、3 次重试、collect_logs=false（不存请求/响应体）、网关鉴权已开启。国内版保持直连。

机器可读规范

三类路径的 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。