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

版本 v3 · 2026-08-23 · 影枢 YingShu 视频生成平台

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

1. 快速开始

三步跑通:

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

# 2. 创建视频任务
curl -X POST https://api.xmjiaqu.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":"task_db649a073372bb26cb1c700f"}

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

2. 认证

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

Authorization: Bearer sk-xxxxxxxxxxxx

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

认证失败

3. 视频生成

3.1 创建任务

POST /api/v3/contents/generations/tasks

请求头

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

• content[].image_url.url 等媒体地址可填公网 HTTPS URL,或平台资源引用 asset://{id}——素材(§8.1)与角色(§8.3)通用同一语法。
• 输入含真人人脸的图/视频会被内容审核拦截(InputImageSensitiveContentDetected.PrivacyInformation),处理路径见 §8.2(真人认证)与 §8.3(角色工坊)。
• safety_identifier 由平台自动注入租户隔离标识,无需传入,传入将被忽略。
• 其余官方字段原样透传给模型。

响应 200

{"id": "task_db649a073372bb26cb1c700f"}

任务 ID 格式为 task_ + 24 位十六进制。

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

错误

3.2 幂等

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

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

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

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

3.3 查询任务

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

进行中

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

成功

{
  "id": "task_db649a073372bb26cb1c700f",
  "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": "task_db649a073372bb26cb1c700f",
  "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": "task_xxx", "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-0-260128", "object": "model"},
    {"id": "doubao-seedance-2-0-fast-260128", "object": "model"},
    {"id": "doubao-seedance-2-0-mini-260615", "object": "model"}
  ]
}

只返回你有权限且平台已开通的模型。

3.8 模型与规格支持

传入模型不支持的分辨率会返回 400。

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 小时窗口约束,请尽快发起。
• 你上传的参考素材不受此限:素材由平台托管,AssetUrl 可随时经素材详情接口重新签发。
• 角色续期不受此限:引用角色的任务,平台自动留存尾帧,见 §8.3。

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

7. 计费

7.1 计费模式

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

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

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

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

7.2 计费量口径

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

纯生成任务(content 不含 video_url)按平台统一公式计算,与执行线路无关:

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

宽高比不影响计费(按分辨率档位统一计量)。

视频参考任务(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}          素材详情(含可下载的 AssetUrl)
PUT    /api/seedance/proxy/assets/{id}          更新
DELETE /api/seedance/proxy/assets/{id}          删除

鉴权同 §2(Bearer)。请求体与响应体与火山官方素材接口同构(PascalCase 字段,Result 包裹)。

关键字段

素材引用:在视频任务 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「素材不锁线路」的唯一例外。

若返回 501 console_flow_required:该线路的真人认证走线下/控制台流程,请联系平台切换线路或代办授权。

8.3 角色工坊(AI 角色与定妆照)

如果你只需要「神似参考图的真人感角色」而非特定真人本人,用角色工坊——一次创建,反复引用,不触发真人审核拦截:

POST   /api/seedance/characters              创建角色 {name, image_url | prompt} → 返回候选(draft)
GET    /api/seedance/characters              角色列表
GET    /api/seedance/characters/{id}         角色详情(draft 含候选列表)
POST   /api/seedance/characters/{id}/select  选定候选 {index} ← 定妆照由你亲自选,平台不代选
POST   /api/seedance/characters/{id}/reroll  重绘一批候选 {prompt?}
POST   /api/seedance/characters/{id}/renew   续期 {task_id}
DELETE /api/seedance/characters/{id}

工作原理:你传一张参考图(或直接写文字描述)→ 平台用视觉模型生成外貌描述 → 以可信文生图并行产出多张候选定妆照(有参考图时附相似度评分供参考)→ 由你选定一张作为角色的唯一定妆照。定妆照是平台侧的可信模型产物,作为生成输入不会触发真人拦截——角色的脸由定妆照锚定,反复引用保持一致。选定前角色为 draft 状态,不可引用(引用返回 400 提示)。

创建(约 90 秒返回候选):

curl -X POST https://api.xmjiaqu.com/api/seedance/characters \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{"name": "清雅", "image_url": "https://your.cdn/face.jpg"}'

{
  "character": {"id": "char-94dc63ba617b79100c2c", "name": "清雅", "status": "draft"},
  "candidates": [
    {"index": 0, "score": 72, "preview_url": "https://…(候选预览,24h 签名)"},
    {"index": 2, "score": 76, "preview_url": "https://…"}
  ],
  "deduplicated": false
}

选定(选中的成为唯一定妆照,其余候选删除;角色转 active 后即可引用):

curl -X POST https://api.xmjiaqu.com/api/seedance/characters/char-94dc63ba617b79100c2c/select \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{"index": 2}'

评分是结构相似度参考值(骨相/眉眼加权),最终以你的眼睛为准;控制台「我的角色」提供可视化选片。

• image_url 与 prompt 二选一:传图 = 平台自动生成外貌描述;传 prompt = 按你的文字直接造角色。
• 参考图只用于生成描述,平台不保存原图;含真人的图也可以传(产出的是"神似"的虚构角色,见下方边界说明)。
• 同一参考图重复提交自动去重(返回 deduplicated: true 与已有角色,不重复消耗)。
• 对形象不满意:reroll 重抽定妆照,可带修改后的 prompt(描述是可编辑的),直到满意。

引用生成:content 媒体对象的 url 填 asset://char-…,平台自动注入定妆照并调度到正确线路。提示词中仍用「图片N」指代(与官方素材规则一致,不能写角色 ID):

{
  "model": "doubao-seedance-2-0-260128",
  "return_last_frame": true,
  "content": [
    {"type": "text", "text": "图片1中的女子在书店翻开一本书,抬头对镜头微笑,写实风格,人脸始终清晰稳定"},
    {"type": "image_url", "image_url": {"url": "asset://char-526fc902e57b4075c780"}, "role": "first_frame"}
  ]
}

信任窗口与续期:

• 角色定妆照的可信期为 30 天(trust_expires_at),过期后引用返回 400。
• 续期零成本:拿任一「引用过该角色、已成功、创建时设了 return_last_frame: true」的任务 task_id 调 renew,即以其尾帧重新锚定并重开 30 天(脸的连续性由生成本身保证)。
• 引用角色的任务,其尾帧由平台自动留存——续期不受生成产物 24 小时时效限制,随时可续。
• 引用了其他角色的任务不能用于本角色续期(400);长期不用导致过期的角色,reroll 重绘即可复活。

边界说明(请按此口径设定终端用户预期):角色是"神似参考图的虚构角色",不是照片中人物本人——文字描述能锁住发型、脸型、气质、妆容,但不承载生物特征,这正是它合规的原因。需要特定真人本人形象,走 §8.2 真人认证。

控制台「我的角色」页提供同等功能的可视化操作(创建 / 预览 / 重绘 / 删除)。

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

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

POST https://api.xmjiaqu.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.3),火山签名入口目前覆盖素材库。

10. 错误格式总表

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

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

11. 接入 Checklist

• [ ] 令牌存入密钥管理系统,不硬编码、不进代码仓库
• [ ] 所有创建请求带 Idempotency-Key(用业务单号)
• [ ] 429 / 502 / 500 按指数退避重试;400 / 403 不重试
• [ ] 配置 Webhook 替代高频轮询,并实现验签 + 时间戳校验 + 按 id 幂等
• [ ] 成功回调里立即转存 video_url(24 小时时效,平台不保存生成产物)
• [ ] 含人物的业务:确定走真人认证(§8.2)还是角色工坊(§8.3),并向终端用户设定正确预期
• [ ] 引用角色的任务开启 return_last_frame: true(续期素材)
• [ ] 状态机只处理 6 个对外状态,未知状态按「进行中」兜底
• [ ] 对账用 usage.total_tokens(即计费量)核对控制台「费用中心」流水
• [ ] 生产前用小额度跑通全链路

12. 变更记录