tokencoup
版本: International · 国内版 语言: ZH · EN
获取 API Key
网关 v0.4 · 参考实现

API 参考文档

一个网关、两种模式。请求体兼容 OpenAI 格式,后端接百度千帆。

上线前状态。 https://api.tokencoup.com 已在 Cloudflare 边缘解析,但尚不是可用的 API:当前所有请求返回 HTTP 503 且 error.type=not_live(响应头 X-Tokencoup-Status: pre-launch)。参考服务器本地运行于 http://127.0.0.1:8081(默认 mock 模式)。模式 B(计量转售)已取消(2026-11-13):在国际版千帆真 key 到手前无法合规开展,用国内版 key 模拟属于合规违规(C2/S3 禁区);/intl/b 现返回 403 mode_B_not_allowed_on_intl。以下文档描述的是已经实现并测试通过的契约。 v0.3 新增 GET /v1/usage、GET /v1/models 与缓冲式 SSE。v0.4 改为优先读取上游 usage 真值(JSON 与 SSE 末块),无真值时标为估算,并加入幂等、原子配额扣减与 UTC 自然月账期。价格仍为占位值,口径见内部《计量与账单设计》。

概览

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

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

版本路径前缀模式上游基址数据驻留
国际版(intl)/intl/a/…、/intl/b/…A + Bhttps://api.baiduqianfan.ai/v1/海外(S1 目标);实际数据驻留待百度书面确认
国内版(cn)/cn/a/…仅 Ahttps://qianfan.baidubce.com/v2/中国大陆
路径中 {edition}/{mode}/ 之后的部分会原样拼到该版本的上游基址。上游基址已于 2026-11-12 按千帆官方文档核对:国际版 https://api.baiduqianfan.ai/v1/、国内版 https://qianfan.baidubce.com/v2/。国际版「海外数据驻留」仍需百度书面确认,依赖该结论前请先看跨境传输说明页。

快速开始

  • 创建网关 API Key(rf_…),其套餐决定 RPM 与 token 配额。
  • 选择模式 A(自带千帆 key)—— 两个版本都支持。
  • 向 /cn/a/… POST 一个 OpenAI 风格的 chat 请求体。
cURL —— 模式 A
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": "用一句话打个招呼。"}]
  }'
200 OK —— 上游原样透传
{
  "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 id、token 数)不会出现在响应体里;国际版下也不包含任何 prompt 内容。

鉴权

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

请求头适用范围取值处理方式
X-Gateway-Key所有请求rf_… 网关 API Key库内只存 SHA-256 哈希;关联套餐与订阅
Authorization: Bearer …仅模式 A你自己的千帆 key不落库,转发给上游
X-Provider-Key仅模式 AAuthorization 的替代写法不落库,转发给上游
Content-Type所有请求application/jsonJSON 请求体必填
参考服务器只处理 POST。X-Gateway-Key 缺失、无效或已吊销会在触达上游之前返回 401 gateway_auth_failed。明文 key 仅在创建时展示一次。
key 版本强校验(C2/S3):国内版千帆 key 打 /intl/…(或国际版 key 打 /cn/…)返回 403 key_edition_mismatch;未在版本注册表中显式登记的 key 一律 fail-closed,返回 403 key_edition_unknown。刻意不按前缀判断:国内版与国际版千帆 key 同为 bce-v3/ALTAK- 前缀,前缀无法证明版本。

端点

POST 用于推理:路径前两段选择版本与模式,其余部分原样转发给千帆上游。GET 提供两个只读端点:/v1/usage(本地台账)与 /v1/models(上游透传)。GET 同样需要鉴权并受限流约束,但不消耗 token、不计费。 视频生成 使用独立单段前缀 /vod/*(百度 VOD v3)和 /video/*(千帆原生视频,复用千帆 key)——均见下文「视频生成」。

方法路径模式含义
POST/cn/a/<千帆路径>A自带 key 转发 —— 所有版本
POST/intl/b/<千帆路径>B按量转售 —— 仅国际版
GET/cn/{a|b}/v1/usageA/B本地实测用量 —— 不请求上游、不计费
GET/cn/{a|b}/v1/modelsA/B已核实公开快照(17 个模型,14 个带价)
POST/vod/<vod-path>—视频生成(百度 VOD v3)——异步任务,按任务计量,不按 token
POST/GET/video/<path>—千帆原生视频生成——复用千帆 key,计量规则同 /vod/*(按任务)
请求体
{
  "model": "ernie-4.0-8k",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "用两句话总结:……"}
  ],
  "temperature": 0.7,
  "stream": false
}
上面的 model ID 是示意(ERNIE 系列)。可用模型以千帆控制台为准 —— tokencoup 不改写 model。前缀之后的部分即千帆自身的 API 路径(例如 v1/chat/completions)。

用量查询(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_...'
字段含义
token_quota / rpm_limit来自 gateway/plans.py 的套餐值
token_used_billable模式 B 计费 token(模式 B 已于 2026-11-13 取消;计数恒为 0)
token_remaining配额 − token_used_billable
ledger_calls台账记录的全部调用(Mode A 与 Mode B)
ledger_tokens全部调用累计 token = 真值 + 估算
period_start / period_endUTC 自然月账期;跨期重置配额
tokens_measured有上游 usage 真值支撑的 token
tokens_estimatedlen(body)/4 回退估算的 token(不可结算)
estimated_callstoken 数为估算的调用次数
billed_amount_usd台账 billed_amount 合计
overage_usd_per_1k_tokens由 plans.TOKEN_PRICE_USD 推导
v0.4: 优先采用上游 usage 真值(JSON 响应与 SSE 末块);上游未返回时才回退 len(body)/4 估算,并在台账记 tokens_source=estimated。tokens_measured、tokens_estimated 与 estimated_calls 给出两种口径的拆分。token_used_billable 与 ledger_tokens 口径不同:只有计费的模式 B 调用才累加前者。两者都不是最终账单 —— 占位价格与结算须以百度书面报价为准(口径见内部《计量与账单设计》)。

模型列表(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>'
合规提示:14 个声明了 datacenters 的模型全部标注 country_code: CN。这是来自上游的一手反证,不能据此宣称国际版流量不进入中国大陆。目录价格不是结算承诺价 —— 上线前须在千帆控制台并以书面形式确认模型 ID、单价与实际数据驻留。采用嵌套定价结构(schema_version 2.x)的模型会在快照中列出,但首页不展示其价格。

流式输出(SSE)

在请求体中设 stream: true。响应为 Content-Type: text/event-stream,采用 OpenAI 风格的 data: 分块,以 data: [DONE] 结束。v0.3 采用缓冲透传:先读完上游 SSE 再一次性写出,尚未实现逐块 flush,客户端不应假定逐 token 延迟。 若上游在最后一个分块返回 usage,则按真值计量;否则回退估算并明确标记。

请求
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}'
响应形状(mock)
data: {"id":"mock-chunk-1","object":"chat.completion.chunk","mock":true,"choices":[...]}

data: [DONE]
流式响应体不写审计日志(GDPR:不持久化 prompt / 响应内容)。mock 模式输出三个合成分块加 [DONE],无需上游 key 即可联调 SDK。

两种模式:BYOK 与按量转售

模式 A —— 自带 keyMode B — metered resale (cancelled)
千帆 key你自己提供tokencoup 国际版 key 池
计费订阅制,token 不加价按 token 计费,仅成功(200)响应
配额预检无有 —— 402 quota_exceeded
key 版本校验有(C2/S3 拦截)不适用;key 池已锁定版本
可用版本intl + cn所有版本一律拒绝(403 mode_B_not_allowed_on_intl)
数据驻留跟随版本海外 —— 目标,未核实(等百度书面确认)
C1:国内版千帆条款禁止转售 / 二次分发,因此 cn 版关闭模式 B,请求返回 403 mode_B_not_allowed_on_cn。仅国际版承载转售。

错误码

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

HTTPerror触发条件处理
400edition_unknown路径缺少合法的 {intl|cn}/{a|b} 前缀改用文档中的路径
401gateway_auth_failedX-Gateway-Key 缺失 / 无效 / 已吊销重新生成网关 key
402quota_exceeded模式 B token 配额耗尽升级套餐或等待重置
403mode_B_not_allowed_on_cn国内版请求了模式 B改用 /cn/a/… 或切到 intl
403missing_provider_key模式 A 未带千帆 key补 Authorization 或 X-Provider-Key
403key_edition_unknown千帆 key 未在版本注册表中登记(不按前缀推断)登记该 key 并显式标注 domestic / international
403key_edition_mismatch千帆 key 版本与服务版本不符(C2/S3)让 key 与版本匹配
429rate_limited超出套餐 RPM退避重试或升级
403mode_B_not_allowed_on_intl模式 B 已取消(2026-11-13):国内 key 不得服务国际转售(C2/S3)请改用模式 A,自带国际版千帆 key
错误响应体
{
  "error": "quota_exceeded",
  "detail": "subscription token quota exhausted; upgrade plan or wait for reset"
}

限流

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

套餐RPM窗口
free6060 秒
pro60060 秒
scale6,00060 秒

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

视频生成(/vod)

视频生成是独立品类,不是文本 API 的某个版本:它使用独立单段前缀 /vod/*(百度 VOD v3;/video/* 千帆原生视频见下文),连接不同上游,并且按任务计量,绝不按 token。一次视频任务的成本比一次对话高若干数量级,因此绝不能与 token 配额或 token 台账共用。

上线前状态,且默认拒绝。 当前未登记任何 VOD 凭证,所有 /vod 请求返回 403 vod_key_unregistered。这是刻意的:没有登记 key 就绝不转发到有计费的上游。对外 API 子域仍返回 503 not_live。

路径

方法路径含义
POST/PUT/vod/v3/aigc/text_to_video文生视频——创建异步任务
POST/vod/v3/aigc/image_to_video图生视频
POST/vod/v3/aigc/text_to_image文生图
POST/vod/v3/aigc/image_to_image图生图
POST/vod/v3/aigc/video_clone视频克隆
POST/vod/v3/aigc/video_extend视频延长
POST/vod/v3/aigc/lip_sync对口型
POST/vod/v3/aigc/create_effect_video特效视频
POST/vod/v3/aigc/recommend/effect特效推荐
POST/vod/v3/aigc/image生图
GET/vod/v3/tasks/{taskId}轮询任务状态——只读,不计量
GET/vod/v3/aigc/effect查询所有特效——只读
GET/vod/v3/aigc/presets-voices查询音色——只读

v3 段可省略(/vod/aigc/text_to_video 会被归一化)。只接受百度官方「API Key 权限接口」清单内的端点,按方法与路径段数双重匹配;其余一律返回 404 unknown_vod_endpoint。绝不把客户端给的任意路径原样转发给上游。

创建任务

请求
curl -s -X POST 'https://api.tokencoup.com/vod/v3/aigc/text_to_video' \
  -H 'X-Gateway-Key: rf_...' \
  -H 'X-Vod-Key: <你的百度 VOD key>' \
  -H 'X-Request-Id: my-task-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "P40",
    "modelP40TaskInput": {
      "duration": 5, "resolution": "540p", "aspectRatio": "16:9",
      "prompt": "a cat surfing a wave, cinematic"
    }
  }'

上游返回 taskId,用 GET /vod/v3/tasks/{taskId} 轮询直到任务完成。除路径归一化外,请求体原样透传。

幂等——在转发之前校验

创建任务在上游是真花钱的动作,所以重放保护放在转发之前,不是之后。同一网关 key 复用同一个 X-Request-Id 会返回缓存的 taskId 并标 duplicate: true,上游零新增调用。省略 X-Request-Id 时网关会生成一个,但生成的值无法跨重试复用。

计量

字段含义
unit恒为 task
billable_units成功创建 1 个任务为 1,否则 0
priced / billing_statusfalse / no_tariff——尚无 VOD 价目表
tokens恒为 0——视频不按 token 计量
task_id上游任务句柄(响应带则记)
cost_drivers仅 model、duration、resolution、aspectRatio
视频记在独立台账(video_task_ledger)里,绝不写 token 台账,也绝不扣 token 配额。若 200 响应不带 taskId,则不记账(no_task_id),不伪造句柄。由于尚无 VOD 价目表,billable_units 会被记录但不产生任何金额——这里的任何字段都不构成账单行。

密钥与隔离

VOD key 与千帆 key 分开注册,两个注册表互斥:登记为 VOD 的 key 会被文本端点拒绝,千帆 key 会被 /vod 拒绝。字符串格式无法判定品类——百度官方 VOD 示例 key 是 bce-v3/ALTAK-…,与千帆 key 完全同形——所以注册表是唯一依据。未登记的 key 返回 403 vod_key_unregistered。

限流

视频使用独立桶(rlv:),与文本限流分开:任务昂贵,一次重试风暴就可能创建几十个计费任务。默认每个网关 key 60 秒内 2 次。

现状与未核实边界

  • 上游默认 https://vod.bj.baidubce.com:443。 百度文档说明支持 HTTP 与 HTTPS 并建议用 HTTPS;其 API Key 页示例用端口 8301,该端口从公网不可达(实测连接超时),故默认改为 HTTPS/443。可用 TOKENCOUP_VOD_SCHEME / _HOST / _PORT 覆盖。
  • Bearer 鉴权在该主机上尚未证实。 无鉴权、官方 bce-v3/ALTAK- 形态、vod-v3/… 三者返回完全相同的 BceSignatureValidateException,说明该主机网关可能只认 AK/SK 请求签名,而非 Bearer key。在真 key 返回 200 之前,不得计费、不得对外承诺。
  • 官方 API Key 页未给创建任务的响应示例,taskId 的确切字段名待真 key 联调核实;网关兼容多种常见写法,取不到就不记账。

千帆原生视频生成(/video)

千帆本身在国内站也提供原生视频生成接口(/beta/video/…)。网关以单段前缀 /video/* 暴露——这是第三个品类,与文本 API(/intl、/cn)和 VOD(/vod)都相互独立。它复用你的千帆 key:与文本 API 同一把 bce-v3/ALTAK-… Bearer 凭证、同一个注册表,无需单独注册。计量仍然是按任务,绝不按 token。

该路径已于 2026-11-13 用真实国内版 key 对上游实测:无效凭证返回 401 invalid_iam_token(真鉴权),有效 key 则进入业务层返回 400 invalid_video_generation_argument——是参数错,说明鉴权已通过。与 VOD 主机不同,这条路径的鉴权是已证实的。

路径

方法路径含义
POST/video/generations/qianfan-video创建任务(文生视频等)
GET/video/generations/qianfan-video/fireseries?task_id=…轮询任务状态——只读,不计量
GET/video/generations/qianfan-video/m-series/list任务列表——只读,不计量

/video/ 之后的路径必须与三个官方端点之一逐字匹配(方法与路径段都校验),其余一律返回 404 unknown_qf_video_endpoint。query 串(?task_id=…)原样透传。

创建任务

请求
curl -s -X POST 'https://api.tokencoup.com/video/generations/qianfan-video' \
  -H 'X-Gateway-Key: rf_...' \
  -H 'Authorization: Bearer <你的千帆 key>' \
  -H 'X-Request-Id: my-video-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "VQ3-Pro", "type": "text2video",
    "prompt": "一只猫在浪尖冲浪,电影感"
  }'

上游返回 task_id 与 usage 块(duration、resolution、total_tokens)。用 fireseries 端点轮询直到任务完成。这里的 total_tokens 是上游的视频 token 口径,网关绝不把它加进 token 台账或 token 配额,只作为任务元数据存档。

计量

字段含义
unit恒为 task
billable_units成功创建 1 个任务记 1,否则 0
priced / billing_statusfalse / no_tariff——无公开价目表,不产生金额
tokens恒为 0——视频不按 token 计量
task_id上游任务句柄
upstream_usage上游给的 duration / resolution / total_tokens,仅作元数据存档

官方价目表(2026-10-14 更新,仅作参考)

千帆视频按积分计费,1 积分 = 1 元。下表逐字摘自官方积分抵扣表(qianfan-multimodal 文档《视频生成模型价格》,页面更新时间 2026-10-14)。注意:网关当前仍不出账——价目表虽已公开,但出账所需的时长×分辨率×模型三维匹配规则尚未接入计费代码,priced 仍为 false。

系列计费方式价格(元)
VQ4按秒 × 清晰度540p 0.28125/s;720p 0.59375/s;1080p 0.75/s;2K 1.1875/s;4K 2.4375/s
VQ3-Pro按支(1–16 秒)1080p 0.9375;720p 0.78125;540p 0.3125
VQ3-Turbo按支(1–16 秒)1080p 0.4375;720p 0.3750;540p 0.2500
VQ2(文生/图生/首尾帧)按时长 × 清晰度例:文生视频 VQ2 540p 1秒 0.3125 / 10秒 0.875;1080p 1秒 0.625 / 10秒 3.4375
VQ2-Pro(参考生视频)按秒增量公式540p 第1秒 0.625 + 后续每秒 +0.15625;720p 第1秒 0.9375 + 每秒 +0.15625;1080p 第1秒 2.65625 + 每秒 +0.3125
VQ2 音视频直出附加费图生视频/参考生视频任务额外 +0.46875 积分/次

完整三维表(VQ2 每个模型 × 每档时长 × 三档清晰度)见官方页原文;此处只摘结构与代表行,不是完整价目。来源:cloud.baidu.com/doc/qianfan-multimodal/s/nmo74mg17(公开网页,2026-11-13 抓取)。

密钥与隔离

key 必须登记在千帆注册表且 edition 为 domestic——beta 视频端点在 qianfan.baidubce.com 上,国际版 key 未在该路径核实过,一律拒绝(403 qf_video_key_edition,fail-closed)。登记在 VOD 注册表的 key 会被拒绝(403 qf_video_key_unregistered),与 /vod 拒绝千帆 key 构成双向闭环:字符串格式无法判定品类,注册表才是唯一依据。

限流

千帆视频有自己的桶(rlq:),与文本桶(rl:)、VOD 桶(rlv:)都分开。默认每个网关 key 60 秒 2 次;可用 TOKENCOUP_QF_VIDEO_RPM / _RPM_WINDOW 覆盖。

现状

鉴权已对上游实测证实(2026-11-13)。尚未用真实计费载荷跑过端到端任务创建——请求体结构(model、type、model_parameters)按官方文档整理,且在价目表发布前 no_tariff 状态持续。幂等重放保护(同一 X-Request-Id 返回缓存 task_id、零次新上游调用)与 /vod 完全一致。

数据驻留(国内版)

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

依据国内版千帆条款,本版本不提供转售(模式 B)—— 且模式 B 已于 2026-11-13 全局取消。模式 A(自带 key)是唯一网关模式。

机器可读规范

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

把任意兼容 OpenAI 的 SDK 的 base_url 指向 https://api.tokencoup.com/cn/a/v1,并把 X-Gateway-Key 设为默认请求头即可。网关不改写请求体,标准 chat-completion 方法可直接复用。

常见问题

需要自己有千帆账号吗?

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

prompt 会被存储吗?

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

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

不能。这正是被永久禁止的 C2/S3 路径:/intl/a 对国内版 key 返回 403 key_edition_mismatch,/intl/b 已整体取消。代码级执行,不是政策声明。

什么时候扣费?

仅模式 B、仅成功(200)响应。失败请求写一条 token 为 0 的台账,不扣配额。重试请复用 X-Request-Id,避免重复计费。

支持流式输出吗?

支持。v0.3 起 stream: true 返回缓冲式 SSE;v0.4 会读取上游最后一个 usage 分块(若提供)。逐块 flush 尚未实现。