Seedance 2.5 Flash
使用模型 doubao-seedance-2.5-flash,通过文字、多模态参考或首尾帧生成 480p、720p 视频。在 Playground 中试用。
创建视频
curl https://api.aivideoapi.ai/v1/videos/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2.5-flash",
"input": {
"prompt": "一个快乐的小马奔跑在草原上",
"generate_audio": true,
"aspect_ratio": "16:9",
"duration": 5,
"resolution": "480p",
"watermark": false,
"return_last_frame": true
},
"callback_url": "https://example.com/webhooks/video"
}'
请求受理后会返回任务 ID。保存 data.taskId,后续用它查询任务或匹配回调通知。
{
"code": 200,
"msg": "success",
"data": { "taskId": "7d89c51e-9430-410e-909e-df347131ebaa" }
}
输入参数
| 字段 | 支持范围 |
|---|---|
prompt | 文字描述。提供提示词或至少一个参考素材即可,支持纯音频输入。 |
generation_type | 默认 omni_reference。选择 first_and_last_frames 时,传一张首帧图或按顺序传入首尾两张图,使用 adaptive 宽高比,不可同时传视频或音频。 |
image_urls、video_urls、audio_urls | 最多 10 张图、5 个视频、5 段音频。参考视频合计最多 30 秒,音频合计最多 30 秒。支持可访问的媒体链接或当前账户的平台素材引用。 |
omni_reference_task_type | 全模态参考模式可选 auto、reference、edit 或 extend。编辑与延长需要参考视频,宽高比为 adaptive。编辑须使用 duration: -1,被编辑视频时长为 4–30 秒。 |
duration | 4–30 秒的整数,或 -1 自动确定输出时长。普通生成默认 5 秒。 |
resolution | 480p 或 720p,默认 720p。 |
aspect_ratio | adaptive(默认)、16:9、4:3、1:1、3:4、9:16 或 21:9。 |
generate_audio、watermark | 默认生成同步音频(true),不加水印(false)。 |
seed | 可选的 JSON 整数,范围为 -1 至 2147483647(含两端)。-1 表示随机,指定 0 等固定值可复用同一种子。省略字段时由模型决定。字符串、小数及 null 均无效。种子不影响计费。 |
output_format | 可输出 mp4(默认)或 mov。 |
return_last_frame | 布尔值,默认 false。将 input.return_last_frame 设为 true,可请求生成视频最后一帧的图片。 |
web_search | 布尔值,默认 false。 |
priority、execution_expires_after | 优先级为 0–9(默认 0);任务过期时间为 3600–259200 秒(默认 172800)。 |
safety_identifier | 可选。当前终端用户的固定标识,1–64 个可打印 ASCII 字符。 |
Draft 样片及基于样片生成正式视频仅在标准版 Seedance 2.5提供。
计费
| 分辨率 | 不含视频输入(积分/秒) | 含视频输入(积分/秒) |
|---|---|---|
| 480p | 17.37 | 11.58 |
| 720p | 39.05 | 26.03 |
不含参考视频,按输出秒数乘以对应单价计费。含参考视频,先将平台探测到的所有输入视频秒数与输出秒数相加,再乘以含视频单价。图片、参考音频及是否生成音频均不改变费率。积分四舍五入到两位小数。
按标准价格,上方 480p 示例为 86.85 积分,加入 5 秒参考视频后为 115.80 积分。720p 输出 5 秒时,无参考视频收费 195.25 积分,输入 5 秒参考视频收费 260.30 积分,输入 10.7 秒参考视频收费 408.67 积分。
提交前可将相同的 model 和 input 发送到 POST /v1/estimate,获取适用于当前账户的报价。duration=-1 时按最多 30 秒输出预扣;含视频还会计入输入视频时长。成功后按实际输出时长结算,多余预扣退回;无法取得实际时长时保留预扣金额。平台确认任务失败或过期后会全额退还预扣积分。如果暂时无法确认是否接单,平台会保留预扣并核对任务状态。
查询任务
用创建该任务的账户下的 API Key 调用 GET /v1/tasks/{taskId}。查询成功时 HTTP 状态码为 200,响应顶层的 id 等于创建时返回的 data.taskId。请按 status 判断视频是否生成成功。下例的时间戳均为 Unix 秒。
curl https://api.aivideoapi.ai/v1/tasks/7d89c51e-9430-410e-909e-df347131ebaa \
-H "Authorization: Bearer $API_KEY"
处理中(HTTP 200)
等待执行时,status 为 pending,附带 estimated_seconds: 300;开始处理后返回如下报文。progress: null 表示暂无进度百分比。示例中的已消耗积分为 0,此时仍可能有预扣。可以继续查询或等待回调。
{
"id": "7d89c51e-9430-410e-909e-df347131ebaa",
"status": "processing",
"model": "doubao-seedance-2.5-flash",
"credits_consumed": 0,
"created_at": 1794819600,
"progress": null
}
生成成功(HTTP 200)
从 output.urls[0] 读取视频地址。请求了尾帧且生成结果包含尾帧图片时,从 output.last_frame_url 读取图片地址。尾帧是与视频宽高相同的无水印 JPEG,可作为下一段视频的首帧。如果没有这个字段,仍可使用已生成的视频。
视频和尾帧图片均使用上游返回的原始链接。链接可能过期,平台不保证固定的有效期,需要保留的文件请及时下载。
credits_consumed 为实际消耗的积分,下面的 480p、5 秒示例为 86.85 积分。结果还可包含 output.metadata 中的视频参数,以及顶层的 usage(如 completion_tokens、total_tokens)。
{
"id": "7d89c51e-9430-410e-909e-df347131ebaa",
"status": "completed",
"model": "doubao-seedance-2.5-flash",
"credits_consumed": 86.85,
"created_at": 1794819600,
"completed_at": 1794819660,
"output": {
"urls": ["https://media.example.com/outputs/pony.mp4"],
"last_frame_url": "https://media.example.com/outputs/pony-last-frame.jpg",
"metadata": {
"duration": 5,
"ratio": "16:9",
"resolution": "480p",
"generate_audio": true,
"output_format": "mp4"
}
}
}
历史任务的结果已归档或清理时,查询仍可能返回 completed,但 output 为 null。结果已清理时还会返回 payload_cleared_at。
生成失败(HTTP 200)
查询已找到任务,生成结果为 failed。读取 error.code 和 error.message 获取原因。以下示例已退还预扣积分。
{
"id": "57c8772c-f834-46f3-9b7d-81f92e104050",
"status": "failed",
"model": "doubao-seedance-2.5-flash",
"credits_consumed": 0,
"created_at": 1794819600,
"error": { "code": "upstream_error", "message": "Video generation failed" }
}
查询请求出错(HTTP 404)
任务 ID 不存在或不属于当前账户时,接口返回 HTTP 404,响应只有顶层 error。
{
"error": {
"code": "task_not_found",
"message": "Task not found.",
"type": "invalid_request_error"
}
}
API Key 缺失、无效或已停用时,返回 HTTP 401(invalid_api_key)。请求 IP 不在该 Key 的白名单内时,返回 HTTP 403(ip_not_allowed)。遇到 HTTP 503(service_unavailable),可稍后用原任务 ID 再次查询。
回调通知
在创建请求顶层填写可从公网访问的 callback_url,例如 https://example.com/webhooks/video。任务完成或失败后,平台向该地址发送 JSON 格式的 POST。下面是接收端收到的两个请求示例。
成功回调
与查询结果相同,回调正文中的 output.urls[0] 是视频地址。请求的尾帧图片可用时,output.last_frame_url 是其图片地址。
POST /webhooks/video HTTP/1.1
Host: example.com
Content-Type: application/json
X-Timestamp: 1794819661
X-Task-Id: 7d89c51e-9430-410e-909e-df347131ebaa
X-Event: task.completed
X-Event-ID: 7d89c51e-9430-410e-909e-df347131ebaa:task.completed
{
"id": "7d89c51e-9430-410e-909e-df347131ebaa",
"status": "completed",
"model": "doubao-seedance-2.5-flash",
"credits_consumed": 86.85,
"created_at": 1794819600,
"completed_at": 1794819660,
"output": {
"urls": ["https://media.example.com/outputs/pony.mp4"],
"last_frame_url": "https://media.example.com/outputs/pony-last-frame.jpg",
"metadata": {
"duration": 5,
"ratio": "16:9",
"resolution": "480p",
"generate_audio": true,
"output_format": "mp4"
}
}
}
失败回调
POST /webhooks/video HTTP/1.1
Host: example.com
Content-Type: application/json
X-Timestamp: 1794819630
X-Task-Id: 57c8772c-f834-46f3-9b7d-81f92e104050
X-Event: task.failed
X-Event-ID: 57c8772c-f834-46f3-9b7d-81f92e104050:task.failed
{
"id": "57c8772c-f834-46f3-9b7d-81f92e104050",
"status": "failed",
"model": "doubao-seedance-2.5-flash",
"credits_consumed": 0,
"created_at": 1794819600,
"error": { "code": "upstream_error", "message": "Video generation failed" }
}
如果排队中的任务已成功取消,事件头同样为 task.failed,正文为 status: "cancelled",不含 error。
接收端可按 X-Event-ID 去重。保存事件后,在 10 秒内返回任意 2xx(例如 204 No Content)。超时或返回非 2xx 时,平台会在第一次、第二次投递失败后分别等待约 3 分钟和 10 分钟再试,单任务回调共最多投递 3 次;重试沿用同一事件 ID。X-Timestamp 是本次投递的 Unix 秒数。回调不带签名,需要验证结果时,用本地保存的任务 ID 和自己的 API Key 查询平台。
常见错误码
请求失败时,API 返回 JSON 格式的错误响应:
{
"error": {
"code": "insufficient_credits",
"message": "Your credit balance is too low. Please top up.",
"type": "billing_error"
}
}
错误码一览
| HTTP 状态码 | 错误码 | 类型 | 说明 |
|---|---|---|---|
| 400 | invalid_request | invalid_request_error | 缺少必填参数或参数无效 |
| 401 | invalid_api_key | authentication_error | API Key 无效、已禁用或已删除 |
| 402 | insufficient_credits | billing_error | 积分余额不足,请充值 |
| 403 | ip_not_allowed | permission_error | 请求 IP 不在 Key 的白名单中 |
| 404 | model_not_found | invalid_request_error | 模型不存在或已停用 |
| 404 | task_not_found | invalid_request_error | 任务 ID 不存在 |
| 429 | rate_limit_exceeded | rate_limit_error | 请求过于频繁,请降低频率 |
| 429 | spend_limit_exceeded | billing_error | 达到 Key 的消费限额(每小时/每天/总量) |
| 500 | internal_error | api_error | 服务器内部错误 |
| 503 | upstream_error | upstream_error | 上游 AI 服务返回错误 |
常见场景
invalid_request (400)
缺少必填字段或参数格式错误时返回。
{
"error": {
"code": "invalid_request",
"message": "'model' is required.",
"type": "invalid_request_error"
}
}
insufficient_credits (402)
积分不足。可通过 GET /v1/credits 查询余额,前往 Dashboard > Billing 充值。
invalid_api_key (401)
可能原因:
- Key 不以
sk-开头 - Key 已被禁用或删除
- 用户账户已被封禁
upstream_error (503)
上游 AI 服务返回错误,可能原因:
- 输入内容包含敏感或违规信息
- 上游服务暂时不可用
- 请求参数不被上游支持
因上游错误导致任务失败时,预扣积分会自动退还。