8848视频模型API说明

2. 当前视频模型

网关当前校验范围

以下是当前版本接纳的主要规格，不等于所有供应商对每种输入组合均已验证。分辨率、时长和价格须同时满足模型与实际可用线路的要求。

duration: -1 是允许型号的自动时长选项，不是无限时长或免费选项；预扣可能按型号最长时长估算，再按实际用量结算。建议初次接入先用本文明确的短时长。不要同时传 duration、seconds 和 metadata 中相互冲突的时长。

3. 通用提交：先保存 JSON，再创建一次

从下方模型章节选择一个 JSON，保存为 video-request.json。每个业务视频生成一个固定的唯一键，并持久化；示例中的 YOUR_UNIQUE_VIDEO_ORDER_ID 必须替换，不同任务不能共用同一个键。

export VIDEO_ORDER_ID='YOUR_UNIQUE_VIDEO_ORDER_ID'
curl --fail-with-body "$API_BASE/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $VIDEO_ORDER_ID" \
  --data-binary @video-request.json \
  -o video-create.json

成功受理通常为 HTTP 200，示例：

{
  "id": "task_EXAMPLE",
  "task_id": "task_EXAMPLE",
  "object": "video",
  "model": "doubao-seedance-2-5-260628",
  "status": "queued",
  "progress": 0,
  "created_at": 1792020000
}

统一以 id 保存公开任务编号，兼容响应可能另含相同的 task_id。不要把厂商的 cgt-* 编号替代平台任务编号用于查询。TASK_ID 设置为实际返回值后，再执行第 7 节的查询。

4. Seedance：文字与单参考图

以下使用 doubao-seedance-2-5-260628，resolution 示例为小写 480p；选择短片先确认内容和计价，不要直接批量调用。

4.1 文生视频

{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "湖面晨雾缓慢流动，远处山峰静止，镜头固定，无人物",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "generate_audio": false,
  "watermark": false
}

4.2 单图作为首帧

沿用同一提交接口，使用带角色的 content。示例图片地址仅为占位值，必须换成实际可访问、允许用于生成的图片；本地路径不能直接填入 URL。

{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "保留参考图中的山峰、湖泊和构图，水面产生轻微涟漪，固定镜头",
  "duration": 4,
  "resolution": "480p",
  "ratio": "adaptive",
  "content": [
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://example.com/reference.png" }
    }
  ],
  "generate_audio": false,
  "watermark": false
}

• first_frame 表示起始画面，reference_image 表示参考而非锁定起始帧；不要依赖提示词代替角色字段。
• 同一请求不要同时以 content、media、images 重复传同一组图片，避免图片被重复投影或角色冲突。
• 本页 Seedance 输入使用 HTTP(S) 或有效 asset:// 引用，不直接接收图片 Base64 或 multipart 文件。不要把同步生图的文件上传格式照搬到视频接口。
• generate_audio、watermark 使用 JSON 布尔值，不要传字符串 "false"。可用性仍受型号和供应商约束。
• 使用已注册素材时，图片地址可按适用的模型和凭证空间使用 asset://asset-*，见第 8 节；素材注册不是所有普通图片的必选步骤，也不豁免真人授权和内容审核。

5. Wan 3.0：文字、首帧与首尾帧

示例使用 wan3.0-video；选择 Prime 时使用完整模型名 wan3.0-video-prime。resolution 示例为大写 480P。

5.1 文生视频

{
  "model": "wan3.0-video",
  "prompt": "一只纸船漂过安静的湖面，固定镜头，柔和晨光",
  "duration": 2,
  "resolution": "480P",
  "ratio": "16:9",
  "audio": false,
  "watermark": false,
  "prompt_extend": false
}

5.2 图生视频

{
  "model": "wan3.0-video",
  "prompt": "保留参考图构图，水面轻微波动，镜头缓慢前推",
  "duration": 2,
  "resolution": "480P",
  "ratio": "adaptive",
  "media": [
    { "type": "first_frame", "url": "https://example.com/first.png" }
  ],
  "audio": false,
  "watermark": false,
  "prompt_extend": false
}

需要首尾帧时，将 media 替换为下面的数组；必须保留首帧，不能只传尾帧：

[
  { "type": "first_frame", "url": "https://example.com/first.png" },
  { "type": "last_frame", "url": "https://example.com/last.png" }
]

输入图片可以使用合规公网 HTTP(S) URL，或在接口与供应商均支持时使用完整的 data:image/png;base64,... 图片 Data URL；不能填浏览器 blob: 或本地文件路径。图片请求的最终比例、像素与时长以返回内容为准。

6. HappyHorse 1.1：选择对应输入型号

6.1 T2V：文字

{
  "model": "happyhorse-1.1-t2v",
  "prompt": "一只纸船漂过安静的湖面，固定镜头，柔和晨光",
  "duration": 3,
  "resolution": "480P",
  "ratio": "16:9"
}

6.2 I2V：首帧图片

{
  "model": "happyhorse-1.1-i2v",
  "prompt": "保留参考图中的主体和构图，水面产生轻微涟漪，镜头固定",
  "duration": 3,
  "resolution": "480P",
  "media": [
    { "type": "first_frame", "url": "https://example.com/first.png" }
  ],
  "audio": false,
  "watermark": false,
  "prompt_extend": false
}

6.3 R2V：参考图片

{
  "model": "happyhorse-1.1-r2v",
  "prompt": "以参考图片中的产品为主体，生成柔和灯光下的展示镜头",
  "duration": 3,
  "resolution": "480P",
  "ratio": "16:9",
  "media": [
    { "type": "reference_image", "url": "https://example.com/reference.png" }
  ]
}

• T2V 不传图片；I2V 必须恰好一个 first_frame；R2V 使用 1–9 张 reference_image。当前 HappyHorse 不支持尾帧，不能照搬 Wan 的首尾帧数组。
• HappyHorse 图片可使用供应商支持的公网 URL 或完整图片 Data URL，不使用火山的 asset:// 素材标识。
• 音轨不能只看请求判断：已有实测曾在 audio: false 时仍得到带 AAC 音轨的视频。本文不承诺该参数必然移除音轨；若业务必须静音，需检查成片并在自己的后处理链路静音。

7. 查询、状态与原厂视频下载

把创建响应的 id 设置为 TASK_ID。以下命令只查询已有任务，不创建视频：

export TASK_ID='task_REPLACE_WITH_RETURNED_ID'
curl --fail-with-body "$API_BASE/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -o video-task.json

成功查询会保留厂商业务扩展字段，不同模型的 metadata 和 usage 不完全相同。Seedance 完成态示意：

{
  "id": "task_EXAMPLE",
  "object": "video",
  "model": "doubao-seedance-2-5-260628",
  "status": "completed",
  "progress": 100,
  "created_at": 1792020000,
  "completed_at": 1792020200,
  "result_url": "https://example.com/temporary-original.mp4",
  "metadata": {
    "url": "https://example.com/temporary-original.mp4",
    "duration": 4,
    "resolution": "480p"
  },
  "usage": {
    "completion_tokens": 38809,
    "total_tokens": 38809
  }
}

• 示例编号、地址和用量仅展示字段形状；不要对所有模型强求完全相同的 JSON。
• 读取顶层平台状态控制轮询，不用 metadata.status 的厂商状态替代它。progress 不是精确剩余时间。
• Seedance 原厂任务号可能出现在 provider_task_id 或 metadata.id，受平台展示开关控制，不保证始终返回；查询始终使用平台 task_*。
• 原厂视频地址可能在 result_url、metadata.url、content.video_url 或 output.video_url，以实际回包为准。没有可用地址时，不要把任务重新标为失败或自动重做。

7.1 从统一成品入口下载

curl --fail-with-body --location \
  --proto '=https' --proto-redir '=https' \
  "$API_BASE/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o video.mp4

对本页当前官方视频链路，已完成且有源地址的任务通常返回 307，正文为 0，Location 指向原厂临时 URL；上面通过 --location 跟随跳转。curl 默认不把 Authorization 转发给不同主机，不要加 --location-trusted，也不要主动把平台 API Key 发给原厂对象存储域名。

也可以将查询返回的原厂完整地址设置为 VIDEO_URL 后直接下载，保留原始签名参数，不附加平台令牌：

curl --fail-with-body --location \
  --proto '=https' --proto-redir '=https' \
  "$VIDEO_URL" -o video.mp4

7.2 检查成片

已安装 ffprobe 时，可离线检查时长、尺寸和音轨，不产生生成费用：

ffprobe -v error \
  -show_entries stream=codec_type,width,height,duration \
  -show_entries format=duration \
  -of json video.mp4

实际输出时长、像素和音轨可能与请求值不同；生成效果与参考图遵循程度不作百分之百保证。

8. Seedance 素材与授权边界

Seedance 的 asset://asset-* 是厂商素材引用，不是平台任务号、分组号或文件路径。已注册素材必须属于可用的同一素材凭证空间；不能跨供应商、跨账号复制使用。

使用素材管理能力时，主站入口为 POST /api/volcengine_asset?Action=...&Version=2024-01-01，沿用主站 Bearer API 令牌，Action 与正文区分大小写：

• 素材接口不是本页视频提交幂等机制的一部分；创建结果不明时先核对已有素材，不默认重复创建安全。
• B 端接入方须自行校验下级用户的素材归属与授权；本文不承诺平台已经完成所有下级用户素材隔离，不能把知道素材 ID 等同于有权使用。
• 普通 AIGC 图片、真实人物肖像的验证要求不同。使用真实人物、声音或其他受保护素材前必须取得合法授权，按供应商适用规则完成认证和内容审核；注册素材不能绕过这些要求。
• credential_space_unavailable 等配置或绑定错误应联系平台，不换账号或渠道试图绕过。旧 /v1/assets、/v1/asset-groups 及旧 person-auth 会话接口不可作为当前接入方案。

9. 幂等、费用与错误处理

9.1 费用与任务身份

• 当前视频采用预扣后结算差额：提交时需要足够的账户和令牌额度，完成后按实际用量与适用计价补扣或退款；不要按旧 Seedance 专属后付费逻辑设计余额检查。
• 不同模型的定价维度可能是 Token、秒数或已配置的表达式。usage 与平台日志按真实维度理解，不把 Wan/HappyHorse 的兼容秒数字段当成真正 Token 数；以模型价格页和账务记录为准，本文不写固定单价。
• 查询已有任务和下载已有成品不会主动创建新生成任务。服务端可能有渠道重试；视频幂等不代表供应商永远只执行一次。
• 为新业务生成新键；视频键最多 191 字节（UTF-8）。重复同键出现 409 时先找回原任务，不能套用异步生图“同正文返回 200”的规则，也不能把改正文当作新任务。

客户端应持久化业务订单、原始请求、Idempotency-Key、平台任务 ID、状态、已下载记录与失败正文；程序重启后继续查询已有任务。不要公开日志中的完整签名地址、令牌、个人素材或认证信息。

本页示例覆盖统一视频生命周期及各系列常用输入，并非完整厂商 API 清单。低层原生路由有不同的参数和响应结构，不要把厂商接口路径直接拼接到主站；没有额外说明时优先使用本页 /v1/videos。