VidBudget
seedance-2.5

Seedance 2.5 · API

Markdown

POST https://vidbudget.com/v1/videos/generations

异步视频生成 · 按秒计费 · 失败不扣费

在线试用 →

快速开始:提交 → 查询 → 下载

这是异步视频接口。提交成功返回 HTTP 202 和任务 ID,视频生成及素材处理在后台完成;不要等待提交请求直接返回视频。

保存任务 ID,每 5–10 秒查询一次。请求中断后继续查询原任务;需要重发提交时使用同一个幂等键和完全相同的参数。

cURL · 提交
curl https://vidbudget.com/v1/videos/generations \
  -H "Authorization: Bearer $VIDBUDGET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "seedance-2.5",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9"
}'

认证与请求头

在控制台创建 API 密钥。密钥仅创建时显示一次,不放入浏览器公开代码、URL 或日志。

HTTP
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_ID

规格与适用范围

参考图片用来描述人物、场景、商品和风格,不是指定首帧或尾帧。请确保拥有输入素材及人物肖像的使用权。

各规格组合当前能否生成,以 GET /v1/models 的 availability 为准;暂时无法生成时返回 503,不扣费。

项目 支持范围
时长 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 / 16 / 17 / 18 / 19 / 20 / 21 / 22 / 23 / 24 / 25 / 26 / 27 / 28 / 29 / 30 秒
分辨率 480P / 720P
画幅 16:9 / 9:16 / 1:1 / 4:3 / 3:4
参考图片 30 张以内
参考视频 10 段以内
参考音频 10 段以内
提示词 最多 11000 字符 / 33000 UTF-8 字节
计费 按生成秒数;带参考视频的 720P 按参考视频秒数 + 生成秒数
视频保留 72 小时,请及时下载

请求参数

Content-Type 为 application/json。不要把未支持的参数当作生效设置:当前不提供 callback_url、n 多条生成、指定首尾帧或流式输出。

参数 类型 必填 说明
model string 是 seedance-2.5
prompt string 是 视频描述;素材按 @Image1 / @Video1 / @Audio1 引用,序号对应各数组顺序。
duration integer 否 默认 5 秒;范围见规格。Clip 竖屏必须显式指定 15 秒。
resolution string 否 默认 720P;可选 480P, 720P
aspect_ratio string 否 默认 16:9;别名 size、ratio;不能互相冲突。
images array<string> 否 HTTPS 图片 URL 数组;别名 reference_images、image_url、image,同一类型只传一个字段。
video_references array<string> 否 HTTPS 视频 URL 数组;本模型不支持时不要传。别名 video_reference、video_url。
audio_references array<string> 否 HTTPS 音频 URL 数组;本模型不支持时不要传。别名 audio_reference、audio_url。
audio boolean 否 按条产品禁止传此参数;其他产品默认 true。false 不保证能关闭成片音轨,取决于模型本身。别名 generate_audio。
seconds integer 否 duration 的别名;同时传时必须相同。
image_role string 否 只接受 reference / reference_images / ref;不支持首尾帧。

价格与扣费

下面读取当前价格配置,与实际扣费函数使用同一来源。提交预扣与任务入库在同一事务完成;成功结算,最终失败退回预扣金额。

带参考视频的 720P 任务按(参考视频总时长 + 生成时长)× $0.11/秒 计费,参考视频总时长向上取整到秒(不足 0.05 秒的零头不计),不带参考视频的任务价格不变;参考图片、参考音频不计费。参考视频是本站上传接口返回的链接时,提交时就按实际时长预扣;其他链接先按参考视频上限 30 秒预扣,后台量出实际时长后、开始生成前退回差额,余额流水记一笔「退回多扣」。

分辨率 单价 USD 示例费用
480P 0.1 / 秒 5 秒:$0.50
720P 0.158 / 秒 5 秒:$0.79
720P 带参考视频 0.11 / 秒(参考视频 + 生成) 5 秒 + 参考视频 5 秒:$1.10

参考素材与示例

先上传素材并查询上传任务,拿到 media.vidbudget.com 链接后填入相应数组;也可使用可公开下载的 HTTPS 素材 URL。不接受 base64 或 data: URI。

图片可用于角色与风格参考,视频可用于动作和运镜参考,音频可用于声音节奏参考。是否支持各类型及数量以本模型规格为准。

素材下载与验证在后台进行;无法读取、格式不合法或违反内容规则可能导致任务失败。失败时退回预扣余额。

真人照片可能受到生成服务的内容限制;不能保证每次接受或每次输出符合主观预期。

视频保留 72 小时,请及时下载。上传素材也保留 72 小时,不要把临时链接用作永久存储。

JSON · 图片参考
{
  "model": "seedance-2.5",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}

响应结构

提交响应同样使用此结构,但 status 为 queued,completed_at 为 null、data 为空数组。error 在失败时是错误码字符串,成功或进行中为 null。

JSON · 查询完成
{
  "id": "TASK_UUID",
  "object": "task",
  "kind": "video",
  "model": "seedance-2.5",
  "status": "succeeded",
  "created_at": 1793354400,
  "completed_at": 1793354700,
  "elapsed_seconds": 300,
  "retry_count": 0,
  "error": null,
  "data": [
    {
      "url": "https://media.vidbudget.com/videos/VIDEO_UUID.mp4"
    }
  ]
}

任务状态与重试

retry_count 记录本任务额外重新生成的次数,初次为 0;查询次数不计入。completed_at 仅在最终成功或失败时写入,耗时包含排队、重试和媒体转存。

生成服务临时故障时系统会自动重新安排生成(同一任务最多 4 次),不额外扣费;提示词、素材或内容审核导致的失败不会重试。提交结果无法确认时不会重复购买,任务直接失败并退回预扣。一个任务只预扣一次、最终只结算或退款一次,每笔余额变化有流水。

状态 含义
queued 已入库等待后台处理
processing 素材处理、生成、轮询或转存进行中
succeeded 已完成,读取 data[0].url
failed 最终失败,读取 error;预扣自动退回

生成耗时与超时

视频生成可能需要数分钟或更久,时长、分辨率和排队都会影响完成时间。新站尚无真实生成耗时统计,不把原站实测值当作本服务承诺。

HTTP 请求时限为 85 秒,超时返回 JSON 504;生成总任务时限当前为 7200 秒。浏览器关闭不会取消后台任务。

503 表示该规格暂时无法生成,未扣费;稍后重试或调整规格,不要持续重复提交。

错误与处理方式

HTTP 错误结构为 {"error":{"code":"..."}},message 不保证存在。任务失败则通过任务对象的 error 字符串读取。

失败的任务还带 error_message,一句可以直接给你的用户看的说明;content_rejected 另有 error_reason,指出是哪项审核拒绝的:copyright(版权)、real_person(真人)或 safety(内容安全)。审核来自模型本身,原样重新提交同样的提示词和素材很少能通过。

HTTP / 任务 错误码 处理
400 invalid_request 检查参数、类型、素材字段和模型约束
401 invalid_api_key / login_required 检查密钥或登录状态
402 insufficient_balance 充值后再提交
404 task_not_found 确认任务属于当前用户,ID 正确
409 conflict 模型关闭或幂等键参数冲突
413 payload_too_large 大文件使用预签名直传
415 unsupported_media_type 仅上传图片/视频/音频
429 upload_rate_limit 等待窗口恢复
503 temporarily_unavailable 该规格暂时无法生成,未扣费,稍后重试
504 request_timeout 查询原任务,避免重复购买
任务 media_processing_failed 检查素材能否读取及实际文件格式
任务 generation_timeout 任务达到总时限,预扣退回
任务 content_rejected 提示词或素材未通过内容审核,修改后再提交
任务 content_rejected · copyright 模型自带的版权审核:提示词或参考素材里有点名的游戏、动漫或影视角色、名人、品牌或 logo、歌曲。请使用原创角色和自己的参考素材
任务 content_rejected · real_person 模型自带的真人审核:参考素材或成片里出现了真人的脸
任务 content_rejected · safety 模型自带的内容安全审核(提示词或成片),例如裸露、色情或暴力细节
任务 reference_rejected 参考素材时长、格式或内容不符合要求
任务 request_not_accepted 这组时长、画幅或素材暂时无法生成,调整后再试
任务 generation_failed / service_unavailable 已自动重试仍未完成,稍后再试
任务 service_busy 生成服务繁忙:排队等待超过上限(默认 10 分钟)或自动重试后仍繁忙,预扣已全额退回,稍后再提交
任务 submission_unconfirmed 提交结果无法确认,已退回预扣,可直接重新提交
429 too_many_active_tasks 同一账户同时排队或生成中的视频任务已达上限(默认 50 个),未扣费;等已有任务完成后再提交,响应带 Retry-After: 30
429 rate_limited 请求过于频繁,未扣费;按响应头 Retry-After 的秒数等待后重试,见「请求限流」
503 service_busy 服务暂时繁忙,这次请求没有生效、未扣费;按响应头 Retry-After 的秒数(通常 2 秒)后重试,提交时复用同一个 Idempotency-Key
402 key_daily_budget_exceeded 这把密钥今天(UTC)的预算已用完,未扣费;UTC 0 点恢复,或在控制台调高
403 key_ip_not_allowed 这把密钥只允许白名单 IP 调用,当前 IP 不在其中
403 key_model_not_allowed 这把密钥不允许调用这个型号

请求限流

每把 API 密钥分别计数(在线试用使用账户自己的计数),用令牌桶:额度用完后按每分钟上限匀速恢复。默认:查询(GET /v1/*)每分钟 1200 次,可短时突发 100 次;提交生成与上传(POST /v1/videos/generations、/v1/uploads*)每分钟 120 次,可短时突发 30 次。密钥无效或未登录的请求按来源 IP 计数,每分钟 60 次。

超出时返回 HTTP 429,错误码 rate_limited,不扣费;响应头 Retry-After 是需要等待的秒数。所有 /v1 响应都带 X-RateLimit-Limit(每分钟上限)、X-RateLimit-Remaining(当前还能立即发出的请求数)、X-RateLimit-Reset(额度完全恢复还需的秒数)。

查询大量任务时,用 GET /v1/tasks 一次取最近 100 个,或在控制台配置 Webhook 接收结束通知,不必逐个高频查询。每个账户同时排队或生成中的视频任务默认最多 50 个,超出返回 429 too_many_active_tasks。

素材上传与大文件直传

每 API key 每小时默认限制当前为 150 次。普通上传上限为 90000000 字节;超过此值使用预签名 PUT。直传上限 1000000000 字节,签名有效期 15 分钟。

支持图片、视频、音频 MIME,并在后台解码验证实际内容。推荐 PNG/JPEG/WebP,MP4,MP3/WAV/M4A。批量上传时每个文件单独请求,建议最多 6 路并发,保留添加顺序作为素材编号。

PUT 到 upload_url 时只带返回的上传 headers,不发送 VidBudget API key。上传完成后调用 complete,再查询任务取得最终素材 URL。

cURL · 普通上传
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"

Webhook:任务结束时推送

在控制台的「Webhook」页登记最多 3 个 https 地址并选择事件。用 API 密钥提交的任务一结束(成功、失败、超时或退款都算),我们向每个订阅了该事件的地址 POST 一次;在线试用提交的任务不推送。也可以继续轮询 GET /v1/tasks/{id};单次请求不支持 callback_url。

请求体:{"id":"evt_…","type":"task.succeeded","created":<Unix 秒>,"data":<与 GET /v1/tasks/{id} 相同的任务对象>}。同一事件重试时 id 不变,可用来去重。

签名:请求头 VidBudget-Signature: t=<Unix 秒>,v1=<十六进制 HMAC-SHA256>,签名内容是「t + 英文句点 + 原始请求体」,密钥是这个地址的签名密钥(whsec_ 开头,只在创建或重置时显示一次)。用原始字节验签,并拒绝 5 分钟以前的 t。

投递:返回任意 2xx 即算送达;10 秒内没有响应、连接失败或其他状态码,会在 1 分钟、5 分钟、30 分钟、2 小时、6 小时后重试,共 6 次。不跟随重定向;地址必须是公网 https、端口 443,内网、本机和保留地址一律不发。

原版同步上传、其他支付方式、其他模型及旧站特有响应字段不适用于本接口。账户接口:GET /v1/balance、GET /v1/tasks、GET /v1/models。

事件 何时发送
task.succeeded 任务成功;data.data[0].url 是成片链接
task.failed 任务最终失败;data.error 是错误码,预扣已全额退回
webhook.test 在控制台点「发送测试事件」
Python · 验签
import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    """header = the VidBudget-Signature value; body = the raw request bytes, not re-encoded JSON."""
    fields = dict(part.split("=", 1) for part in header.split(","))
    stamp = int(fields["t"])
    if abs(time.time() - stamp) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{stamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields.get("v1", ""))

# Flask: verify(SECRET, request.headers["VidBudget-Signature"], request.get_data())

登录 VidBudget

余额、API 密钥和生成记录都在你的账户里。

或
使用 Google 登录

还没有账户?免费注册

联系我们

账户、充值、生成结果或 API 接入的问题,都可以找我们。

充值问题请附上订单号,生成问题请附上任务 ID,方便我们直接核对。

退款说明 →API 文档 →