跳到正文

Seedance:视频生成 API

用 Seedance 2.0 / 2.5 生成视频:参数、返回与注意事项。

项目值
Base URLhttps://api.hop-base.com/v1
提交任务POST /v1/video/generate
查询任务GET /v1/video/tasks/{task_id}
任务列表GET /v1/video/tasks
上传素材(仅 2.0)POST /v1/sd/assets
密钥分组国内「Seedance 国内(Doubao)」,海外「Seedance 海外 · Seedream」

可用型号

型号模型 ID分辨率时长(秒)官方价
2.0 标准版(国内)doubao-seedance-2-0-260128-a480p / 720p / 1080p4–15$4.12起/ 百万 tokens
2.0 Fast(国内)doubao-seedance-2-0-fast-260128-a480p / 720p4–15$2.43起/ 百万 tokens
2.0 Mini(国内)doubao-seedance-2-0-mini-260615-a480p / 720p4–15$0.824起/ 百万 tokens
2.5(国内)doubao-seedance-2-5-260628-a480p / 720p / 1080p4–30$6.18起/ 百万 tokens
2.0 标准版(海外)dreamina-seedance-2-0-hc
dreamina-seedance-2-0-ep
dreamina-seedance-2-0-260128
480p / 720p / 1080p / 4K4–15$2.40起/ 百万 tokens
2.0 Fast(海外)dreamina-seedance-2-0-fast-hc
dreamina-seedance-2-0-fast-ep
dreamina-seedance-2-0-fast-260128
480p / 720p4–15$3.30起/ 百万 tokens
2.0 Mini(海外)dreamina-seedance-2-0-mini-hc
dreamina-seedance-2-0-mini-ep
dreamina-seedance-2-0-mini-260615
480p / 720p4–15$2.10起/ 百万 tokens
2.5(海外)dreamina-seedance-2-5-260628480p / 720p / 1080p4–30$6.40起/ 百万 tokens

海外 2.5 的 1080p 须当前分组支持,不支持 4K。

国内型号由Seedance 国内(Doubao)分组提供,海外型号由Seedance 海外 · Seedream分组提供。国内分组已覆盖标准、Fast、Mini 与 Seedance 2.5,只有 4K 需要海外分组的标准版。海外分组的密钥不能调用 doubao-* ID。

每个型号的分档价与完整规格见模型卡,例如 dreamina-seedance-2-5-260628、doubao-seedance-2-0-260128-a。

请求参数

以下都是 JSON 顶层字段,不要嵌套进 parameters。整数和布尔值写成字符串(如 "5"、"true")或把整数写成小数会被拒。整个请求体上限 64 MB,内嵌 Data URL 也计入。

参数必填类型与限制默认值说明
model必填上方型号表中的 ID—决定时长、分辨率与素材限制
content必填非空数组,写法见下—提示词写在 text 元素里
duration可选整数;2.0:4–15 或 -1;2.5:4–30 或 -12.0:5;2.5:-1时长(秒);-1 由模型自动决定
resolution可选各型号可用档见型号表720p须为该型号支持的值
ratio可选16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptiveadaptiveadaptive 按参考图或由模型自动选择
generate_audio可选布尔值2.5:true;2.0:不代填2.0 请显式传
watermark可选布尔值2.5:false;2.0:不代填2.0 请显式传
return_last_frame可选布尔值2.5:true取得末帧时返回 task.last_frame_url;2.0 不保证
priority可选整数 0–9—任务排队的调度提示,不保证完成时间
execution_expires_after可选整数 3600–259200(秒)—不改变 24 小时兜底
callback_url可选HTTP(S) URL—不能替代轮询
safety_identifier可选1–64 个 ASCII 字符—标识你的终端用户的稳定 ID,用于滥用监测;不要放个人信息

frames、seed、camera_fixed、draft、draft_task、service_tier 在两代模型中都会被拒绝(400)。完整字段也可在 API 参考:提交视频任务中查看。

照搬 OpenAI 等接口时的常见误用:

size、seconds、n、aspect_ratio 不是 Seedance 参数,不报错但会被忽略,任务按默认时长与 720p 生成。请改用 duration、resolution、ratio。

content 元素

content 的元素为 text / image_url / video_url / audio_url:

"content": [
  { "type": "text", "text": "橘猫在草地上奔跑,镜头跟随" },
  { "type": "image_url", "image_url": { "url": "https://example.com/cat.png" }, "role": "reference_image" },
  { "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" } },  // role 省略时为 reference_video
  { "type": "audio_url", "audio_url": { "url": "https://example.com/ref.mp3" } }   // role 省略时为 reference_audio
]

图片的 role 为 first_frame、last_frame 或 reference_image:

  • 只有一张图且不写 role 时按首帧处理。
  • 多张图必须写 role。
  • 带视频或音频参考时,图片必须是 reference_image。
  • 首尾帧最多 2 张:1 张须为 first_frame,2 张须各一张 first_frame / last_frame,不能与参考素材混用。
  • Seedance 2.0 的音频参考须搭配图片或视频,2.5 支持仅音频。

图片与音频可用 base64 Data URL,视频不接受 Data URL;Seedance 2.0 还可用已就绪的 asset://素材ID。

参考素材规格

这套规则适用于 Seedance 2.0 与 2.5 的国内、海外模型,不是所有视频模型的通用规范。

提交时会下载并检查每个参考素材,不符合即同步返回 400(没有 code,按 message 识别),不产生任务费用。通过检查的素材仍可能在执行阶段因内容审核失败。

项目图片视频音频
数量上限2.0:9 张;2.5:30 张2.0:3 段;2.5:10 段2.0:3 段;2.5:10 段
格式jpg / jpeg / png / webp / bmp / tif / tiff / gif / heic / heifmp4 / mov(容器需为 MP4/ISO-BMFF)wav / mp3
大小< 30 MiB≤ 200 MiB≤ 15 MiB
尺寸宽高各 300-6000 px宽高各 300-6000 px,总像素 409,600-8,295,044-
宽高比0.4-2.50.4-2.5-
时长-2.0:2-15 秒;2.5:2-30 秒2.0:2-15 秒;2.5:2-30 秒
帧率-24-60 FPS-

首尾帧模式最多 2 张图。视频和音频的多段总时长与单段时长同上限,且分别累计,不是两者相加:例如 2.0 的所有参考视频合计 ≤ 15 秒,所有参考音频合计也 ≤ 15 秒,且每一段都须 ≥ 2 秒。

生成视频的 duration 与参考素材时长是两项独立限制。1 MiB = 1,048,576 字节。

素材 URL 必须是公网可访问的 http(s) 地址:

  • 不允许内网 / 回环 / 链路本地地址与带认证信息的 URL。
  • 重定向最多 3 次。
  • 每个素材须在 2 分钟内下载并解析完。
  • Data URL 须为 data:<MIME>;base64,…。

素材库(仅 Seedance 2.0)

素材库接收一个已有的公网素材 URL,返回素材 ID,在 Seedance 2.0 生成时以 asset://素材ID 引用。普通参考素材也可直接用 URL,无需一律先入库。

上传。保存返回的 data.Id;受理不等于就绪。

curl https://api.hop-base.com/v1/sd/assets \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "URL": "https://example.com/your-image.jpg",
    "Name": "avatar_front",
    "AssetType": "Image"
  }'
{
  "data": {
    "Id": "assetEXAMPLE"
  }
}

等待就绪。用同一分组密钥约每 5 秒查询一次,设置超时。data.Status 为 Active 表示就绪(兼容 completed / succeeded,大小写不敏感)。

curl https://api.hop-base.com/v1/sd/assets/assetEXAMPLE \
  -H "Authorization: Bearer sk-your-key"
{
  "data": {
    "Id": "assetEXAMPLE",
    "Status": "Active",
    "AssetType": "Image"
  }
}

处理中继续等待。上传或审核失败时处理错误,不要继续提交生成或无限轮询。

引用。用完整的 data.Id 拼成 asset://素材ID 放入生成请求的 content,不要改用查询响应里的 URL。

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "The subject waves gently at the camera"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://assetEXAMPLE"
      },
      "role": "reference_image"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}'

上传请求的字段:

字段必填类型与限制默认值说明
URL(或 url)必填公网 HTTP(S) 地址;不接受 base64 或 multipart—本地文件需先自行托管
AssetType(或 asset_type)必填Image / Video / Audio,不区分大小写—素材类型,按「参考素材规格」校验
Name可选字符串—便于你识别的名称,不参与生成
Duration(或 duration / duration_seconds)可选整数秒—不替代实际时长检测

上传时会下载并按「参考素材规格」的 2.0 口径检测,视频、音频须为 2–15 秒。上传接口的 400 带 error.code(如 invalid_asset_duration)。

按素材类型改写 content 元素:

  • 视频:type: video_url、video_url.url: asset://…、role: reference_video。
  • 音频:对应 audio_url / reference_audio。
  • 首帧图片改用 role: first_frame,尾帧为 last_frame;不能把首尾帧与多模态参考模式混用。

不要改写素材 ID,也不要跨分组或跨用户复用。生成仍会检查状态、类型、数量与规格,入库既不豁免 2.0 的数量限制,也不豁免内容审核。

返回结果

提交与单任务查询都使用 task 包装,不要读成顶层 id / outputs。

提交响应

提交成功返回 200,task.id 形如 vt…,用于后续查询。提交响应只含 id、model、status(pending 或 processing)、outputs(恒为空)、error、created_at、completed_at,结果请通过查询获取。

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "dreamina-seedance-2-5-260628",
    "status": "pending",
    "outputs": [],
    "error": null,
    "created_at": "2026-09-23T08:00:00Z",
    "completed_at": null
  }
}

任务查询字段

字段说明
task.idHopBase 任务 ID,vt…
task.statuspending / processing / completed / failed 之一
task.outputs成片地址,字符串数组,不是 {url} 对象
task.duration_seconds成片秒数;自动时长任务请在完成后读取
task.last_frame_url可选,取得末帧时才有;每次查询都会重新签名
task.usage.completion_tokens本次计费 tokens;是 tokens,不是金额
task.error.message失败原因,英文,没有 code 字段
task.completed_at未完成时为 null
usage.cost / usage.cost_cny / usage.cost_usd任务结束后的实际扣费,见视频总览

task.status 只会返回这四个值之一,只在 completed 时读取 task.outputs:结果链接就绪后才报 completed,此时 outputs 不会为空。pending / processing 继续轮询,推荐每 5 秒一次。

480p / 720p 通常 2-5 分钟出片,1080p 与 4K 更久。成片地址支持浏览器直接播放与 Range 拖动,完成后 30 天有效。

进行中

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "dreamina-seedance-2-5-260628",
    "status": "processing",
    "outputs": [],
    "error": null,
    "created_at": "2026-09-23T08:00:00Z",
    "completed_at": null
  }
}

成功

下例为查询到已完成任务(HTTP 200)的结构节选,ID、URL 和用量均为示意值:

{
  "task": {
    "id": "vtEXAMPLE",                       // HopBase 任务 ID
    "model": "dreamina-seedance-2-5-260628",
    "status": "completed",
    "duration_seconds": 5,                   // 自动时长任务请在完成后读取
    "outputs": ["https://api.hop-base.com/example-signed-video.mp4"],  // 字符串数组,不是 {url} 对象
    "last_frame_url": "https://api.hop-base.com/example-signed-last-frame.jpg",  // 可选,取得末帧时才有
    "usage": { "completion_tokens": 1000, "total_tokens": 1000 },  // 可选;是 tokens,不是金额
    "error": null,
    "created_at": "2026-09-23T08:00:00Z",
    "completed_at": "2026-09-23T08:03:10Z"   // 未完成时为 null
  },
  "usage": { "cost": 3.4, "currency": "CNY", "cost_cny": 3.4, "cost_usd": 0.5 }
}

失败

生成失败时查询仍返回 HTTP 200,status 为 failed,原因在 task.error.message。失败不计费。

{
  "task": {
    "id": "vtEXAMPLE",
    "status": "failed",
    "outputs": [],
    "error": { "message": "<English failure reason>" }
  }
}

message 是英文,没有 code 字段。其中的链接会被替换为 [URL_REDACTED],请求 ID 与内部错误码会被去掉;生成端未给出原因时是一条通用的英文兜底说明。

任务列表

GET /v1/video/tasks 可追加 ?page=1&limit=20,返回 {"tasks": [...], "total": 1, "totalPages": 1},每个元素直接是任务对象。limit 默认 20、最大 100,只列出通过 API 提交的任务。

最小示例

# 1. 提交
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      { "type": "text", "text": "一只橘猫在阳光下的草地上奔跑,镜头跟随" }
    ],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false,
    "watermark": false
  }'

# 2. 用返回的 task.id 轮询,推荐每 5 秒一次
curl https://api.hop-base.com/v1/video/tasks/vt你的任务ID \
  -H "Authorization: Bearer sk-你的密钥"

注意事项

Seedance 2.5 的任务模式

Seedance 2.5 没有显式的"任务模式"参数。带 reference_video 提交时,Seedance 会按提示词内容把请求判成普通生成、视频扩展或视频编辑。写成"延续 / 接着 / 扩展这段视频"这类提示词会被判成视频扩展。

模式必须传
视频编辑duration: -1 且 ratio: "adaptive"
视频扩展、首帧/首尾帧ratio: "adaptive"
这些约束提交时不校验:

提交仍返回 200,直到轮询时才变成 failed,不产生费用。带参考视频且提示词可能被理解为"延续原片"时,建议统一传 ratio: "adaptive"。

报错原文形如 identified your task as video extension based on your prompt。Seedance 2.0 没有扩展 / 编辑模式,不受此影响。

真人参考图

真人参考图:

直接传入(URL 或 Data URL)的含真人图片可能在提交时被拒:同步返回 4xx,error.code 为 input_sensitive,message 说明改法。Seedance 2.0 请改走素材库;2.5 不支持素材库,暂不能使用真人参考图。

Seedance 2.0:把同一张图按上方「素材库」上传,就绪后以 asset://素材ID 引用再提交。需要真人参考图时改用 2.0 并走素材库。入库不豁免其他内容审核。

超时、取消与结果链接

  • 任务创建超过 24 小时仍未结束会被自动判为失败,不计费。
  • 视频任务不支持取消;提交成功后不要重复提交,每次重提都是另一个计费任务。
  • 成片地址是 api.hop-base.com 下的签名地址,完成后 30 天有效,再次查询不会续期,过期访问返回 410。

从海外分组切到国内分组

国内分组同时接受上表海外 dreamina-* ID 作为兼容别名(4K 仍会被拒绝)。存量客户从海外切到国内只需更换密钥,base_url、API 路径、请求参数与轮询逻辑都不变。

换 key 后请用新密钥调 GET /v1/models 选择完整模型 ID。已提交的历史任务仍可用原任务 ID 查询。

常见报错 → 改法

照搬其他接口时的三处写法会直接被拒:

写法改法
只传顶层 prompt提示词放在 content[].text
image_url 写成字符串写成对象 {"url": …}
type 写成 image / input_image用 image_url / video_url / audio_url

提交时的参数报错

以下错误在提交时同步返回 400,不创建任务、不计费。响应体为 {"error":{"message":"…","type":"invalid_request_error"}},没有 code 字段,请按 message 识别(数字与序号随请求变化):

# 类型与取值
duration must be an integer                    # priority / execution_expires_after 同理
watermark must be a boolean                    # generate_audio / return_last_frame 同理
Seedance 2.0 duration must be an integer in 4-15 or -1, got 20
Seedance 2.5 duration must be an integer in 4-30 or -1, got 40
model dreamina-seedance-2-0-hc does not support parameter seed   # 被拒字段;报错里是你请求的模型 ID
model dreamina-seedance-2-0-hc does not support ratio 2:1
model dreamina-seedance-2-0-fast-hc does not support resolution 1080p
request body must not exceed 64MB
priority must be within 0-9, got 10
execution_expires_after must be within 3600-259200 seconds
callback_url must be a valid http(s) URL
safety_identifier must be an ASCII string of 1-64 characters

# content 结构
missing content                                # 只传了顶层 prompt
content[0].image_url must be an object         # image_url 写成了字符串
content[0].type does not support image         # type 写成 image / input_image
content[0].text must not be empty
multi-image scenarios must specify first_frame/last_frame or reference_image roles
images in a multimodal reference scenario must set role=reference_image
first/last frame image-to-video cannot be mixed with the multimodal reference scenario
Seedance 2.0 supports at most 9 reference images

# 模型与分组
domestic doubao-seedance-2-0-fast-260128-a only supports 480p, 720p, got 1080p
model seedream-5-0-pro is an image generation model, use POST /v1/images/generations instead

两类情况不是上面的 400:

报错改法
404 The current group does not support the requested model: <模型 ID>模型 ID 不在当前密钥的分组里(如海外密钥调 doubao-*),换用提供该模型的分组的密钥
以 only supports 480p or 720p, got 1080p 结尾海外 2.5 请求 1080p 而当前分组不支持,不会自动降档;改用 720p 或换支持 1080p 的分组

404 会先于上述校验返回,可用 ID 以 GET /v1/models 为准。

参考素材报错

content[1] 为出错素材在 content 中的序号:

content[1] media URL returned HTTP 403        # 素材地址拒绝下载(防盗链、签名过期等)
content[1] unable to fetch media file, make sure the URL is publicly accessible
content[1] media URL hostname could not be resolved
content[1] media URL must point to a public address, not a private or reserved one
content[1] too many redirects for media URL
content[1] unable to parse media metadata of the video asset   # 文件损坏或格式不符
content[1] media data URL must be base64-encoded
content[1] image data URL does not support MIME type image/svg+xml
    # 允许:image/jpeg png webp bmp tiff gif heic heif;audio/wav audio/mpeg
content[1] reference image width and height must be within 300-6000 px, got 200x200
content[1] video asset duration must be within 2-15 seconds, got 16.000 seconds
total reference video duration must not exceed 15 seconds, got 18.000 seconds

参考素材 2 分钟内未能下载并解析完时,提交返回 503,code 为 upstream_timeout:

media validation timed out, please retry later

这是服务端的临时状况,不是素材本身的问题,稍后原样重试即可。

引用素材库素材出错时同样是同步 400、没有 code:

content[1] reference asset is not ready yet, current status is Processing  # 继续查询素材,Active 后再提交
content[1] requires a image asset, got Video       # AssetType 与 image_url / video_url / audio_url 不对应
content[1] references a retired Seedance 2.5 EP asset; ...  # asset25-* 已退役,改传原始公网 URL
... cannot be mixed in one task                    # 只引用同一批上传的素材,或改为直接传公网 URL

任务失败原因

OutputVideoSensitiveContentDetected / OutputAudioSensitiveContentDetected  # 成片未通过审核;带 PolicyViolation 为版权
rejected by content moderation                                             # 成片、提示词或参考素材未通过内容审核
InputImageSensitiveContentDetected 等 Input…Sensitive…                      # 输入素材未通过审核,含真人隐私
InvalidParameter / is not valid / missing required / identified your task as  # 参数或任务模式不合法
task no longer exists                                                        # 任务不存在或已被清理
task expired / timed out / did not finish within 24 hours                     # 任务超时或已过期

审核类与参数类(前四类)原样重试仍会失败,须先改提示词、素材或参数;后两类可直接重新提交。

计费

Seedance 按视频 token 计费,task.usage.completion_tokens 为本次计费 tokens。失败任务与提交时的 400 不计费。

提交时按预估费用预留余额,任务结束后释放。duration: -1 时,2.5 按 30 秒、2.0 按 15 秒预留;余额紧张时传具体秒数可降低预留。余额规则与 usage.cost 字段见视频总览,各型号官方价见上方型号表与模型卡,实际扣费见控制台「使用记录」。

下一步