参数与错误

本页只描述 Seedance 在统一异步接口 POST /v1/video/tasks 中公开的字段。Seedance 当前只支持 generation，不支持通过该接口执行编辑、扩展或 remix。

模型与分辨率

具体可用模型以控制台模型广场或 GET /v1/models 为准。分辨率由所选模型固定，不能通过请求参数修改；output.resolution 和 provider_options 中的 resolution 参数都会被拒绝。

公共请求字段

字段	类型	必填	说明
`model`	string	是	控制台模型广场或 `GET /v1/models` 返回的 Seedance 模型 ID
`operation`	string	是	Seedance 固定为 `generation`
`input.prompt`	string	是	视频生成提示词，去除首尾空格后不能为空，最多 1200 个 Unicode 字符
`input.reference_mode`	string	否	参考素材模式；支持值由模型 ID 范围决定，纯文本请求可省略
`input.image`	object	否	第一张参考图；`frame` 模式下表示首帧
`input.reference_images`	array	否	追加的有序参考图数组，传入时不能为空数组
`input.reference_videos`	array	否	`media` 模式使用的参考视频数组
`input.reference_audios`	array	否	`media` 模式使用的参考音频数组
`output.duration`	integer	是	输出时长，单位为秒；2.0 / Fast 为 4–15，2.5 为 4–30
`output.aspect_ratio`	string	否	输出画幅，默认 `16:9`
`output.generate_audio`	boolean	否	是否生成成片音轨，省略时默认 `true`
`client_reference_id`	string	否	业务侧关联 ID，最长 191 个字符
`metadata`	object	否	自定义 JSON 对象，会随任务查询和 Webhook 原样返回

请求 JSON 使用严格字段校验。字段名拼错或传入未支持字段时会返回 400，不会静默忽略。

模型 ID 范围差异

下表是不同模型 ID 范围的参数差异。* 仅表示一组模型 ID，不是请求中需要填写的字符；完整模型 ID 仍以控制台模型广场或 GET /v1/models 为准。

模型 ID 范围	有参考素材时的 `input.reference_mode`	图片参考	视频参考	音频参考	素材总数
`adobe-seedance-*`	`frame` 或 `media`	`frame` 最多 2 张；`media` 最多 9 张	`media` 最多 3 个	`media` 最多 3 个	`frame` 最多 2 项；`media` 最多 12 项
`leonardo-seedance-2.0-`、`leonardo-seedance-2.0-fast-`	`media`	最多 4 张	最多 3 个	最多 1 个，且必须搭配图片或视频	最多 8 项
`leonardo-seedance-2.5-*`	`frame` 或 `media`	`frame` 为 1–2 张；`media` 最多 30 张	`media` 最多 10 个	`media` 最多 10 个，且必须搭配图片或视频	`frame` 最多 2 项；`media` 最多 50 项

所有图片数量都包含 input.image。2.5 的上述数量是网关可接收的公开上限；下游会读取当前模型能力，若实际能力收紧，会在上游 Generate 前返回具体校验错误。

参考素材	Seedance 2.0 / Fast	Seedance 2.5
图片	PNG/JPEG/WebP，单张最多 20 MB	PNG/JPEG/WebP，单张最多 20 MB
视频	MP4/MOV，单个 3–10 秒、最多 200 MB；总时长最多 15 秒	MP4/MOV，单个 3–10 秒、最多 200 MB；总时长最多 30.2 秒
音频	MP3/WAV，单个 2–15 秒、最多 15 MB；总时长最多 15 秒	MP3/WAV，单个 2–15 秒、最多 15 MB；总时长最多 30.2 秒

调用方不传视频或音频时长，服务会检测真实文件并在上传后复核。 input.reference_audios 是参考输入，output.generate_audio 是成片音轨开关，两者互不替代。

输出参数

字段	可选值	默认值	说明
`output.duration`	2.0 / Fast 为 4–15；2.5 为 4–30 的整数	无	必填，生成目标时长，单位为秒
`output.aspect_ratio`	`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`	`16:9`	输出画幅
`output.generate_audio`	`true`、`false`	`true`	是否请求生成成片音轨；不表示音频参考输入

不要传 output.resolution。选择分辨率时直接更换为对应的完整模型名。

参考素材

参考来源对象只使用绝对 HTTP/HTTPS url，可选的 name 在全部图片、视频和音频中必须唯一：

json

{
  "url": "https://media.example.com/reference.mp4",
  "name": "motion"
}

项目	限制
URL 类型	绝对 HTTP/HTTPS URL
Data URL / Base64	不支持
`provider` + `file_id`	不支持
multipart	`/v1/video/tasks` 不支持；本地文件使用 `/v1/media/uploads` 直传
视频输入 `input.video`	不支持

具体支持的参考模式和素材数量见“模型 ID 范围差异”。frame 只接受图片，顺序为 input.image 在前，再依次追加 input.reference_images[]。media 按图片、视频、音频分组处理，使用 name 和提示词中的 @name 建立语义引用。

视频和音频参考的时长以实际内容为准，不信任扩展名、客户端 MIME 或客户端声明。 Leonardo 参考音频无需也不接受客户端时长字段。该限制与生成视频的 output.duration 相互独立。

本地文件直传

本地参考素材不进入 SuperToken 请求体：

使用 ak_... 调用 POST /v1/media/uploads，提交 kind、mime_type 和 size_bytes。
按响应中的 method、upload_url 和 headers 直接 PUT 到对象存储。
使用 ak_... 调用 POST /v1/media/uploads/complete。
把确认响应中的临时 HTTPS url 放入视频任务参考字段。

直传创建和确认接口每次最多处理 12 项。确认时会校验实际对象大小与 MIME；SuperToken 只处理上传元数据，不接收文件字节。

旧参数迁移

generate_audio 与 reference_mode 已成为供应商无关的公共字段。以下旧写法不再兼容：

json

{
  "provider_options": {
    "adobe_video": {
      "generate_audio": true,
      "reference_mode": "media"
    }
  }
}

改为 output.generate_audio 和 input.reference_mode。旧字段会在任务创建、幂等重放和扣费前返回 400 invalid_provider_options，错误消息会指出对应的新字段。provider_options 仅保留给无法统一的供应商高级参数，不能用于覆盖模型、提示词、时长、画幅、分辨率或参考素材。

按秒计费

当模型配置为视频按秒计费时，创建任务前会使用 output.duration 作为有效计费秒数：

text

费用额度 = 每秒价格 × output.duration × 当前分组倍率

分组倍率沿用 Token 所属分组或聚合分组的有效倍率，不在视频请求中单独设置。不同分辨率使用不同模型，不再叠加 resolution、size 等倍率。参考素材数量、素材时长和 reference_mode 不改变计费秒数。

提交前会按完整请求时长预扣；异步任务失败时按平台现有任务退款规则处理。实际价格和可用资金来源以控制台当前模型定价为准。

任务对象

字段	说明
`id`	平台任务 ID
`object`	固定为 `video.task`
`model`	创建时使用的公开模型名
`operation`	Seedance 固定为 `generation`
`status`	`queued`、`in_progress`、`succeeded` 或 `failed`
`progress`	0 到 100 的整数进度
`result`	成功时包含 `videos[]`，其他状态通常为 `null`
`error`	失败时包含错误，其他状态为 `null`
`client_reference_id`	创建时传入的业务关联 ID
`metadata`	创建时传入的自定义对象
`created_at`	创建时间，Unix 秒
`started_at`	开始处理时间，Unix 秒；未开始时为 `null`
`completed_at`	完成时间，Unix 秒；未完成时为 `null`
`updated_at`	最后更新时间，Unix 秒

视频结果字段

字段	说明
`asset_id`	资源管理中心中的视频资源 ID
`index`	结果序号，从 0 开始
`url`	视频访问地址
`mime_type`	视频 MIME 类型，通常为 `video/mp4`
`filename`	建议文件名
`width` / `height`	有值时返回；不可用时字段可能省略
`duration_ms`	结果时长元数据，单位为毫秒；当前回显已验证的请求时长
`temporary`	是否应将 URL 视为临时地址
`url_auth`	`resource_api_key` 或 `none`，决定下载时是否附加 `ak_...`

duration_ms 用于展示和审计。当前不会下载结果媒体重新探测时长，而是回显已验证的请求时长；不会根据该字段再次补扣或退款，计费使用创建请求中的 output.duration。

结果为 temporary: true、url_auth: "none" 时，浏览器可以直接访问完整的 HTTPS 签名 URL，不附加 SuperToken Key；地址过期后不会刷新或归档。若返回 resource_api_key，则按响应字段携带资源 API Key。

列表查询参数

GET /v1/video/tasks 支持：

参数	说明
`status`	`queued`、`in_progress`、`succeeded` 或 `failed`
`operation`	Seedance 使用 `generation`
`client_reference_id`	按业务关联 ID 精确筛选
`created_after`	创建时间下限，Unix 秒
`created_before`	创建时间上限，Unix 秒
`after`	上一页最后一个任务 ID
`limit`	默认 20，范围 1 到 100

批量查询 POST /v1/video/tasks/query 的 task_ids 必须包含 1 到 100 个任务 ID。响应保持请求中的任务顺序，并通过 missing 返回当前账号下未找到的 ID。

错误格式

创建与查询接口使用统一错误对象：

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_video_duration",
    "message": "duration must be between 4 and 15 seconds",
    "request_id": "request_example123"
  }
}

终态失败位于任务对象的 error 字段：

json

{
  "code": "video_task_failed",
  "message": "Video task failed",
  "retryable": false
}

常见错误

HTTP 状态或错误码	常见原因	处理方式
`400 invalid_request`	JSON 无效、`duration` 不是整数、缺少模型/提示词、包含未知字段、参考素材不是 HTTP(S) URL、参考数量超限，或 `frame` 传了视频/音频	对照字段表和数量限制修正请求
`400 video_duration_required`	缺少 `output.duration`	按所选模型传入整数秒
`400 invalid_video_duration`	时长超出所选模型范围	2.0 / Fast 使用 4–15 秒；2.5 使用 4–30 秒
`400 invalid_video_aspect_ratio`	画幅不受 Seedance 支持	使用 `21:9`、`16:9`、`4:3`、`1:1`、`3:4` 或 `9:16`
`400 unsupported_reference_mode`	所选模型 ID 范围不支持请求中的参考模式	按“模型 ID 范围差异”选择模式
`400 invalid_video_parameter`	提示词超过 1200 个字符、传了 `output.resolution`、音频没有图片/视频，或 `frame` 素材组合无效	缩短提示词、移除分辨率字段，或按模型补充正确参考素材
`400 invalid_provider_options`	使用了旧音轨/参考模式字段，或命名空间、专用参数无效	改用 `output.generate_audio`、`input.reference_mode`，并移除重复覆盖字段
`400 unsupported_video_operation`	使用了 `edit`、`extension` 或 `remix`	改为 `generation`
`400 unsupported_video_model`	模型未开放或不受支持	查询 `GET /v1/models` 并核对模型 ID
`invalid_reference_media_duration`	无法解析参考视频或音频的真实时长	检查文件内容、编码与 MIME
`reference_media_duration_exceeded`	参考视频或音频的合计时长超过模型上限	裁剪素材后重新上传并创建新任务
`401` / `403`	Key 无效、已停用、权限不匹配或混用了 Key	按接口换用正确的 `sk-...` 或 `ak_...`
`404 task_not_found`	任务不存在或不属于当前资源 Key 账号	核对任务 ID 和账号
`409 idempotency_key_conflict`	同一 Key 被用于不同请求	为新请求生成新的幂等 Key
`429`	请求过于频繁或达到限流	降低提交或轮询频率后重试

不要盲目重试参数类 400。遇到任务终态 failed 时，先读取 retryable；确需重新创建任务时使用新的 Idempotency-Key，复用原 Key 只会返回原任务。

GPT-Image-2

Gemini Images

Seedance

Kling 3.0

Veo 3.1

MiniMax H3

参数与错误

模型与分辨率

公共请求字段

模型 ID 范围差异

输出参数

参考素材

本地文件直传

旧参数迁移

按秒计费

任务对象

视频结果字段

列表查询参数

错误格式

常见错误

下一步

参数与错误 ​

模型与分辨率 ​

公共请求字段 ​

模型 ID 范围差异 ​

输出参数 ​

参考素材 ​

本地文件直传 ​

旧参数迁移 ​

按秒计费 ​

任务对象 ​

视频结果字段 ​

列表查询参数 ​

错误格式 ​

常见错误 ​

下一步 ​

参数与错误

模型与分辨率

公共请求字段

模型 ID 范围差异

输出参数

参考素材

本地文件直传

旧参数迁移

按秒计费

任务对象

视频结果字段

列表查询参数

错误格式

常见错误

下一步