视频生成 API · 租户接入文档

版本 v5 · 2026-10-09 · Somobai 视频生成平台(变更记录见 §12)

对外接口以火山方舟官方接口兼容为准。 如果你已经接过火山方舟视频生成,迁移到本平台只需要改两处:域名 和 凭证,请求体与响应体字段一律不变;素材库另提供与火山官方 SDK 兼容的签名入口(§9)。

1. 快速开始

三步跑通:

# 1. 确认令牌可用(列出你有权限的模型)
curl https://api.somobai.com/v1/models \
  -H "Authorization: Bearer sk-your-key-here"

# 2. 创建视频任务
curl -X POST https://api.somobai.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "doubao-seedance-2-0-260128",
        "content": [{"type": "text", "text": "一只猫在草地上奔跑"}],
        "resolution": "720p",
        "duration": 5
      }'
# → {"id":"cgt-20260827103000-a1b2c"}

# 3. 轮询直到终态
curl https://api.somobai.com/api/v3/contents/generations/tasks/cgt-20260827103000-a1b2c \
  -H "Authorization: Bearer sk-your-key-here"

2. 认证

所有数据面接口使用 Bearer Token:

Authorization: Bearer sk-xxxxxxxxxxxx

• 令牌由平台开户时签发交付,你也可以在租户控制台 /console → 「令牌管理」自行创建。
• 控制台创建时明文只显示一次,请立即存入你的密钥管理系统;遗失可联系平台重新获取。
• 令牌可配置:模型白名单、IP 白名单、子额度上限、有效期。
• 令牌泄漏时在控制台「禁用」或「轮换」,轮换会立即失效旧令牌并返回新令牌。

IP 白名单(必填)

• 账户级 IP 白名单在开户/注册时必填,填写调用 API 的服务器公网 IP(多个用逗号分隔,支持 CIDR,如 203.0.113.7, 198.51.100.0/24)。不接受 0.0.0.0/0 这类放开全部的网段。
• 只有白名单内的 IP 能调用 API,Bearer 令牌与 §9 的 AK/SK 入口都受限;控制台网页登录不受影响。
• 服务器 IP 变更时,在控制台「设置 → API 调用 IP 白名单」修改(owner/admin 角色),即时生效。
• 令牌上的 IP 白名单为可选项,在账户白名单基础上进一步收窄(两者都满足才放行)。

认证失败

3. 视频生成

3.1 创建任务

POST /api/v3/contents/generations/tasks

请求头

请求体(与火山方舟原生字段同构)

Seedance 2.5 扩展字段(原样透传,以模型实际支持为准)

• content[].image_url.url 等媒体地址可填公网 HTTPS URL,或平台素材引用 asset://{asset_id}(§8.1)。
• 输入含真人人脸的图/视频会被内容审核拦截(InputImageSensitiveContentDetected.PrivacyInformation),处理路径见 §8.2(真人认证)。
• safety_identifier 由平台自动注入租户隔离标识,无需传入,传入将被忽略。
• 火山文本命令兼容:提示词末尾的 --resolution 1080p --duration 5 等命令(含 --rs/--dur/--rt 简写)同样被识别;与顶层字段并存时以文本命令为准,计费按最终生效值。
• 透传规则:请求体按原样转发给模型,平台只做以下处理——asset:// 引用替换为实际素材地址、safety_identifier 注入、callback_url 改由平台接收(终态时平台再推送到你的地址,见 §5)、文本命令解析回写顶层字段。上表扩展字段及其余未列出的官方字段均原样透传。

响应 200

{"id": "cgt-20260827103000-a1b2c"}

任务 ID 格式与火山同构:cgt-yyyymmddHHmmss-xxxxx(2026-08-27 前创建的历史任务为 task_ + 24 位十六进制,按原 ID 继续可查)。

注意:创建接口只返回 ID,不返回状态。请用 §3.3 查询,或配置 Webhook(§5)。

错误

3.2 幂等

带 Idempotency-Key 头时,同一租户下相同键的重复请求不会创建新任务,直接返回首次创建的任务 ID:

curl -X POST .../tasks -H 'Idempotency-Key: order-8837' ...
# → {"id":"cgt-20260827103000-a1b2c"}    第一次:创建
# → {"id":"cgt-20260827103000-a1b2c"}    重试:返回同一个,不重复扣费

幂等键建议用你自己的业务单号。键永久有效,不设过期。

幂等只匹配键,不校验请求体。同键不同参数仍返回首次的任务。

3.3 查询任务

GET /api/v3/contents/generations/tasks/{id}

进行中

{
  "id": "cgt-20260827103000-a1b2c",
  "model": "doubao-seedance-2-0-260128",
  "status": "running",
  "resolution": "720p",
  "duration": 5,
  "error": null,
  "created_at": 1786886334,
  "updated_at": 1786886391
}

成功

{
  "id": "cgt-20260827103000-a1b2c",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "resolution": "720p",
  "duration": 5,
  "error": null,
  "content": {
    "video_url": "https://….mp4?…(约 24 小时有效,立即转存,见 §6)",
    "last_frame_url": "https://….png?…"
  },
  "usage": {"completion_tokens": 103819, "total_tokens": 103819},
  "created_at": 1786886334,
  "updated_at": 1786886512
}

失败

{
  "id": "cgt-20260827103000-a1b2c",
  "status": "failed",
  "error": {"code": "InvalidParameter", "message": "..."},
  "created_at": 1786886334,
  "updated_at": 1786886334
}

• created_at / updated_at 为 Unix 秒(整数,非字符串)。
• usage.total_tokens 是本单的计费量,与账单严格一致,口径见 §7.2。
• resolution / duration 为实际输出值(duration: -1 的任务在成功后回填模型实际选择的时长)。
• 模型透传的展示字段(seed、framespersecond、generate_audio、service_tier、frames)在上游返回时平铺在顶层。

3.4 状态机

轮询建议:创建后 5 秒开始首次查询,之后每 3–5 秒一次。更推荐用 Webhook(§5)替代轮询。

3.5 取消任务

POST /api/v3/contents/generations/tasks/{id}/cancel

{"id": "cgt-20260827103000-a1b2c", "status": "cancelled"}

限制:仅 queued 且尚未提交执行的任务可取消,否则返回:

{"error": {"code": "InvalidState", "message": "仅本地排队中的任务可取消"}}

取消后预扣额度全额释放。

3.6 任务列表

GET /api/v3/contents/generations/tasks?status=succeeded

{"items": [ { /* 同 §3.3 单任务结构 */ } ]}

• status 可选,按状态过滤。
• 固定返回最近 100 条,按创建时间倒序,无分页参数。需要全量历史请走控制台。

3.7 模型列表

GET /v1/models

{
  "object": "list",
  "data": [
    {"id": "doubao-seedance-2-5-260628", "object": "model"},
    {"id": "doubao-seedance-2-0-260128", "object": "model"},
    {"id": "doubao-seedance-2-0-fast-260128", "object": "model"},
    {"id": "doubao-seedance-2-0-mini-260615", "object": "model"}
  ]
}

只返回你有权限且平台已开通的模型。可用模型以此接口返回为准,下文 §3.8 为参考。

3.8 模型与规格支持

传入模型不支持的分辨率会返回 400;duration: -1 仅 Seedance 2.5 支持。权威模型列表以 GET /v1/models(§3.7)为准。

Seedance 2.5 的参考素材上限:视频 ≤30 个、图片 ≤10、音频 ≤10,单任务合计 ≤50 个。

4K 档说明:计费量约为 1080p 的 4 倍(4 秒 ≈ 77.76 万 tokens),但 4K 档 token 单价较低,实际费用约为 1080p 的 2 倍;单价见控制台「费用中心」。

4. 并发与限流

• 每个租户有并发上限(默认 10,可协商调整)。并发计入 queued + running 的任务。
• 超出上限时按你的租户策略处理:
• 排队模式(默认):任务落入本地队列,有空位自动提交。队列满或等待超时(默认 600 秒)返回 429 / 转 expired。
• 拒绝模式:立即返回 429。

429 响应

{"error": {"code": "Throttling", "message": "并发已达上限,请稍后重试"}}

拒绝模式下带 Retry-After: 5 响应头。

客户端建议:收到 429 按指数退避重试(5s / 10s / 20s / 40s),配合 Idempotency-Key 保证重试不重复扣费。

5. Webhook 回调

配置方式二选一:

• 租户级:控制台「设置」→ Webhook URL + Secret,对所有任务生效。
• 任务级:创建任务时传 callback_url,仅对该任务生效,优先级更高。

任务进入终态时推送。

请求

POST <你的 URL>
Content-Type: application/json
X-Relay-Timestamp: 1786886512
X-Relay-Signature: 3f2a9c...

请求体与 §3.3 查询响应完全一致。

验签

X-Relay-Signature = hex(HMAC-SHA256(secret, timestamp + "." + rawBody))

Python 示例:

import hmac, hashlib, time

def verify(secret: str, ts: str, raw_body: bytes, sig: str) -> bool:
    if abs(time.time() - int(ts)) > 300:      # 拒绝 5 分钟外的重放
        return False
    mac = hmac.new(secret.encode(),
                   (ts + ".").encode() + raw_body,
                   hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, sig)

必须用原始字节计算,不要先反序列化再重新序列化 JSON。

重试:非 2xx 响应会重投,总投递次数上限 5 次(首投 + 4 次重试),退避 20s / 40s / 80s / 160s。5 次全失败标记为 failed,可在控制台「Webhook」手动重推。

你的接口要求:快速返回 2xx(15 秒超时),业务处理异步化;按 id 做幂等(同一任务可能收到多次)。

强烈建议:在成功回调里立刻触发你的视频转存流程——§6 的 24 小时时效从任务成功即开始计算。

6. 视频文件(⚠️ 24 小时时效,务必及时转存)

成功任务的 content.video_url / last_frame_url 是模型服务方的临时签名地址,约 24 小时后失效。

收到 succeeded 后请立即下载转存到你自己的存储(对象存储/CDN)。平台不保存生成产物, 24 小时后该任务的视频将无法再获取(任务记录与计费信息仍可查)。

• 直接 GET 下载,不需要 Authorization 头。
• 推荐配合 Webhook(§5):收到成功回调即触发你的转存流程,避免轮询间隙浪费时效。
• 二次创作(视频延长/编辑)引用产物同样受 24 小时窗口约束,请尽快发起。
• 你上传的参考素材不受此限:素材由平台托管,下载地址(URL)可随时经素材详情接口重新签发。

如你的业务需要平台代管生成产物(平台侧转存、30 天持久地址),可联系平台按租户开通「转存模式」。

7. 计费

7.1 计费模式

按商务约定二选一,可在控制台「费用中心」查看你的模式与余量:

按额度(默认):平台分配余额(元),任务按 单价 × 计费量 扣费。 - 单价维度:模型 × 场景 × 分辨率;content 中含 video_url 的请求按视频参考场景计价(单价低于纯生成,但 token 总量更大)。 - 你的专属价格表见控制台「费用中心」(单价单位:元/百万 tokens,与火山官方报价同口径)。 - 单价在创建任务时快照进任务,之后平台调价不影响已创建的任务。 - 计费币种为人民币(CNY)。

按模型 Token 池:按模型分配 token 配额(如 "2.0 的 100 万 tokens"),任务直接从对应模型的池子扣计费量 tokens,各模型独立计量、互不挪用,不涉及金额换算。控制台「费用中心」可查各池余量、Token 流水,并按模型提交配额申请。

两种模式共同规则: - 创建任务时按预估冻结,终态后按实际计费量结算并释放差额(duration: -1 的任务按该模型最长时长预估冻结)。 - failed / cancelled / expired 全额释放,不计费。 - 额度/配额不足时创建任务返回 403 QuotaExceeded,可在控制台提交调额申请。

7.2 计费量口径

usage.total_tokens 即计费量,与账单严格一致:

计费量以模型实际返回用量为准(usage.total_tokens 即账单量)。下表为各档的参考估算(实际生产会有小幅偏差),用于预估成本与核对量级:

计费 tokens = 编码宽 × 编码高 × (24 × 输出秒数 + 1) ÷ 1024

估算公式:宽 × 高 × (24 × 秒 + 1) ÷ 1024(4K 档无 +1 常数);Seedance 2.5 的编码尺寸为标准像素。

视频参考任务(content 含 video_url)按模型实际处理量计费:输入视频时长同样消耗 tokens,且存在最低用量,以任务成功后返回的 usage.total_tokens 为准。

素材与真人认证接口均不消耗视频额度。

8. 素材库与真人认证(可选)

两种"把内容带进生成"的方式,按需选用:

所有资源按租户隔离(跨租户访问一律 404)。

8.1 素材库(平台托管)

素材由平台统一托管:上传即返回素材 ID(即时可用),平台在生成时自动把素材分发到执行线路——你无需关心素材存在哪条线路,服务线路故障或调整也不影响你的素材与引用。

POST   /api/seedance/proxy/assets/groups        创建素材组(即时)
GET    /api/seedance/proxy/assets/groups        素材组列表
GET    /api/seedance/proxy/assets/groups/{id}   素材组详情
PUT    /api/seedance/proxy/assets/groups/{id}   更新
DELETE /api/seedance/proxy/assets/groups/{id}   删除(组内须无素材)

POST   /api/seedance/proxy/assets               创建素材(需先有素材组)
GET    /api/seedance/proxy/assets               素材列表(?GroupId=)
GET    /api/seedance/proxy/assets/{id}          素材详情(含可下载的 URL)
PUT    /api/seedance/proxy/assets/{id}          更新
DELETE /api/seedance/proxy/assets/{id}          删除

鉴权同 §2(Bearer)。请求体与响应体与火山官方素材接口同构(PascalCase 字段,Result 包裹):资源 ID 形如 asset-yyyymmddHHmmss-xxxxx / group-yyyymmddHHmmss-xxxxx,CreateTime 为东八区 RFC3339 时间字符串(如 2026-08-26T18:00:00+08:00)。

关键字段

素材引用:在视频任务 content 对应媒体对象的 url 字段填 asset://{asset_id}。

• 素材不锁定服务线路,任务照常自动调度;素材首次在某条线路使用时,平台会现场分发(该任务可能多等约 10–30 秒,同素材的后续任务无感)。
• 引用他人素材返回 404;素材未就绪(刚上传或被内容审核拒绝)返回 400。
• 素材规格上限(供参考):图片 ≤30MB,视频 ≤200MB / 2–15 秒,音频 ≤15MB / 2–15 秒。

8.2 真人认证(使用特定真人形象)

官方合规要求:含真人人脸的图/视频不能直接作为输入(会被 InputImageSensitiveContentDetected.PrivacyInformation 拦截),必须先经本人活体认证授权:

POST   /api/seedance/face-verifications         发起真人认证
GET    /api/seedance/face-verifications/{id}    认证结果

流程:

1. POST /api/seedance/face-verifications(body 可为空,部分线路支持 return_url)→ 返回 verification_id、h5_url,以及 expires_in/expires_at(H5 会话时效,通常很短,拿到后立即引导用户打开)
2. 将 h5_url 交给被授权的真人本人在手机浏览器打开,按页面提示完成活体认证(受光线/角度影响有概率不通过,可重试)
3. 轮询 GET /api/seedance/face-verifications/{id}:waiting_user = 未完成(若响应带 note 提示会话过期,重新从第 1 步创建);verified = 成功,取得 group_id(真人人像组);failed/expired = 需重新发起
4. 向该 group_id 上传该本人的图片/视频/音频(同 §8.1 素材接口;上游会做人脸一致性校验,建议清晰正面照,视频逐秒抽帧全部通过才入库),素材 Active 后以 asset://{asset_id} 引用
5. 同一人像组支持同一人的多套妆造素材,认证一次即可;不同人物请分别认证、分组

注意:真人素材与认证线路绑定(授权按线路账号成立),引用真人素材的任务固定在该线路执行——这是 §8.1「素材不锁线路」的唯一例外。

9. 火山方舟原生兼容入口(可选)

如果你已有基于火山官方 SDK 的素材库代码,可直接换 Endpoint 接入,不改签名逻辑:

POST https://api.somobai.com/?Action={Action}&Version=2024-01-01

AK/SK 在控制台「设置」创建。支持的 Action:

CreateAssetGroup ListAssetGroups GetAssetGroup UpdateAssetGroup DeleteAssetGroup CreateAsset ListAssets GetAsset UpdateAsset DeleteAsset

响应用 ResponseMetadata / Result 包裹,与火山官方格式一致;与 §8.1 REST 接口操作同一套平台素材库,可混用。ProjectName 等项目/凭证类字段由平台自动处理,不需要也不应传入。

视频生成任务与真人认证请走 Bearer 接口(§3 / §8.2),火山签名入口目前覆盖素材库。

10. 错误格式总表

所有数据面错误统一格式:

{"error": {"code": "错误码", "message": "错误描述"}}

11. 接入 Checklist

• [ ] 令牌存入密钥管理系统,不硬编码、不进代码仓库
• [ ] 所有创建请求带 Idempotency-Key(用业务单号)
• [ ] 429 / 502 / 500 按指数退避重试;400 / 403 不重试
• [ ] 配置 Webhook 替代高频轮询,并实现验签 + 时间戳校验 + 按 id 幂等
• [ ] 成功回调里立即转存 video_url(24 小时时效,平台不保存生成产物)
• [ ] 含特定真人形象的业务:先完成真人认证(§8.2),再上传并引用人像素材
• [ ] 以 GET /v1/models 为准选择模型;2.0 系列传正整数 duration,仅 2.5 可用 -1
• [ ] 状态机只处理 6 个对外状态,未知状态按「进行中」兜底
• [ ] 对账用 usage.total_tokens(即计费量)核对控制台「费用中心」流水
• [ ] 生产前用小额度跑通全链路

12. 变更记录