Seedance 2.5 请求与返回参数

本页于 2026-09-07 核对火山引擎官方创建视频生成任务（更新于 2026-09-04）和查询视频生成任务（更新于 2026-08-19），并对照 ModelSell 当前接口转换行为整理。

示例使用官方模型 ID doubao-seedance-2-5-260628。调用 ModelSell 时，请使用账户实际可用的模型名和 ModelSell API Key；渠道中的模型别名或 -max 后缀不属于官方 Model ID。

任务类型引导

omni_reference_task_type 是可选的 string 请求字段，官方默认值为 auto，仅 Seedance 2.5 支持。它用于全模态参考任务的类型引导，不代表模型一定按指定类型执行。

原生接口把该字段放在 JSON 顶层。通用接口也推荐顶层字段，并兼容 metadata.omni_reference_task_type；两者都传时顶层优先。请显式填写编辑、延长所需的关联参数。网关校验枚举和关联字段，参考视频的真实时长由上游检查。

原生请求字段

接口为 POST /api/v3/contents/generations/tasks。下表的默认值和范围来自官方模型说明；实际可用字段取决于所选渠道。内置火山渠道和六个 Seedance 模板均转发下列原生选项；通用接口通过 metadata.<字段名> 传递高级选项，具体功能仍需所选上游模型支持。

官网同时列出的 frames、seed、camera_fixed、draft 和 service_tier: "flex" 属于其他模型的能力，不能据此认为 Seedance 2.5 支持。需要指定整数秒时使用 duration。

2026-09-09 对照官方 SDK 请求结构补齐全系列字段转发。未传选项不会注入默认值，显式 false / 0 会保留。完整映射及尾帧示例见通用视频格式调用。

输入素材与角色

图片角色为 reference_image、first_frame 或 last_frame，视频为 reference_video，音频为 reference_audio。首帧、首尾帧、全模态参考三种模式互斥；不要把 first_frame / last_frame 和参考媒体模式混用。

2.5 全模态参考最多 30 张图片、10 个视频、10 段音频；视频总时长和音频总时长分别不超过 30 秒。单个参考视频一般为 2–30 秒，编辑用视频为 4–30 秒；单段音频为 2–30 秒。2.0 对应上限是 9 张图片、3 个视频、3 段音频，视频和音频各不超过 15 秒。

官网支持图片和音频 URL、Base64 Data URL，以及受支持的 asset:// 引用；视频使用 URL 或受支持的 asset:// 引用，不支持 Base64。官方单张图片小于 30 MB、单个视频不超过 200 MB、单段音频不超过 15 MB，请求体不超过 64 MB；渠道可能采用更小的上传限制。2.5 官网支持仅音频输入，ModelSell 原生与通用入口支持有效媒体或样片内容不附带提示词；具体组合由上游校验。

编辑请求示例

把示例 URL 替换为可访问的 4–30 秒视频：

curl -X POST "$MODELSELL_BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $MODELSELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "omni_reference_task_type": "edit",
    "content": [
      {"type": "text", "text": "编辑参考视频，将背景改成雪山，保留原有动作和镜头。"},
      {"type": "video_url", "video_url": {"url": "https://example.com/reference-video.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": -1,
    "resolution": "720p",
    "generate_audio": true
  }'

延长任务使用相同的参考视频结构，将任务类型改为 extend，提示词明确写“向后延长参考视频”，保持 ratio: "adaptive"，例如指定 duration: 10。参考生成新视频时使用 reference，提示词明确描述新视频内容。

创建与查询返回参数

官方创建成功的最小响应只有 id，并不表示视频已生成。ModelSell 会把任务 ID 替换为公共任务 ID；后续查询必须使用返回的 id：

{"id":"task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6"}

curl "$MODELSELL_BASE_URL/api/v3/contents/generations/tasks/task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6" \
  -H "Authorization: Bearer $MODELSELL_API_KEY"

以下为采用方舟原生响应的渠道字段。返回字段随任务状态、模型和渠道而变化，不能要求未列为必填的字段始终存在。官网未把 omni_reference_task_type 列为返回字段，不要依赖它回传。

官方视频链接有效期为 24 小时，2.5 视频 URL 最多下载 100 次；官方查询接口仅保留最近 7 天的任务。这些是方舟上游限制，其他渠道和 ModelSell 本地任务记录可能不同，建议成功后及时转存。

{
  "id": "task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "content": {"video_url": "https://example.com/seedance/result.mp4"},
  "created_at": 1788753600,
  "updated_at": 1788753660,
  "duration": 8,
  "framespersecond": 24,
  "resolution": "720p",
  "ratio": "16:9",
  "output_format": "mp4",
  "generate_audio": true,
  "usage": {"completion_tokens": 108900, "total_tokens": 108900},
  "error": null
}

其他渠道和通用格式

Service Inference / Max 渠道的原生响应会把上游 task 对象展开到顶层：成功状态为 completed，视频地址取 outputs[0]，时长可能为 duration_seconds，完成时间为 completed_at；还可能有 usage、last_frame_url、prep 和字符串 error。这些字段不能与方舟的 content.video_url 混为一谈。

{
  "id": "task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6",
  "status": "completed",
  "model": "doubao-seedance-2-5-260628-max",
  "outputs": ["https://example.com/seedance/result.mp4"],
  "duration_seconds": 8,
  "error": null
}

GET /v1/videos/{task_id} 使用规范化对象 object: "video"，状态为 queued、in_progress、completed、failed。成功地址为 video_url / metadata.url，尾帧为 metadata.last_frame_url，用量为 metadata.usage，实际输出格式为 metadata.output_format，仅在上游提供时返回。GET /v1/video/generations/{task_id} 则保留 {code, data} 包装，任务状态为 data.status，上游原始快照位于 data.data。兼容字段 task_id 可能省略，应保存 id。原生入口也有渠道采用这一通用响应，接入前按选用渠道确定结构。完整示例见通用视频格式调用。

同步与异步错误

{
  "id": "task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6",
  "status": "failed",
  "error": {
    "code": "InvalidParameter.TaskTypeMismatch",
    "message": "The detected task type does not match omni_reference_task_type."
  }
}

错误示例中的 message 仅作说明，实际文案以上游为准。通用响应的 error.code 可能规范化为 failed，不要要求它保留方舟原始错误码。轮询遇到 failed、cancelled 或 expired 应停止，并设置本地等待上限。