企业 API 接入

谁可以接入

仅企业旗舰版组织开放；密钥由团队所有者创建，费用走团队共享钱包。

企业 API 接入是「企业旗舰版」组织专属的能力。个人账号、企业基础版与企业专业版不开放这组接口，调用会直接返回 403；升级到企业旗舰版后即可在客户端创建密钥。

• 密钥在客户端「团队与共享钱包 → API 密钥」里管理，只有团队所有者能创建和撤销，普通成员看不到这个入口。
• 建议按调用方分别建密钥（例如测试环境一把、生产环境一把），出问题时可以单独撤销，不牵连其它系统。
• 通过密钥产生的调用费用一律记在团队共享钱包上，不经过任何成员的个人钱包。

认证与密钥

Bearer 密钥认证；明文只在创建时展示一次，撤销即时生效。

每个请求都要在 Authorization 请求头里带上密钥；请求体为 JSON 时另带 Content-Type: application/json。

Authorization: Bearer sk-ic-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: <你自己生成的唯一字符串>

• 密钥明文只在创建的那一次展示。平台只保留校验用的摘要，事后无法再找回，请当场存进你自己的密钥管理工具。
• 不要把密钥写进前端代码、公开仓库、截图或日志里。它只应该出现在你自己的服务端。
• 怀疑泄露就立即撤销并重建一把。撤销即时生效，此后所有使用该密钥的请求都会返回 401，已在跑的任务不受影响。

基础地址与端点

所有端点都挂在同一个前缀下，同步接口直接返回结果，异步接口返回任务。

所有请求都发往下面这个前缀。服务域名在开通时提供，不同部署环境不一样，本文档一律用占位符表示：

https://<你的服务域名>/api/openapi/v1

视频生成耗时长，走异步：提交后拿到任务，再用 GET /tasks/{id} 轮询状态、用 GET /tasks/{id}/result 取结果，中途可以用 POST /tasks/{id}/cancel 取消。图片、语音与文字类接口是同步的，一次请求直接返回结果。

请求示例

提交一个异步视频任务，再按任务 ID 查询进度。

curl -X POST "https://<你的服务域名>/api/openapi/v1/videos" \
  -H "Authorization: Bearer sk-ic-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260912-000123" \
  -d '{
    "model": "<模型 ID，取自 GET /models>",
    "prompt": "雨夜霓虹下的长街，镜头缓慢推进",
    "resolution": "720P",
    "duration": 5
  }'

curl "https://<你的服务域名>/api/openapi/v1/tasks/<任务 ID>" \
  -H "Authorization: Bearer sk-ic-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

任务 ID 来自提交接口的返回体；同步生成接口则会在 X-Generation-Task-ID 响应头里带上本次调用的任务 ID，可用于事后对账。

幂等键

POST 生成请求必须带 Idempotency-Key，重发不会重复计费。

适用范围

所有 POST 生成请求都必须带 Idempotency-Key 请求头：/videos、/images/generations、/images/edits、/audio/speech、/chat/completions、/responses。

取值要求

可打印 ASCII 字符，不含空格，长度不超过 90 字节。直接用你自己业务侧的订单号或一个 UUID 即可。

重复提交

同一把密钥用同一个幂等键重复提交，命中的是同一个任务、返回同一份结果，不会重复计费 —— 网络超时后原样重发是安全的。

作用域

幂等键按密钥做了命名空间隔离：不同密钥之间互不影响，同一个取值在两把密钥上是两次独立提交，各自计费。

限流

密钥与团队两层令牌桶，两层都通过才放行。

单把密钥

默认每分钟 60 次。

单个团队

默认每分钟 300 次，该团队名下所有密钥合并计算。

放行条件

两层令牌桶各判各的，密钥层与团队层都通过才放行；任一层用尽即拒绝。

超限之后

返回 429，并在 Retry-After 响应头给出需要等待的秒数。请按它退避重试，不要原地重试 —— 那只会继续消耗配额。

以上是默认额度。如果你的调用量需要更高额度，请联系我们说明场景与峰值，由我们评估。

错误码

按 HTTP 状态码判断，具体原因看响应体里的 msg。

400

请求参数或模型不合法。按返回的 msg 修正后再提交；模型 ID 以 GET /models 返回的为准。

401

密钥无效、已撤销，或密钥所属团队已解散、所有者被封禁。服务端对这几种情况刻意返回同一句提示、不作区分（不给探测者任何额外信息），请检查 Authorization 头，必要时重新创建一把密钥。

402

团队可用点数不足。请先给团队共享钱包充值或购买会员；点数不足时任务不会被创建，也不会产生扣费。

403

当前套餐未包含 API 接入。企业 API 接入仅对企业旗舰版开放，请先升级套餐。

429

触发限流。按 Retry-After 响应头退避后重试。

503

限流所依赖的组件暂不可用。这种情况下服务端一律拒绝而不是放行（不会绕过限流），请稍后重试；重试时沿用同一个幂等键不会重复计费。

计费

按官方模型定价从团队共享钱包扣点，个人钱包不受影响。

通过 API 发起的调用，按官方模型定价从团队共享钱包扣点。个人钱包与 API 调用完全无关：既不会被扣，也不会因为团队的调用而变化。

• 计费口径与在客户端内提交完全一致：视频按模型、分辨率与时长计价，图片与文字按次计价；提交时冻结、结束后按实际用量结算，未用完的部分返还。
• 团队可用点数不足时请求直接返回 402，任务不会被创建，也不会产生任何扣费。
• 用量与流水可以在客户端的团队面板查看；管理后台还能按组织与密钥分别查询，账单有争议时以这里的记录为准。

响应包装

沿用站点统一的 code / data / msg 信封；同步生成接口透传上游响应体。

接口沿用站点统一的响应包装：业务成功时 code 为 0、data 是本次结果、msg 为 ok；失败时 msg 是可直接展示给你的运维人员看的中文说明。异步提交成功时状态码是 202，data 为本次的任务对象；data 的具体字段随端点不同，一律以实际返回为准，请不要按文档里的示例写死解析。

HTTP/1.1 202 Accepted

{
  "code": 0,
  "data": { … 任务对象：字段以实际返回为准，其中的任务 ID 用于后续 GET /tasks/{id} … },
  "msg": "ok"
}

同步生成接口（图片生成与编辑、语音合成、对话补全、响应式文本生成）是个例外：它们直接透传上游模型服务商的响应体，不再套这层信封，便于你复用已有的模型 SDK 与解析代码；这类响应会带 X-Generation-Task-ID 响应头，用它把上游结果和平台账单对上。