API v1

创建视频任务

POST/v1/video/generations

提交提示词和可选的图片、视频或音频,创建一个异步生成任务,立即返回任务 ID 和预留金额。

查看 Markdown
  • 在请求头 Authorization: Bearer 后面放 API 密钥。
  • 必须带 Idempotency-Key:结果不明时用同一个键原样重试,只会创建一个任务、扣一次费。
  • 生成在后台进行:用「查询视频任务」轮询,或用 callback_url 接收 task.completed。
  • 创建时按上限预留金额,完成后按实际用量结算;失败或取消的任务不收费。

请求头

#Authorizationstring必填

Bearer 加一个空格和 API 密钥。缺失或无效时返回 401 authentication_failed。

#Content-Typestring必填

请求体是 JSON:application/json。

#X-Request-IDstring

你自己的请求标识。无效或重复的值会被替换,最终值在响应头 X-Request-ID 返回。

#Idempotency-Keystring必填

每个新请求生成一个新值并保存,以字母或数字开头。结果不明时用同一个键和原请求体重试,会返回原响应;同一个键配不同的请求体返回 409 idempotency_conflict。键按团队区分,不按 API 密钥区分。

长度8–128字符A–Z a–z 0–9 . _ : -

请求体application/json · 必填

请求体只接受下列字段,其他字段会被拒绝。

#modelstring必填

本次使用的模型标识。

dreamina-seedance-2-0-260128Seedance 2.0
dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast
dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini
#contentarray必填

平台限制:最多 9 张图片、3 段视频、3 段音频,共 15 份素材、16 项 content。视频和音频单段均为 2–15 秒,各自合计最多 15 秒。HTTPS 素材由平台下载、扫描、保存并审核后用于生成;准备失败全额释放预留费用,不收生成费。已知素材准备失败时同时返回 content_index。

数量1–16
每一项必须且只能符合下列一种结构。
#typestring必填

输入项类型。

固定为text
#textstring必填

生成提示文本。

长度1–10000
#resolutionstring

输出分辨率。Seedance 2.0 Fast 和 Mini 只接受 480p 或 720p。

默认720p可选480p720p1080p
#ratiostring

画面宽高比。

默认adaptive可选adaptive21:916:94:31:13:49:16
#durationinteger

输出时长,4–15 的整数秒,默认 5 秒。

默认5范围4–15
#generate_audioboolean

是否生成音频。

默认false
#seedinteger

随机种子,默认 -1,表示随机。

范围-1–4294967295默认-1
#watermarkboolean

是否添加水印。

默认false
#callback_urlstring

任务结束后接收回调的地址。必须与本团队在控制台已验证、未撤销、未过期的回调地址逐字节相同,否则返回 400 callback_target_not_verified。用同一个 Idempotency-Key 重试时不能增加、去掉或更换它,否则返回 409 idempotency_conflict。

长度1–2048格式https://
暂不支持的参数7
return_last_frame

设为 true 时返回 400 unsupported_capability。

draftoutput_formatomni_reference_task_typeexecution_expires_afterprioritysafety_identifier

当前模型不接受,传入即返回 400 invalid_request。

返回HTTP 202

已受理:任务已创建,金额已预留。响应头 Location 是任务的查询路径。

#idstring必填

平台任务标识。

长度4–128字符A–Z a–z 0–9 _ -
#objectstring必填

对象类型标识。

固定为video.task
#request_idstring必填

请求关联标识。

长度4–128字符A–Z a–z 0–9 _ -
#billing_correlation_idstring必填

费用关联标识。

长度4–128字符A–Z a–z 0–9 _ -
#modelstring必填

本次使用的模型标识。

dreamina-seedance-2-0-260128Seedance 2.0
dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast
dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini
#statusstring必填

当前状态,具体含义见对应取值。

固定为queued
#phasestring

生成开始前正在准备输入素材。

固定为preparing_assets
#settlement_statusstring必填

当前费用结算状态。

固定为reserved
#quoteobject必填

接受任务时的预留报价。

6 个子字段
#currencystring必填

金额币种,美元。

固定为USD
#reserved_amountstring必填

接受任务所需的预留金额。

格式6 位小数
#meter_typestring必填

用量计量类型。

固定为seedance_video_generation
#estimated_usage_upper_boundobject必填

预估用量上界。

1 个子字段
#video_tokensinteger必填

视频计量单位数;实际用量允许为空的情况以字段类型为准。

范围≥ 1
#price_versionstring必填

本次报价的价格版本。

长度4–128字符A–Z a–z 0–9 _ -
#quote_policy_versionstring必填

预留报价策略版本。

长度1–128字符A–Z a–z 0–9 . _ : -
#created_atinteger必填

创建时间,Unix 整数秒。

范围≥ 0

响应头

#X-Request-IDstring必填

本次请求的标识:你提供的有效值,或替换后的值。

#Locationstring必填

已接受对象的规范查询路径。

状态码

每个 error.code 的处理办法见「错误码」。

状态码说明与 error.code
202已受理:任务已创建,金额已预留。
响应头Location
400请求格式或参数不对,或引用的素材、回调地址不能用。
401API 密钥缺失或无效。
响应头WWW-Authenticate
409幂等键冲突或重放已过期,API 密钥未就绪,或素材还在处理。
429余额不足、请求太频繁,或素材存储已满。
响应头Retry-After
500服务内部错误。
503服务暂时不可用,或暂停接收新任务。