Seedance 视频生成 API

本文面向使用API Key 的调用方，介绍本平台的 Seedance 请求参数、首图与首尾图输入、任务查询和结果下载。

接入流程：创建任务 → 保存任务 ID → 轮询任务 → 获取视频地址。

1. 接入地址与鉴权

Base URL：https://token.kelly.cloud

用途	方法	路径
创建视频任务	POST	`/v1/video/generations`
查询单个视频任务	GET	`/v1/video/generations/{task_id}`

请求头：

使用平台签发的 API Key。本文示例中的素材 URL 需要替换为真实、可访问的地址。

2. 模型字段

创建任务使用小写字段 model，填写平台开放给当前令牌的完整模型名称。

模型名称	版本
`doubao-seedance-2-0-260128`	Seedance 2.0
`doubao-seedance-2-0-fast-260128`	Seedance 2.0
`doubao-seedance-2-0-mini-260615`	Seedance 2.0
`doubao-seedance-2-5-260628`	Seedance 2.5

本文采用 Seedance 的 model、prompt、content 字段，不使用其他视频接口的 ModelName、FileInfos 格式。不同模型的分辨率、时长和素材组合能力可能不同，不能仅替换模型名称就假定全部参数都支持。

3. 创建视频任务

3.1 文生视频

3.2 首图生成视频

首图放在 content 数组中，使用 type: "image_url"，并指定 role: "first_frame"。

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "以首图作为起始画面，人物缓慢抬头微笑，镜头轻轻推进，保持人物外观一致。",
  "content": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.png" },
      "role": "first_frame"
    }
  ],
  "seconds": "5",
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": false
}

将此 JSON 作为 POST /v1/video/generations 的请求体，鉴权与文生视频相同。

3.3 首尾图生成视频

首图使用 first_frame，尾图使用 last_frame。两张图片都放在同一个 content 数组中。

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "从首图的站立姿态自然过渡到尾图的挥手姿态，动作连贯，保持人物和背景一致。",
  "content": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.png" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.png" },
      "role": "last_frame"
    }
  ],
  "seconds": "5",
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": false
}

role 决定素材用途，不要仅依赖数组中第一张、第二张的顺序来表达首尾图。本平台此接口没有独立的顶层 first_frame_url、last_frame_url、first_frame_image 或 last_frame_image 参数，请使用上述 content 写法。

3.4 参考图生成视频

参考图使用 role: "reference_image"，用于表达参考素材，不等同于指定首帧。多张参考图可分别添加为数组项。

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "参考图片中的人物形象，生成她在花园中行走的视频，保持服装和面部特征一致。",
  "content": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference.png" },
      "role": "reference_image"
    }
  ],
  "seconds": "5",
  "resolution": "720p",
  "ratio": "16:9"
}

3.5 参考视频与参考音频

平台支持在 content 中传递 video_url 和 audio_url。使用前请确认所选模型支持对应素材类型及组合。

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "参考视频中的运镜节奏和音频氛围，生成一个夕阳下的海边场景。",
  "content": [
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/reference.mp4" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "https://example.com/reference.mp3" },
      "role": "reference_audio"
    }
  ],
  "seconds": "5",
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true
}

以上展示平台接受的素材结构，不表示每个模型均支持任意素材混用。素材数量、尺寸、文件大小、时长和允许的组合以具体模型能力为准。

4. 请求参数说明

4.1 常用参数

参数	JSON 类型	必填	说明
`model`	string	是	当前令牌可用的完整模型名称或平台模型别名
`prompt`	string	条件必填	非空视频描述；不传时，`content` 中必须包含非空的 `text` 项
`content`	array	否	文本、首图、尾图或参考素材；结构见下表
`seconds`	string	否，建议显式传入	生成时长，单位秒，例如 `"5"`；注意这里是字符串
`duration`	integer	否	时长的另一种写法，例如 `5`；与 `seconds` 二选一，推荐统一使用 `seconds`
`resolution`	string	否，建议显式传入	平台计价可识别 `480p`、`720p`、`1080p`、`4k`；所选模型是否支持该档位需另行确认，示例使用 `720p`
`ratio`	string	否	画面比例，例如 `16:9`、`9:16`、`1:1`；支持范围以模型为准
`generate_audio`	boolean	否	是否生成音频，例如 `true` / `false`；不是单独指定配音文本的字段
`seed`	integer	否	随机种子；可以传 `0`，相同种子不代表必然生成完全相同的结果
`camera_fixed`	boolean	否	是否请求固定镜头，需模型支持
`watermark`	boolean	否	是否请求添加水印，需模型支持

建议显式指定时长、分辨率和音频选项，避免依赖不同模型的默认值。平台没有把所有模型的生成时长固定限制为 5 秒，也不保证所有模型默认参数相同。

4.2 `content` 数组结构

用途	`type`	内容字段	`role`
视频描述	`text`	`text`，字符串	不传
首图 / 首帧	`image_url`	`image_url: {"url":"图片地址"}`	`first_frame`
尾图 / 尾帧	`image_url`	`image_url: {"url":"图片地址"}`	`last_frame`
参考图片	`image_url`	`image_url: {"url":"图片地址"}`	`reference_image`
参考视频	`video_url`	`video_url: {"url":"视频地址"}`	`reference_video`
参考音频	`audio_url`	`audio_url: {"url":"音频地址"}`	`reference_audio`

素材地址建议使用可直接读取的 HTTPS 文件地址，不能是本机路径、网页详情页或需要浏览器登录才能访问的链接；带签名的地址应在任务处理期间保持有效。

也可以把提示词放入 content，例如：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "人物轻轻转身，镜头平稳移动。" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.png" },
      "role": "first_frame"
    }
  ],
  "seconds": "5",
  "resolution": "720p",
  "generate_audio": false
}

平台要求有文字描述，不能只传图片而不传 prompt 或非空文本项。若同时传 prompt 和 content 文本项，以 prompt 为准，素材项仍保留。

兼容的 image / images 简写不会自动标记首帧或尾帧；需要区分素材用途时统一使用 content，不要混用两套图片写法。

5. 创建任务响应

创建成功返回 HTTP 200，表示任务已提交，不代表视频已经生成。示例：

{
  "id": "task_example",
  "task_id": "task_example",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "progress": 0,
  "created_at": 1793000000
}

保存返回的公开任务 ID。当前响应的 id 和 task_id 表示同一个任务，可使用 task_id，也可兼容读取 id。不要把任务查询结果中的数据库数字 data.id 当作任务 ID。

6. 查询任务状态

将 task_example 替换为创建响应中的任务 ID，使用任务所属账号的有效 API Key 查询。只访问 GET /v1/video/generations 不会查询到单个任务，路径中必须带任务 ID。

查询成功的响应包含 code、message、data。下面只列出业务接入需要的字段，实际响应可能包含其他任务信息。

生成中：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_example",
    "status": "IN_PROGRESS",
    "progress": "30%",
    "fail_reason": ""
  }
}

生成完成：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_example",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://example.com/generated-video.mp4"
  }
}

生成失败：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_example",
    "status": "FAILURE",
    "progress": "100%",
    "fail_reason": "任务失败原因"
  }
}

code: "success" 仅表示查询请求成功，必须继续检查 data.status 判断视频是否生成成功。

查询状态 `data.status`	含义	处理建议
`NOT_START`	等待开始	继续轮询
`SUBMITTED`	已提交	继续轮询
`QUEUED`	排队中	继续轮询
`IN_PROGRESS`	生成中	继续轮询
`SUCCESS`	生成成功	读取 `data.result_url`
`FAILURE`	生成失败	读取 `data.fail_reason`，停止轮询

创建响应的 status 为小写 queued、progress 为数字；本文查询接口返回大写任务状态和带 % 的进度字符串，两者不能按同一种结构解析。进度是任务阶段提示，不是精确的剩余时间。

建议每 10–15 秒查询一次，并设置客户端等待上限。网络异常或限流时适当延长间隔；生成耗时受模型、素材、时长及排队情况影响，不承诺固定在 1–5 分钟内完成。

Seedance 视频生成 API

1. 接入地址与鉴权#

2. 模型字段#

3. 创建视频任务#

3.1 文生视频#

3.2 首图生成视频#

3.3 首尾图生成视频#

3.4 参考图生成视频#

3.5 参考视频与参考音频#

4. 请求参数说明#

4.1 常用参数#

4.2 content 数组结构#

5. 创建任务响应#

6. 查询任务状态#