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 秒。
duration4–30 秒的整数,或 -1 自动确定输出时长。普通生成默认 5 秒。
resolution480p 或 720p,默认 720p。
aspect_ratioadaptive(默认)、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提供。

计费

分辨率不含视频输入(积分/秒)含视频输入(积分/秒)
480p17.3711.58
720p39.0526.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 状态码错误码类型说明
400invalid_requestinvalid_request_error缺少必填参数或参数无效
401invalid_api_keyauthentication_errorAPI Key 无效、已禁用或已删除
402insufficient_creditsbilling_error积分余额不足,请充值
403ip_not_allowedpermission_error请求 IP 不在 Key 的白名单中
404model_not_foundinvalid_request_error模型不存在或已停用
404task_not_foundinvalid_request_error任务 ID 不存在
429rate_limit_exceededrate_limit_error请求过于频繁,请降低频率
429spend_limit_exceededbilling_error达到 Key 的消费限额(每小时/每天/总量)
500internal_errorapi_error服务器内部错误
503upstream_errorupstream_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 服务返回错误,可能原因:

  • 输入内容包含敏感或违规信息
  • 上游服务暂时不可用
  • 请求参数不被上游支持

因上游错误导致任务失败时,预扣积分会自动退还。