Seedance · 火山方舟格式

创建视频生成任务

提交视频生成任务，立即返回任务 ID，之后用任务 ID 查询结果。请求参数和返回结果与火山方舟「创建视频生成任务」接口一致。

POSThttps://your-domain/ark/api/v3/contents/generations/tasks

请求示例

curl https://your-domain/ark/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

返回结果

{
  "id": "video_8f3k2m9x4q1w7e5r0t6y2u4p"
}

请求参数

请求体是 JSON，不超过 64 MB。不认识的参数会被忽略，值为 null 的参数视同不传。

请求体

modelstring必填

模型 ID，例如 doubao-seedance-2-0-260128，可用的模型见模型与价格。这个接口只能调用 Seedance 系列模型，其他模型请用OpenAI 格式。

contentobject[]必填

输入给模型的文本和素材，1 到 100 项。支持以下组合：

只有文本：文生视频；
文本（可选）+ 首帧图片：图生视频-首帧；
文本（可选）+ 首帧 + 尾帧图片：图生视频-首尾帧；
文本（可选）+ 参考图、参考视频、参考音频的任意组合：多模态参考，以及视频编辑、视频延长。

首帧（首尾帧）和多模态参考不能混用；需要固定首帧时，可以把图片作为参考图，并在提示词里写明「以图片1为首帧」。使用尾帧时必须同时有首帧。各模型参考素材的数量上限见模型与价格。

content 的元素

typestring必填

内容类型：text（文本）、image_url（图片）、video_url（视频）或 audio_url（音频）。

textstring

type 为 text 时必填，描述想要生成的视频。有多个 text 时按顺序换行拼接，合计不超过 10000 字；建议中文不超过 500 字，太长时模型容易忽略细节。

和火山方舟一样，也可以在提示词末尾写 --rs 720p --rt 16:9 --dur 5 来传分辨率、画幅和时长，请求体里的同名参数优先。--seed、--cf、--wm、--frames 会被去掉，不生效。

image_urlobject

type 为 image_url 时必填，写成 {"url": "..."}。url 可以是：

图片的公网链接（http 或 https），不超过 4096 个字符；
Base64 编码，格式为 data:image/<图片格式>;base64,<Base64 编码>，图片格式小写，例如 data:image/png;base64,...，单张不超过 10 MB。

支持 jpeg、png、webp、bmp、tiff、gif、heic、heif；单张小于 30 MB，宽高比（宽 / 高）在 0.4 到 2.5 之间，宽和高都在 300 到 6000 像素之间。不支持素材库的 asset://。

video_urlobject

type 为 video_url 时必填，写成 {"url": "..."}。url 是视频的公网链接（http 或 https），平台会读取视频时长用于计费，所以链接必须能公开下载；不支持 Base64 和 asset://。

支持 mp4、mov。每个视频 2 秒以上，个数和总时长不能超过模型的上限（Seedance 2.0 系列 3 个、共 15 秒；Seedance 2.5 10 个、共 30 秒）；Seedance 2.5 视频编辑的原视频至少 4 秒。

audio_urlobject

type 为 audio_url 时必填，写成 {"url": "..."}。url 可以是音频的公网链接，或 data:audio/<音频格式>;base64,<Base64 编码>，例如 data:audio/wav;base64,...。

支持 wav、mp3，单个不超过 15 MB，时长要求与火山方舟相同。Seedance 2.0 系列不能只传音频，需要同时带参考图或参考视频。

rolestring

素材的用途：

图片：first_frame（首帧）、last_frame（尾帧）或 reference_image（参考图）。只有一张图片时可以不填，按首帧处理；有多张图片时每张都要填。
视频：reference_video，可以不填。
音频：reference_audio，可以不填。

resolutionstring默认值 720p

视频分辨率：480p、720p 或 1080p，各模型支持的分辨率见模型与价格。

ratiostring

视频宽高比：16:9、4:3、1:1、3:4、9:16、21:9 或 adaptive（自动适配）。不同生成方式的规则：

文生视频：不传或传 adaptive 时按 16:9 生成。
首帧、首尾帧：不传或传 adaptive 时跟随首帧图片。Seedance 2.0 系列可以指定画幅，图片会被居中裁剪；Seedance 2.5 只能用 adaptive。
多模态参考：不传或传 adaptive 时由模型根据素材决定，也可以指定画幅。
视频编辑、延长：跟随原视频，这个参数不生效。

durationinteger

视频时长，单位秒。Seedance 2.0 系列可选 4 到 15，默认 5；Seedance 2.5 可选 4 到 30，不传时由模型决定。传 -1 由模型在可选范围内决定时长，先按最长时长冻结费用，完成后按实际时长结算，见计费规则。

视频编辑生成的视频和原视频一样长，这个参数不生效。

generate_audioboolean默认值 true

是否生成与画面同步的声音（人声、音效和背景音乐）。false 生成无声视频。

omni_reference_task_typestring默认值 auto

多模态参考的任务类型：

auto、reference：参考生成，根据参考图、视频、音频生成新视频；
edit：视频编辑，修改原视频的画面或声音；
extend：视频延长，向前或向后延长原视频。

edit 和 extend 需要至少一个参考视频，视频编辑的时长按第一个参考视频计算。Seedance 2.0 系列没有这个参数，靠提示词区分编辑和延长；传了不会转给模型，但平台会按对应的任务类型检查参数和计费。

callback_urlstring

回调地址，http 或 https 链接，不超过 1024 个字符。任务状态变化时，平台会向这个地址 POST 任务信息，见回调通知。

safety_identifierstring

终端用户的唯一标识，不超过 64 个字符，建议传用户 ID 哈希后的值。查询任务时原样返回。

service_tierstring默认值 default

服务等级，只支持 default（在线推理）。

draftboolean默认值 false

样片模式，暂不支持，只能不传或传 false。

return_last_frameboolean默认值 false

返回尾帧，暂不支持，只能不传或传 false。

output_formatstring默认值 mp4

输出格式，只支持 mp4。

seed、camera_fixed、watermark、priority、tools、execution_expires_after 可以传，但不生效：视频不带水印，任务最长执行 12 小时。frames 只能不传或传 0，请用 duration 指定时长。

返回参数

idstring

任务 ID，以 video_ 开头。用它查询任务或取消任务。

参数有误、余额不足等情况下，接口直接返回错误，不会创建任务，也不扣费，见错误码。

请求示例

文生视频见右侧的请求示例，下面是其他生成方式的写法。

图生视频-首帧

content 里放一张 role 为 first_frame 的图片。ratio 传 adaptive 时，视频的宽高比跟随图片。

图生视频-首帧

curl https://your-domain/ark/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "女孩抬头看向镜头，微笑着挥手，微风吹起她的头发"},
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/first-frame.png"},
        "role": "first_frame"
      }
    ],
    "ratio": "adaptive",
    "duration": 5
  }'

使用本地图片

本地图片转成 Base64 编码后放在 url 里，单张不超过 10 MB：

Python

import base64
import os

from arkruntime import Ark

client = Ark(
    base_url="https://your-domain/ark/api/v3",
    api_key=os.environ.get("ARK_API_KEY"),
)

# 转成 data URL：data:image/<图片格式>;base64,<Base64 编码>
with open("first-frame.png", "rb") as f:
    image = "data:image/png;base64," + base64.b64encode(f.read()).decode()

task = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {"type": "text", "text": "女孩抬头看向镜头，微笑着挥手，微风吹起她的头发"},
        {"type": "image_url", "image_url": {"url": image}, "role": "first_frame"},
    ],
    ratio="adaptive",
    duration=5,
)
print(task.id)

图生视频-首尾帧

放两张图片，role 分别为 first_frame 和 last_frame。首尾帧的宽高比不一致时，以首帧为准，尾帧会被自动裁剪。

图生视频-首尾帧

curl https://your-domain/ark/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "镜头从街道缓缓升高，天色由白天过渡到黄昏，街灯依次亮起"},
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/first-frame.png"},
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/last-frame.png"},
        "role": "last_frame"
      }
    ],
    "ratio": "adaptive",
    "duration": 5
  }'

多模态参考

参考图、参考视频和参考音频可以任意组合。提示词里用「图片1」「视频1」「音频1」指代素材，序号是同类素材在 content 里的顺序。带参考视频的任务改用「带参考视频」单价，参考视频的时长也计入费用，见计费规则。

多模态参考

curl https://your-domain/ark/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "图片1中的女孩穿着图片2的外套，按视频1的运镜在街头行走，背景音乐用音频1"},
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/girl.png"},
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/coat.png"},
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {"url": "https://example.com/camera-move.mp4"},
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {"url": "https://example.com/bgm.mp3"},
        "role": "reference_audio"
      }
    ],
    "ratio": "16:9",
    "duration": 10
  }'

视频编辑

放入原视频，omni_reference_task_type 传 edit，在提示词里写明要怎么改。生成的视频和原视频一样长，按原视频的时长冻结费用，完成后按实际时长结算。

视频编辑

curl https://your-domain/ark/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {"type": "text", "text": "把视频1中女孩的外套换成红色羽绒服，其他内容保持不变"},
      {
        "type": "video_url",
        "video_url": {"url": "https://example.com/source.mp4"},
        "role": "reference_video"
      }
    ],
    "omni_reference_task_type": "edit",
    "ratio": "adaptive",
    "duration": -1
  }'

视频延长

放入原视频，omni_reference_task_type 传 extend，duration 是延长后生成的视频时长。

视频延长

curl https://your-domain/ark/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {"type": "text", "text": "将视频1向后延长，镜头继续向前推进，天色渐渐暗下来"},
      {
        "type": "video_url",
        "video_url": {"url": "https://example.com/source.mp4"},
        "role": "reference_video"
      }
    ],
    "omni_reference_task_type": "extend",
    "ratio": "adaptive",
    "duration": 8
  }'

回调通知

创建任务时传了 callback_url，任务状态变化时平台会向这个地址发送 POST 请求，请求体是 JSON，内容和查询任务的返回结果相同。

创建带回调的任务

curl https://your-domain/ark/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true,
    "callback_url": "https://example.com/seedance/callback"
  }'

status	什么时候回调
`queued`	任务提交成功，开始排队
`running`	开始生成
`succeeded`	生成成功，content.video_url 是视频地址
`failed`	生成失败，error 是失败原因
`expired`	超过 12 小时没有完成

回调地址要在 5 秒内返回 2xx 状态码，否则算发送失败。succeeded、failed、expired 发送失败时会再发两次，每次间隔 5 秒；queued、running 只发一次。
主动取消的任务不回调。
回调地址要能从公网访问，内网地址收不到回调。
同一状态可能收到不止一次，请按任务 ID 和 status 去重。没有收到回调时，可以用查询接口确认任务状态。

回调的请求体（任务成功时）

{
  "id": "video_8f3k2m9x4q1w7e5r0t6y2u4p",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://your-domain/uploads/videos/2026/10/k3Zq8mVt2LxR9pWa.mp4"
  },
  "usage": {"completion_tokens": 108900, "total_tokens": 108900},
  "created_at": 1791691200,
  "updated_at": 1791691318,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "service_tier": "default",
  "execution_expires_after": 43200,
  "generate_audio": true,
  "draft": false,
  "priority": 0,
  "output_format": "mp4"
}