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 + B | https://api.baiduqianfan.ai/v1/ | 海外(S1 目标);实际数据驻留待百度书面确认 |
国内版(cn) | /cn/a/… | 仅 A | https://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 请求体。
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,混淆它们是接入时最高频的错误。
| 请求头 | 适用范围 | 取值 | 处理方式 |
|---|---|---|---|
X-Gateway-Key | 所有请求 | rf_… 网关 API Key | 库内只存 SHA-256 哈希;关联套餐与订阅 |
Authorization: Bearer … | 仅模式 A | 你自己的千帆 key | 不落库,转发给上游 |
X-Provider-Key | 仅模式 A | Authorization 的替代写法 | 不落库,转发给上游 |
Content-Type | 所有请求 | application/json | JSON 请求体必填 |
X-Gateway-Key 缺失、无效或已吊销会在触达上游之前返回 401 gateway_auth_failed。明文 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/usage | A/B | 本地实测用量 —— 不请求上游、不计费 |
| GET | /cn/{a|b}/v1/models | A/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。前缀之后的部分即千帆自身的 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_end | UTC 自然月账期;跨期重置配额 |
tokens_measured | 有上游 usage 真值支撑的 token |
tokens_estimated | len(body)/4 回退估算的 token(不可结算) |
estimated_calls | token 数为估算的调用次数 |
billed_amount_usd | 台账 billed_amount 合计 |
overage_usd_per_1k_tokens | 由 plans.TOKEN_PRICE_USD 推导 |
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>'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}'data: {"id":"mock-chunk-1","object":"chat.completion.chunk","mock":true,"choices":[...]}
data: [DONE][DONE],无需上游 key 即可联调 SDK。两种模式:BYOK 与按量转售
| 模式 A —— 自带 key | Mode 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) |
| 数据驻留 | 跟随版本 | 海外 —— 目标,未核实(等百度书面确认) |
cn 版关闭模式 B,请求返回 403 mode_B_not_allowed_on_cn。仅国际版承载转售。错误码
错误是带 error 机器码的 JSON 对象,部分带 detail。千帆上游的错误按原始状态码与响应体原样透传。
| HTTP | error | 触发条件 | 处理 |
|---|---|---|---|
| 400 | edition_unknown | 路径缺少合法的 {intl|cn}/{a|b} 前缀 | 改用文档中的路径 |
| 401 | gateway_auth_failed | X-Gateway-Key 缺失 / 无效 / 已吊销 | 重新生成网关 key |
| 402 | quota_exceeded | 模式 B token 配额耗尽 | 升级套餐或等待重置 |
| 403 | mode_B_not_allowed_on_cn | 国内版请求了模式 B | 改用 /cn/a/… 或切到 intl |
| 403 | missing_provider_key | 模式 A 未带千帆 key | 补 Authorization 或 X-Provider-Key |
| 403 | key_edition_unknown | 千帆 key 未在版本注册表中登记(不按前缀推断) | 登记该 key 并显式标注 domestic / international |
| 403 | key_edition_mismatch | 千帆 key 版本与服务版本不符(C2/S3) | 让 key 与版本匹配 |
| 429 | rate_limited | 超出套餐 RPM | 退避重试或升级 |
| 403 | mode_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 | 窗口 |
|---|---|---|
free | 60 | 60 秒 |
pro | 600 | 60 秒 |
scale | 6,000 | 60 秒 |
建议:对 429 与 5xx 采用带抖动的指数退避;401、402、403 请先修正请求,不要盲目重试。
视频生成(/vod)
视频生成是独立品类,不是文本 API 的某个版本:它使用独立单段前缀 /vod/*(百度 VOD v3;/video/* 千帆原生视频见下文),连接不同上游,并且按任务计量,绝不按 token。一次视频任务的成本比一次对话高若干数量级,因此绝不能与 token 配额或 token 台账共用。
/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_status | false / 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。
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_status | false / 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 闭合路径。
机器可读规范
三类路径的 OpenAPI 3.1 描述发布在 openapi.json,可直接导入 Postman、Insomnia 或用 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 尚未实现。