tokencoup
版本: International · 国内版 语言: EN · ZH
获取 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)—— 两个版本都支持。
  • 向 /intl/a/… POST 一个 OpenAI 风格的 chat 请求体。
cURL —— 模式 A
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": "用一句话打个招呼。"}]
  }'
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/intl/a/<千帆路径>A自带 key 转发 —— 所有版本
POST/intl/b/<千帆路径>B按量转售 —— 仅国际版
GET/intl/{a|b}/v1/usageA/B本地实测用量 —— 不请求上游、不计费
GET/intl/{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 /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_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 /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>'
合规提示: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/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}'
响应形状(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。仅国际版承载转售。

模式 B(计量转售)—— 已取消

已于 2026-11-13 取消。 模式 B 让你按 token 付费使用 tokencoup 的国际版千帆 key 池。现予撤销:可操作它的 key 只有国内版 key,用国内 key 服务境外流量违反本网关赖以存在的跨境数据规则(C2/S3)。

网关现在对两个版本的 /intl/b 一律返回 403 mode_B_not_allowed_on_intl —— 与国内版禁止转售同级的路径级拦截。模式 A(自带 key)不受影响,快速开始见上文。

若将来提供真实的国际版千帆账号与 key,可通过配置重新启用模式 B 并填充转售池恢复 —— 已为其实现并测试的计量、计费、幂等与对账机制保留在代码库中,处于休眠状态。

计费与配额

计费仅适用于模式 B,而模式 B 已于 2026-11-13 取消(国内 key 不得服务国际转售,C2/S3)。下列套餐/配额/台账机制保持已实现并测试、处于休眠状态,直到真实国际版 key 池存在;模式 A 的用量会记入台账用于观测,但不计费。

套餐价格Token 配额RPM(60 秒窗口)
free$0100,00060
pro$29 / 月5,000,000600
scale$299 / 月80,000,0006,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 注入页面;若套餐集合发生漂移,构建闸门会直接失败。因此定价页与上表始终等于网关实际强制执行的值。
这不是可结算账单。 套餐价、每 1K token $0.002 的超额价、汇率与税率都是占位值。正式收费前还必须具备:真实国际版千帆 key、百度书面结算价与转售授权、按模型的输入/输出分价、VAT 处理与计费服务商。详见内部《计量与账单设计》。

错误码

错误是带 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 完全一致。

实验网关(/eos)

/eos/* 是第四个独立品类:一组实验性的 OpenAI 兼容第三方模型代理(one-api/new-api 系),既不是千帆,也不是官方 VOD 接口。它有独立的 key 注册表(secrets/eos_keys.json)、独立上游域名与独立限流桶。2026-11-14 由「登记但暂不接入」转为正式接入。

实验性质,无商业条款。 上游没有 billing / usage 查询接口(5 条候选路径全部 404),/v1/models 目录接口也已下线(40400,复测稳定),模型发现只能靠硬编码白名单。用量只在本地留痕便于观测:绝不出账、绝不扣 token 配额、绝不编造金额。该品类没有 SLA、没有价目表、不会生成账单,且仅在国际版参考文档中展示。

登记与严格的站点绑定

项目契约
网关鉴权X-Gateway-Key——与其它品类共用同一套订阅 key
上游凭证X-Eos-Key: <key> 或 Authorization: Bearer <key>;该 key 必须在 secrets/eos_keys.json 里登记为 active
未登记 key403 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_statusno_tariff——绝不产出金额
tokens上游 total_tokens 真值,仅供观测
台账eos_usage_ledger(独立表)。绝不写入 usage_ledger,绝不扣订阅 token 配额
streamSSE 缓冲透传;从最后一个带 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(不存请求/响应体)、网关鉴权已开启。国内版保持直连。

GDPR 对中国大陆无充分性认定,EU→CN 传输需 SCC + TIA。S1 的设计意图是绕开该路径,但尚未核实:百度未书面确认千帆国际版端点的驻留区域,第三方尽调称部分个人信息存于中国、无公开 DPA。在驻留区域与 DPA/SCC 确认之前,不要通过线上服务发送欧盟个人数据。无论驻留结论如何,国内版 key 在国际版一律被拒(C2/S3)。

机器可读规范

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

把任意兼容 OpenAI 的 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 尚未实现。