Seedance:视频生成 API
用 Seedance 2.0 / 2.5 生成视频:参数、返回与注意事项。
| 项目 | 值 |
|---|---|
| Base URL | https://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-a | 480p / 720p / 1080p | 4–15 | $4.12起/ 百万 tokens |
| 2.0 Fast(国内) | doubao-seedance-2-0-fast-260128-a | 480p / 720p | 4–15 | $2.43起/ 百万 tokens |
| 2.0 Mini(国内) | doubao-seedance-2-0-mini-260615-a | 480p / 720p | 4–15 | $0.824起/ 百万 tokens |
| 2.5(国内) | doubao-seedance-2-5-260628-a | 480p / 720p / 1080p | 4–30 | $6.18起/ 百万 tokens |
| 2.0 标准版(海外) | dreamina-seedance-2-0-hcdreamina-seedance-2-0-epdreamina-seedance-2-0-260128 | 480p / 720p / 1080p / 4K | 4–15 | $2.40起/ 百万 tokens |
| 2.0 Fast(海外) | dreamina-seedance-2-0-fast-hcdreamina-seedance-2-0-fast-epdreamina-seedance-2-0-fast-260128 | 480p / 720p | 4–15 | $3.30起/ 百万 tokens |
| 2.0 Mini(海外) | dreamina-seedance-2-0-mini-hcdreamina-seedance-2-0-mini-epdreamina-seedance-2-0-mini-260615 | 480p / 720p | 4–15 | $2.10起/ 百万 tokens |
| 2.5(海外) | dreamina-seedance-2-5-260628 | 480p / 720p / 1080p | 4–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 或 -1 | 2.0:5;2.5:-1 | 时长(秒);-1 由模型自动决定 |
resolution | 可选 | 各型号可用档见型号表 | 720p | 须为该型号支持的值 |
ratio | 可选 | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive | adaptive | adaptive 按参考图或由模型自动选择 |
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 参考:提交视频任务中查看。
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 / heif | mp4 / 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.5 | 0.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.id | HopBase 任务 ID,vt… |
task.status | pending / 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 字段见视频总览,各型号官方价见上方型号表与模型卡,实际扣费见控制台「使用记录」。
下一步
- 视频总览:各视频系列对比与共用的任务流程
- API 参考:提交视频任务:请求字段
- API 参考:查询视频任务:返回字段
- 错误码与重试:各错误码的含义以及是否该重试