Doubao Seedance 2.0 hwzr版视频生成

功能概览

本页用于说明 Doubao Seedance 2.0 hwzr版视频生成 的核心能力、调用入口和接入要点，帮助开发者快速判断适用场景并完成集成。

适用场景

• 产品原型验证：快速接入模型能力，验证内容生成、理解或编辑流程。
• 生产业务接入：用于批量任务、自动化工作流和多模型组合调用。
• 能力迁移适配：适合从原有模型或 SDK 平滑切换到爱虾AI统一接口。

接入建议

• 优先确认模型名称、请求路径和响应字段，再接入具体业务流程。
• 对异步任务、媒体生成和长耗时请求，建议在业务侧加入重试与状态轮询。
• 上线前建议准备日志追踪、错误处理和内容安全校验，便于稳定运行。

接口总览

POST /v1/video/generations
GET  /v1/video/generations/{task_id}

路径中的 video 为单数。创建接口返回任务信息，视频生成在后台进行。

参数支持状态

使用参数时请遵守以下规则：

• 素材使用上游可以访问的公网 http:// 或 https:// URL。本接口采用 JSON，不接收 multipart 文件直传。
• 首帧、首尾帧、多模态参考三种模式选一种，不能混用。参考音频不能单独输入，需同时提供参考图片或视频。
• 布尔参数使用 JSON 的 true / false，不要传字符串。
• 同一参数只传一个名称。若同时传入别名，duration 优先于 seconds，ratio 优先于 aspect_ratio，images/videos/audios 优先于对应的 reference_*。
• 兼容 size，例如 1280x720、1920x1080、2560x1440、3840x2160，会转换为分辨率；resolution 优先，画幅仍需通过 ratio 指定。
• 接口会检查非空提示词、整数时长和分辨率；素材数量、模式组合、素材可用性等限制最终以上游校验结果为准。

content 结构

使用 content 传素材时，建议统一在该数组内表达素材和角色，避免重复传入顶层素材字段。传入 prompt 时优先使用它；未传或为空时，按顺序提取 content 中的文本项，并用换行连接。

POST /v1/video/generations

以下 cURL 示例适用于 Bash；Windows PowerShell 可使用下方的 PowerShell 示例。请替换 API Key 和素材地址。

文生视频

curl --max-time 120 'https://api.yisu-api.com/v1/video/generations' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.0-hwzr",
    "prompt": "海边日落，镜头缓慢向前推进，柔和的自然光",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true,
    "watermark": false
  }'

参考图生成视频

{
  "model": "doubao-seedance-2.0-hwzr",
  "prompt": "保持参考图中的人物和服装，人物缓慢走向镜头",
  "duration": 8,
  "ratio": "9:16",
  "resolution": "1080p",
  "images": ["https://example.com/reference.png"],
  "generate_audio": true
}

首尾帧生成视频

{
  "model": "doubao-seedance-2.0-hwzr",
  "prompt": "镜头从首帧平滑过渡到尾帧，保持人物一致",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "first_image": "https://example.com/first.png",
  "last_image": "https://example.com/last.png"
}

多模态参考生成视频

{
  "model": "doubao-seedance-2.0-hwzr",
  "prompt": "保持参考图的人物外观，参考视频的动作节奏和音频氛围",
  "duration": 10,
  "ratio": "16:9",
  "resolution": "2k",
  "images": ["https://example.com/character.png"],
  "videos": ["https://example.com/motion.mp4"],
  "audios": ["https://example.com/reference.mp3"],
  "generate_audio": true
}

使用 content

{
  "model": "doubao-seedance-2.0-hwzr",
  "content": [
    {"type": "text", "text": "根据参考图生成清新果茶广告"},
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/tea.png"},
      "role": "reference_image"
    }
  ],
  "duration": 8,
  "ratio": "9:16",
  "resolution": "720p"
}

以上 JSON 均发送到 POST /v1/video/generations。

Windows PowerShell 示例

$headers = @{ Authorization = 'Bearer <API_KEY>' }
$body = @{
    model = 'doubao-seedance-2.0-hwzr'
    prompt = '海边日落，镜头缓慢向前推进'
    duration = 5
    ratio = '16:9'
    resolution = '720p'
    generate_audio = $true
    watermark = $false
} | ConvertTo-Json -Depth 10

$created = Invoke-RestMethod -Method Post `
    -Uri 'https://api.yisu-api.com/v1/video/generations' `
    -Headers $headers -ContentType 'application/json; charset=utf-8' `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($body)) -TimeoutSec 120
$created | ConvertTo-Json -Depth 20

从创建响应中取出任务 ID 后查询：

$taskId = '替换为创建响应中的任务ID'
$encodedTaskId = [System.Uri]::EscapeDataString($taskId)
Invoke-RestMethod -Method Get `
    -Uri "https://api.yisu-api.com/v1/video/generations/$encodedTaskId" `
    -Headers $headers -TimeoutSec 120

查询视频任务

响应保留上游的顶层或 data 嵌套结构。以下为常见字段组合示意，并非固定响应模板；具体层级和字段以上游实际返回为准。

创建响应示意：

{
  "task_id": "task_xxx",
  "status": "QUEUED",
  "model": "doubao-seedance-2.0-hwzr"
}

查询成功响应示意：

{
  "data": {
    "task_id": "task_xxx",
    "status": "SUCCESS",
    "model": "doubao-seedance-2.0-hwzr",
    "result_url": "https://example.com/output.mp4"
  }
}

字段读取位置：

保存创建响应中的任务 ID，使用创建任务时同一账号的 API Key 查询；无需再次提交 model 或生成参数。任务 ID 作为路径段使用时应进行 URL 编码。

curl 'https://api.yisu-api.com/v1/video/generations/TASK_ID' \
  -H 'Authorization: Bearer <API_KEY>'

常见状态如下，调用方可先将状态转换为小写再判断：

查询返回 HTTP 200 也可能表示任务仍在生成，或任务已经失败；应结合任务状态判断。生成完成后使用返回的视频 URL 获取成片，并及时保存文件。本文仅定义创建、查询接口。