视频生成 API

本教程将介绍如何使用视频生成 API 来创建和查询视频生成任务。

接口概览

接口	方法	路径	说明
创建视频生成任务	POST	`/v3/contents/generations/tasks`	提交视频生成任务，返回任务 ID
查询视频生成任务	GET	`/v3/contents/generations/tasks/{taskId}`	查询任务状态和获取视频结果

调用地址

环境	Base URL
测试环境（网关）	`https://aitest.newtouch.com/aifusion/ai`
生产环境（网关）	`https://aifusion.newwtouch.com/ai`

接口一：创建视频生成任务

基本信息

项目	说明
路径	`/v3/contents/generations/tasks`
方法	POST
Content-Type	application/json
认证方式	Bearer Token（请求头 Authorization）

请求头

参数名	类型	必填	说明
`Authorization`	string	✅	格式：`Bearer {apiKey}`
`Content-Type`	string	✅	固定值：`application/json`

请求参数（Body）

参数名	类型	必填	说明
`model`	string	✅	模型 ID，如 `doubao-seedance-2-0`
`content`	array	✅	输入内容数组（文本/图片/音频/视频）
`callback_url`	string		回调通知地址
`return_last_frame`	boolean		是否返回尾帧图片
`service_tier`	string		服务等级：`default`(默认) / `flex`(离线，50% 价格)
`execution_expires_after`	integer		任务超时时间 (秒)，范围 [3600, 259200]，默认 172800
`generate_audio`	boolean		是否生成音频（Seedance 2.0/1.5 pro 支持）
`draft`	boolean		是否开启样片模式（Seedance 1.5 pro）
`safety_identifier`	string		终端用户标识，≤64 字符
`priority`	integer		执行优先级 [0,9]（Seedance 2.0）
`resolution`	string		分辨率：`480p` / `720p`(默认) / `1080p`
`ratio`	string		宽高比：`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`(默认)
`duration`	integer		视频时长 (秒)，Seedance 2.0: [4,15]，默认 5
`frames`	integer		视频帧数（Seedance 1.0 系列）
`seed`	integer		随机种子 [-1, 2^32-1]，默认 -1
`camera_fixed`	boolean		是否固定摄像头（Seedance 1.0/1.5）
`watermark`	boolean		是否添加”AI 生成”水印
`tools`	array		工具配置，如联网搜索

content 数组项说明

文本信息

字段	类型	必填	说明
`type`	string	✅	固定值：`text`
`text`	string	✅	文本提示词，中文≤500 字，英文≤1000 词

图片信息

字段	类型	必填	说明
`type`	string	✅	固定值：`image_url`
`image_url.url`	string	✅	图片 URL / Base64 / 素材 ID
`role`	string	条件必填	`first_frame` / `last_frame` / `reference_image`

视频信息（Seedance 2.0）

字段	类型	必填	说明
`type`	string	✅	固定值：`video_url`
`video_url.url`	string	✅	视频 URL
`role`	string	✅	固定值：`reference_video`

音频信息（Seedance 2.0）

字段	类型	必填	说明
`type`	string	✅	固定值：`audio_url`
`audio_url.url`	string	✅	音频 URL
`role`	string	✅	固定值：`reference_audio`

样片信息（Seedance 1.5 pro）

字段	类型	必填	说明
`type`	string	✅	固定值：`draft_task`
`draft_task.id`	string	✅	Draft 任务 ID

响应参数

参数名	类型	说明
`id`	string	视频生成任务 ID（仅保存 7 天）

请求示例

示例 1：文生视频

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "一只可爱的小猫在阳光下奔跑"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}

示例 2：图生视频 - 首帧模式

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "女孩抱着狐狸，女孩睁开眼，温柔地看向镜头，狐狸友善地抱着，镜头缓缓拉出，女孩的头发被风吹动，可以听到风声"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
      }
    }
  ],
  "generate_audio": true,
  "ratio": "adaptive",
  "duration": 5,
  "watermark": false
}

示例 3：图生视频 - 首尾帧模式

{
    "model": "doubao-seedance-1-5-pro-251215",
    "content": [
         {
            "type": "text",
            "text": "图中女孩对着镜头说"茄子"，360 度环绕运镜"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ],
    "generate_audio":true,
    "ratio": "adaptive",
    "duration": 5,
    "watermark": false
}

示例 4：多模态参考生视频（图片 + 音频）

{
    "model": "doubao-seedance-2-0-260128",
    "content": [
         {
            "type": "text",
            "text": "全程使用视频 1 的第一视角构图，全程使用音频 1 作为背景音乐。第一人称视角果茶宣传广告，seedance 牌「苹苹安安」苹果果茶限定款；首帧为图片 1，你的手摘下一颗带晨露的阿克苏红苹果，轻脆的苹果碰撞声；2-4 秒：快速切镜，你的手将苹果块投入雪克杯，加入冰块与茶底，用力摇晃，冰块碰撞声与摇晃声卡点轻快鼓点，背景音：「鲜切现摇」；4-6 秒：第一人称成品特写，分层果茶倒入透明杯，你的手轻挤奶盖在顶部铺展，在杯身贴上粉红包标，镜头拉近看奶盖与果茶的分层纹理；6-8 秒：第一人称手持举杯，你将图片 2 中的果茶举到镜头前（模拟递到观众面前的视角），杯身标签清晰可见，背景音「来一口鲜爽」，尾帧定格为图片 2。背景声音统一为女生音色。"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
            },
            "role": "reference_image"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
            },
            "role": "reference_image"
        },
        {
          "type": "video_url",
          "video_url": {
              "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
          },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": {
              "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
          },
          "role": "reference_audio"
        }
    ],
    "generate_audio":true,
    "ratio": "16:9",
    "duration": 11,
    "watermark": false
}

接口二：查询视频生成任务

基本信息

项目	说明
路径	`/v3/contents/generations/tasks/{taskId}`
方法	GET
认证方式	Bearer Token（请求头 Authorization）

请求头

参数名	类型	必填	说明
`Authorization`	string	✅	格式：`Bearer {apiKey}`

路径参数

参数名	类型	必填	说明
`taskId`	string	✅	视频生成任务 ID

查询参数

参数名	类型	必填	说明
`model`	string	✅	模型 ID

响应参数

参数名	类型	说明
`id`	string	任务 ID
`status`	string	任务状态：`queued` / `running` / `succeeded` / `failed` / `expired`
`model`	string	模型 ID
`output`	array	输出结果数组
`usage`	object	用量信息
`error`	object	错误信息（失败时）

output 数组项说明

参数名	类型	说明
`type`	string	输出类型：`video_url` / `image_url`
`video_url.url`	string	生成的视频 URL
`image_url.url`	string	尾帧图片 URL（当 `return_last_frame=true`）

usage 说明

参数名	类型	说明
`completion_tokens`	integer	生成的 token 数
`total_tokens`	integer	总 token 数

请求示例

GET /v3/contents/generations/tasks/task_xxxxxxxxxxxxxxxx?model=doubao-seedance-2-0
Authorization: Bearer YOUR_API_KEY

响应示例

任务进行中

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "running",
  "model": "doubao-seedance-2-0",
  "created_at": 1717920000
}

任务成功

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "succeeded",
  "model": "doubao-seedance-2-0",
  "created_at": 1717920000,
  "completed_at": 1717920300,
  "output": [
    {
      "type": "video_url",
      "video_url": {
        "url": "https://tos-cn-beijing.volces.com/xxx/generated_video.mp4?X-Tos-xxx"
      }
    }
  ],
  "usage": {
    "completion_tokens": 100,
    "total_tokens": 100
  }
}

任务成功（含尾帧）

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "succeeded",
  "model": "doubao-seedance-2-0",
  "output": [
    {
      "type": "video_url",
      "video_url": {
        "url": "https://tos-cn-beijing.volces.com/xxx/generated_video.mp4"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://tos-cn-beijing.volces.com/xxx/last_frame.png"
      }
    }
  ],
  "usage": {
    "completion_tokens": 100,
    "total_tokens": 100
  }
}

任务失败

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "failed",
  "model": "doubao-seedance-2-0",
  "error": {
    "code": "content_violation",
    "message": "内容审核未通过"
  }
}

模型能力对照表

模型	文生视频	图生视频 - 首帧	图生视频 - 首尾帧	多模态参考	有声视频	Draft 模式
Seedance 2.0	✅	✅	✅	✅	✅	❌
Seedance 1.5 pro	✅	✅	✅	❌	✅	✅
Seedance 1.0 pro	✅	✅	✅	❌	❌	❌
Seedance 1.0 pro fast	✅	✅	❌	❌	❌	❌

调用流程示意

┌─────────────────────────────────────────────────────────────┐
│                      客户端调用流程                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. POST /v3/contents/generations/tasks                     │
│     ↓                                                       │
│     返回 { "id": "task_xxx" }                               │
│                                                             │
│  2. 轮询 GET /v3/contents/generations/tasks/{task_id}       │
│     ↓                                                       │
│     status: queued → running → succeeded/failed             │
│                                                             │
│  3. status === "succeeded"                                  │
│     ↓                                                       │
│     从 output[0].video_url.url 获取视频地址                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

注意事项

任务有效期: task_id 仅保存 7 天，超时自动清除
异步接口: 创建任务后需轮询查询接口获取结果
账户余额: 开通 Seedance 2.0 需余额 ≥ 200 元或已购资源包
人脸限制: Seedance 2.0 不支持直接上传含真人人脸的参考图
图片要求: 格式 jpeg/png/webp/bmp/tiff/gif/heic/heif，≤30MB
视频时长: duration 设置 -1 时由模型智能选择，需谨慎使用
接口对齐: 本接口的请求参数和响应参数与 Seedance 官方 API 完全对齐，可直接参考官方文档获取更详细的参数说明