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)—— 两个版本都支持。
- 向
/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,混淆它们是接入时最高频的错误。
| 请求头 | 适用范围 | 取值 | 处理方式 |
|---|---|---|---|
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 | /intl/a/<千帆路径> | A | 自带 key 转发 —— 所有版本 |
| POST | /intl/b/<千帆路径> | B | 按量转售 —— 仅国际版 |
| GET | /intl/{a|b}/v1/usage | A/B | 本地实测用量 —— 不请求上游、不计费 |
| GET | /intl/{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 /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_...'| 字段 | 含义 |
|---|---|
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 /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>'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/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][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。仅国际版承载转售。模式 B(计量转售)—— 已取消
已于 2026-11-13 取消。 模式 B 让你按 token 付费使用 tokencoup 的国际版千帆 key 池。现予撤销:可操作它的 key 只有国内版 key,用国内 key 服务境外流量违反本网关赖以存在的跨境数据规则(C2/S3)。
网关现在对两个版本的 /intl/b 一律返回 403 mode_B_not_allowed_on_intl —— 与国内版禁止转售同级的路径级拦截。模式 A(自带 key)不受影响,快速开始见上文。
计费与配额
计费仅适用于模式 B,而模式 B 已于 2026-11-13 取消(国内 key 不得服务国际转售,C2/S3)。下列套餐/配额/台账机制保持已实现并测试、处于休眠状态,直到真实国际版 key 池存在;模式 A 的用量会记入台账用于观测,但不计费。
| 套餐 | 价格 | Token 配额 | RPM(60 秒窗口) |
|---|---|---|---|
free | $0 | 100,000 | 60 |
pro | $29 / 月 | 5,000,000 | 600 |
scale | $299 / 月 | 80,000,000 | 6,000 |
超额单价 每 1,000 token $0.002(占位值)。配额耗尽返回 402 quota_exceeded。USD→CNY 汇率(7.2)与税率均为占位;上线前 EU 客户须处理 VAT。 配额扣减是原子条件更新,账期为 UTC 自然月,跨期 token_used 归零。重试请带 X-Request-Id,避免重复写入台账或二次扣配额。若请求发出后真实用量超出剩余额度,成本仍按真值入账并标记 quota_exceeded,不做冲销。
gateway/plans.py,把价格、Token 配额与 RPM 注入页面;若套餐集合发生漂移,构建闸门会直接失败。因此定价页与上表始终等于网关实际强制执行的值。错误码
错误是带 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 完全一致。
实验网关(/eos)
/eos/* 是第四个独立品类:一组实验性的 OpenAI 兼容第三方模型代理(one-api/new-api 系),既不是千帆,也不是官方 VOD 接口。它有独立的 key 注册表(secrets/eos_keys.json)、独立上游域名与独立限流桶。2026-11-14 由「登记但暂不接入」转为正式接入。
/v1/models 目录接口也已下线(40400,复测稳定),模型发现只能靠硬编码白名单。用量只在本地留痕便于观测:绝不出账、绝不扣 token 配额、绝不编造金额。该品类没有 SLA、没有价目表、不会生成账单,且仅在国际版参考文档中展示。登记与严格的站点绑定
| 项目 | 契约 |
|---|---|
| 网关鉴权 | X-Gateway-Key——与其它品类共用同一套订阅 key |
| 上游凭证 | X-Eos-Key: <key> 或 Authorization: Bearer <key>;该 key 必须在 secrets/eos_keys.json 里登记为 active |
| 未登记 key | 403 eos_key_unregistered(fail-closed)。key 的字符串形态不参与品类判定 |
| 站点绑定 | US key → eos-ca.aigc.exp.bcevod.com;SG key → eos-sg.aigc.exp.bcevod.com,静态映射 |
| 跨站 | 实测:所有跨站组合上游均返回 40100。网关绝不回退到另一个站点——绑定站点无路由时返回 403 eos_site_unregistered |
| 注册表隔离 | 与千帆、VOD 注册表双向互斥;同一把 key 同时登记两处,两边都拒绝 |
2026-11-14 已把 /vod 与 /eos 两个注册表拆开:两把活 key 从 VOD 注册表迁出(原条目保留为 moved-* 审计留痕,不再加载),因为同一把 key 同时登记两处会触发双向互斥,把 /eos 一起锁死。已失效的 DE key 在任何注册表都不登记。
端点与模型白名单
| 方法 | 路径 | 含义 |
|---|---|---|
| POST | /eos/v1/chat/completions | 对话补全;stream:true 时按 SSE 缓冲透传 |
| 其它 | 任何其它 /eos/* 路径 | 404 unknown_eos_endpoint(不提供目录 / 发现接口) |
由于上游目录接口已下线,模型 ID 必须命中硬编码白名单(2026-11-13 实测矩阵,两个站点一致):gemini-2.5-flash、gemini-2.5-flash-lite、gemini-2.5-flash-pro、gemini-2.5-flash-image、glm-5.2、glm-5.1、kimi-k3。其余一律 400 model_not_allowed,绝不转发任意 model 字符串。当前只暴露 chat 端点——生图模型列全仅供未来扩展,此处不路由。
curl -s -X POST 'https://api.tokencoup.com/eos/v1/chat/completions' \
-H 'X-Gateway-Key: rf_...' \
-H 'X-Eos-Key: <已登记的 eos key>' \
-H 'X-Request-Id: my-eos-001' \
-H 'Content-Type: application/json' \
-d '{"model": "gemini-2.5-flash", "messages": [{"role": "user", "content": "你好"}]}'计量:只记账,不出账
| 字段 | 含义 |
|---|---|
metered | 仅当上游返回结构化 usage 块且 total_tokens 为正时才是 true |
billed / priced | 恒为 false |
billing_status | no_tariff——绝不产出金额 |
tokens | 上游 total_tokens 真值,仅供观测 |
| 台账 | eos_usage_ledger(独立表)。绝不写入 usage_ledger,绝不扣订阅 token 配额 |
stream | SSE 缓冲透传;从最后一个带 usage 的块取真值。无 usage → 不估算、不记账 |
X-Request-Id | 幂等:重放在任何上游调用之前返回 duplicate:true。响应体从不落库 |
限流使用独立的 rle: 桶(默认 10 次/60 秒,可用 TOKENCOUP_EOS_RPM 调整)。审计只留 12 位 key 指纹与绑定站点,绝不落地明文凭证、prompt 或应答正文。
试用额度(未登记凭证)
试用额度是一条受控、只记账、绝不账单的通道,面向还没有正式上游凭证的调用方——例如正在评估网关的人,或只用上游免费额度模型的调用方。它默认关闭,一旦打开并且额度用尽,对相应调用方就是硬 403。
TOKENCOUP_TRIAL_ENABLED 未设置(默认值)时,没有正式凭证的调用方一律被拒:403 trial_disabled。而已登记凭证的调用方(key 在 secrets/eos_keys.json 或 secrets/qianfan_keys.json 里)永远不受试用额度约束——它直接绕过这条通道,因为它本来就有自己的凭证。试用通道允许什么
| 项目 | 契约 |
|---|---|
| 开关 | TOKENCOUP_TRIAL_ENABLED=1(默认 0 = 关闭,fail-closed) |
| 可试用品类 | 仅 eos(qianfan_cn 已于 2026-11-14 摘除——白名单模型经实测全部退役)。/vod、/video、/intl/* 永远不可试用 |
| 模型 | 硬编码白名单。/eos:7 个实验模型;千帆国内:无试用通道——原 4 个 ERNIE 模型上游已退役,现行目录无可证实免费的模型 |
| 每 key / 小时 | TOKENCOUP_TRIAL_CALLS_PER_KEY_HOUR(默认 5) |
| 每 key / 日 | TOKENCOUP_TRIAL_CALLS_PER_KEY_DAY(默认 20) |
| 全局 / 日 | TOKENCOUP_TRIAL_CALLS_GLOBAL_DAY(默认 200)——fail-closed:全站一旦触顶,所有试用调用方一律被拒 |
| 单请求 | TOKENCOUP_TRIAL_MAX_TOKENS_PER_CALL(默认 8,000)——随调用记录的参考上限 |
| 模型不在白名单 | 403 trial_model_not_allowed(绝不转发) |
| 品类不可试用 | 403 trial_category_not_allowed |
| 超出上限 | 403 trial_rate_limited(小时)或 403 trial_quota_exhausted(日 / 全局) |
为什么试用通道绝不出账
试用调用只写入 trial_ledger——一张只存计数与时间戳的独立表。绝不写入 usage_ledger、绝不扣订阅 token 配额、绝不产出金额。billed=false、priced=false、billing_status=no_tariff。prompt、应答正文、响应体一律不落库。
上游自己的免费额度是另一回事,属于上游侧:国内千帆控制台给每模型 100 万 tokens(3 个月),另有永久免费的 ERNIE-Speed/Lite/Tiny;而国际版完全没有免费额度(价目页只有付费单价)。所以试用额度约束的是我们这条通道,不是上游余额——而且它永远不产生价格。
TOKENCOUP_TRIAL_ENABLED=1 \
TOKENCOUP_TRIAL_CALLS_PER_KEY_HOUR=5 \
TOKENCOUP_TRIAL_CALLS_PER_KEY_DAY=20 \
TOKENCOUP_TRIAL_CALLS_GLOBAL_DAY=200 \
PYTHONPATH=. TOKENCOUP_DB=/var/lib/tokencoup/gw.db PORT=8081 MOCK=0 \
python3 -u -m gateway.server用 trial.snapshot(key_id, category) 查当前用量:返回 calls_today、tokens_today、三条上限,以及 billed=false / priced=false / billing_status=no_tariff。不暴露任何凭证或正文内容。
数据驻留与隐私(国际版)
国际版实现的是 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 生成器生成客户端。
base_url 指向 https://api.tokencoup.com/intl/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 尚未实现。