主题
Seedance 2.5 Flash 视频生成
POST
/v1/video/generations
🤖 本页是给 AI Agent 读的接口文档
人类用户只需按「如何使用」中的方法教会 AI 怎么用。
Seedance 2.5 Flash 是一款支持文生视频、图生视频、多模态参考视频生成和有声视频的异步视频模型,输出时长 4–30 秒、分辨率最高 720p。
- 文生视频(T2V):根据提示词从零生成视频,可开启联网搜索补充实时信息。
- 图生视频(I2V):使用首帧图像控制视频的起始画面,也可同时传入尾帧图像控制结束画面。
- 多模态参考视频(R2V):传入参考图像、参考视频或参考音频,引导生成风格和内容。支持仅传参考音频。
- 有声视频:默认为视频生成音频,可通过
generate_audio关闭。
提交生成请求后,接口立即返回任务 ID。视频生成是异步过程,需要通过查询接口检查任务状态,成功后从返回的结果地址获取视频。
- 这是异步接口。创建请求返回任务 ID 后即结束,不等候视频生成完成。
- 客户端应定期调用查询接口检查任务状态,建议间隔 5–10 秒。
- 成功后从查询响应的
data.result_url获取视频内容地址。
模型
请求体中的 model 固定填写下面的模型 ID。
seedance-2.5-flash价格
| 分辨率 | 单秒售价 |
|---|---|
480p(无参考视频) | ¥0.55 / $0.0809 |
480p(有参考视频) | ¥0.35 / $0.0515 |
720p(无参考视频) | ¥1.25 / $0.1838 |
720p(有参考视频) | ¥0.80 / $0.1176 |
无参考视频时,按输出视频时长(秒)计费;有参考视频时,按参考视频实际总时长与输出时长之和计费。是否生成音频不影响价格。
- 无参考视频:费用 = 输出视频时长(秒) × 对应分辨率的“无参考视频”单秒价格
- 有参考视频:费用 =(所有参考视频总时长+输出视频时长)× 对应分辨率的“有参考视频”单秒价格
认证
使用 ClawPower API Key 进行 Bearer 认证,并在请求头中传入:
Authorization: Bearer <CLAWPOWER_API_KEY>类型 HTTP (bearer)
请求体
application/json
要调用的模型 ID。固定填写 seedance-2.5-flash,不支持品牌别名或其他模型名称。
有效值
"seedance-2.5-flash"视频生成说明。描述场景、主体、动作、镜头和风格。
去除首尾空白后长度须为 3–4000 个字符。图生视频与多模态参考模式下,可结合媒体内容描述预期的运镜和变化。
最小长度
3最大长度
4000输出视频时长,单位为秒,取 4–30 的整数。必填。
最小值
4最大值
30输出分辨率,必填。每档单价见价格表。
有效值
"480p""720p"输出视频宽高比,默认 adaptive。文生视频和多模态参考也可指定其他列出的比例,首帧与首尾帧请求只接受 adaptive。
有效值
"adaptive""21:9""16:9""4:3""1:1""3:4""9:16"默认
"adaptive"是否为视频生成音频。默认 true。
不影响价格:是否生成音频按同一价格计费。
默认
true是否在生成前联网搜索,用搜索结果补充提示词中的实时信息。默认 false。
只能用于文生视频(T2V):请求包含任何媒体字段时不能开启。
默认
false首帧图片的公网 HTTPS URL。使用 adaptive 画幅,不能与参考素材数组同时使用。
尾帧图片的公网 HTTPS URL。须同时传入 first_frame_image,使用 adaptive 画幅,不能与参考素材数组同时使用。
1–10 张参考图的公网 HTTPS URL。每张小于 30 MB,格式为 JPEG、PNG 或 WebP。不能与首尾帧字段同时使用。
最小项数
1最大项数
101–5 段参考视频的公网 HTTPS URL。每段 2–30 秒,累计不超过 30 秒,每段最多 200 MB,格式为 MP4 或 MOV。短边 480–720 像素,宽、高各 300–6000 像素,总像素 409,600–927,408,宽高比 0.4–2.5,平均帧率 24–60 fps。不能与首尾帧字段同时使用。所有参考视频的实际总时长计入费用。
最小项数
1最大项数
51–5 段参考音频的公网 HTTPS URL,可单独传入。每段 2–30 秒,累计不超过 30 秒,每段最多 15 MB,格式为 WAV 或 MP3。不能与首尾帧字段同时使用。
最小项数
1最大项数
5响应
任务创建成功。返回公共任务 ID,用于后续查询。
application/json
JSON "id": "task_0123456789abcdef", "task_id": "task_0123456789abcdef", "object": "video", "model": "seedance-2.5-flash", "status": "queued", "progress": 0, "created_at": 1787414400
{
}
TIP
视频生成是异步任务。创建任务后,请前往 任务管理 > 查询视频任务 查看任务状态与结果。
生成模式
Seedance 2.5 Flash 根据请求中的媒体字段自动确定生成模式,不需要额外指定 mode 参数。
| 模式 | 触发条件 | 允许的媒体字段 |
|---|---|---|
| 文生视频 T2V | 省略所有媒体字段 | 无。可设置 web_search: true |
| 图生视频 I2V | 传入 first_frame_image | 首帧必填,可搭配 last_frame_image 指定尾帧 |
| 多模态参考 R2V | 至少传入一个非空参考数组 | image_urls、video_urls、audio_urls,支持仅传音频参考 |
组合限制:
- 首尾帧字段与参考素材数组互斥。
last_frame_image必须与first_frame_image一起传入。- 请求包含任何媒体字段时,
web_search须保持关闭。
时长与分辨率
| 字段 | 可选值 | 说明 |
|---|---|---|
duration | 4–30 的整数 | 输出视频时长,单位为秒,必填 |
resolution | 480p、720p | 输出分辨率,必填,各档售价见上方价格表 |
宽高比
ratio 可省略,默认 adaptive。首帧及首尾帧生成只接受 adaptive。文生视频和多模态参考生成支持 adaptive、21:9、16:9、4:3、1:1、3:4、9:16。
从 Seedance 2.0 迁移的文生视频和参考生成请求若要保持 16:9,请显式传入 ratio: "16:9"。
音频与联网搜索
| 字段 | 默认值 | 说明 |
|---|---|---|
generate_audio | true | 控制是否生成音频,不影响售价 |
web_search | false | 控制是否联网搜索,仅限纯文生视频 |
媒体限制
| 媒体 | 格式 | 数量 | 单个文件大小 | 时长 |
|---|---|---|---|---|
| 图片 | JPEG、PNG、WebP | 首尾帧各 1 张,或参考图最多 10 张 | 每张小于 30 MB | — |
| 参考视频 | MP4、MOV | 最多 5 段 | 每段不超过 200 MB | 单段 2–30 秒,累计不超过 30 秒 |
| 参考音频 | WAV、MP3 | 最多 5 段 | 每段不超过 15 MB | 单段 2–30 秒,累计不超过 30 秒 |
所有媒体字段只接受公网 HTTPS URL,不接受本地路径、file://、内网地址或 Base64。本地素材请先通过 ClawPower 的图片上传、视频上传或音频上传接口取得 URL。参考数组传入时必须非空。
参考视频支持 480p 或 720p,短边须在 480–720 像素之间,宽和高各须在 300–6000 像素之间。总像素数须在 409,600–927,408 之间,宽高比须在 0.4–2.5 之间,平均帧率须在 24–60 fps 之间。输入规格与请求的输出分辨率分别校验。
有参考视频时,参考视频的实际总时长与输出时长合并计费。
完整调用示例
下面的 Python 示例展示完整的异步任务流程:创建任务、查询状态、下载视频。
python
import time
import requests
API_BASE = "https://api.clawpowerai.com"
API_KEY = "<CLAWPOWER_API_KEY>"
# 1. 创建视频生成任务
create_response = requests.post(
f"{API_BASE}/v1/video/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={
"model": "seedance-2.5-flash",
"prompt": "黄昏海边,一位少年运球奔跑,电影感镜头",
"duration": 5,
"resolution": "720p",
"ratio": "16:9",
"generate_audio": True,
},
timeout=30,
)
create_response.raise_for_status()
task_id = create_response.json()["task_id"]
print(f"任务已创建: {task_id}")
# 2. 查询任务状态,等待生成完成
while True:
query_response = requests.get(
f"{API_BASE}/v1/video/generations/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
query_response.raise_for_status()
data = query_response.json()["data"]
status = data["status"]
print(f"状态: {status}, 进度: {data.get('progress', '—')}")
if status == "SUCCESS":
result_url = data["result_url"]
break
elif status == "FAILURE":
raise RuntimeError(f"视频生成失败: {data.get('fail_reason', '')}")
time.sleep(8)
# 3. 下载视频(内容地址同样需要 Bearer 鉴权)
video_response = requests.get(
result_url,
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=120,
)
video_response.raise_for_status()
with open("output.mp4", "wb") as f:
f.write(video_response.content)
print("视频已保存为 output.mp4")NOTE
这是异步接口。创建请求返回任务 ID 后立即结束,不等候视频生成完成。客户端应定期调用查询接口检查任务状态,建议间隔 5–10 秒。查询请求返回 HTTP 200 只表示成功读取了任务记录,必须检查 data.status 判断任务是否成功完成。详见 任务管理 > 查询视频任务。
