Seedance 2.5 视频生成 API

APIMaster 关于 Seedance 2.5 参数、参考媒体、首尾帧、编辑、异步结果、计费和故障排除的详细指南。

Seedance 2.5 视频生成

使用公开模型 ID seedance-2.5，从文本、图像、视频或音频参考创建视频。生成是异步的：提交一个请求，保存其公开任务 ID，轮询直到完成，然后下载结果。成功提交意味着任务已被接受；这并不意味着视频已经生成。

图像转视频、编辑与延长任务的重要提示： 默认宽高比为 adaptive。请保持该值或省略宽高比字段；不要显式发送固定的宽高比，例如 16:9。对于仅包含图片的首尾帧任务，输出遵循第一张图像的比例。如果需要特定比例，请先裁剪或填充您的图像。

默认值变更 — 2026-10-01： 省略 duration 现在意味着 5 秒，而不是 4；默认宽高比是 adaptive，而不是 16:9；生成的音频默认为 true。如果您的集成依赖于固定的时长、宽高比或静音输出，请显式设置这些字段。

认证和端点

API 基础 URL 是 https://apimaster.ai/v1。从 API 密钥获取 APIMaster 密钥，并在请求中发送 Authorization: Bearer YOUR_API_KEY。JSON 请求还需要 Content-Type: application/json。请将密钥保存在您的服务器上，不要放在公共前端代码中。

方法	端点	用途
`POST`	`https://apimaster.ai/v1/videos/generations`	推荐的 JSON 任务提交
`GET`	`https://apimaster.ai/v1/video/generations/{task_id}`	兼容性格式的任务状态查询
`GET`	`https://apimaster.ai/v1/videos/{task_id}`	OpenAI 风格视频状态查询
`GET`	`https://apimaster.ai/v1/videos/{task_id}/content`	认证视频下载
`GET`	`https://apimaster.ai/v1/videos/{task_id}/last-frame`	认证尾帧下载（当请求时）

不要使用图像任务端点来轮询视频任务。请使用创建任务所属账户的密钥。

快速开始：文生视频

从一个短视频片段和明确的规格开始，然后再请求 30 秒或更高分辨率的视频。后续示例中的媒体 URL 请替换为您自己的可直接下载的文件。

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A lighthouse above a calm sea at sunrise. Slow camera push-in, natural lighting, no text.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "generate_audio": true,
    "watermark": false,
    "output_format": "mp4"
  }'

示例提交响应：

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_example"}],
  "error": null
}

保存返回的 task_id，并使用查询端点获取任务状态和最终视频。

请求参数与默认值

字段	类型	默认值	约束条件
`model`	字符串	无；必需	`seedance-2.5`
`prompt`	字符串	无；生成时必需	场景、动作、摄像机和参考意图；使用 `draft_task_id` 时省略
`duration`	整数	`5`；在 `edit` 中省略则变为 `-1`	`4`–`30` 秒或 `-1` 表示自动时长；编辑仅接受 `-1`
`resolution`	字符串	`720p`；样片 `480p`；样片升级 `1080p`	普通生成：`480p`, `720p`, `1080p`；样片和升级仅接受各自对应的分辨率
`aspect_ratio`	字符串	`adaptive`	`adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`；帧/编辑/延长任务需要 `adaptive`
`ratio`	字符串	同 `aspect_ratio`	别名；如果同时提供，两个值必须匹配
`size`	字符串	省略时为 `adaptive`	旧版尺寸/比例便捷字段；接受 `adaptive`。建议使用 `resolution` 和 `aspect_ratio`
`image_urls`	字符串数组	无参考	最多总共 `30` 张图像，包括 `image_with_roles`
`image_with_roles`	对象数组	无参考	包含 `url` 和 `role` 的对象；`first_frame`, `last_frame`, 或 `reference_image`
`first_frame_image` / `last_frame_image`	字符串	无帧	对应图像角色的别名；使用 HTTP(S) 或已批准的 `asset://` URL
`video_urls`	字符串数组	无参考	最多 `10`；总时长最多 `30` 秒
`audio_urls`	字符串数组	无参考	最多 `10`；总时长最多 `30` 秒；支持纯音频参考
`generate_audio`	布尔值	`true`	是否生成声音
`audio`	布尔值	同 `generate_audio`	别名；音频值冲突将返回 400
`watermark`	布尔值	`false`	是否请求生成内容水印
`seed`	整数	模型选择	将 `0` 保留为显式种子；种子不保证输出完全相同
`output_format`	字符串	`mp4`	`mp4` 或 `mov`；MOV 对编辑/扩展工作流有用。编解码器和色彩精度取决于结果文件
`omni_reference_task_type`	字符串	`auto`	`auto`, `reference`, `edit`, 或 `extend`；参见下方的同步验证
`nsfw_check`	布尔值	`false`	可选的提交前文本/图像审核
`return_last_frame`	布尔值	`false`	成功后，当帧可用时返回 `last_frame_url`
`draft`	布尔值	`false`	生成 480p 样片；仅 `seedance-2.5`
`draft_task_id`	字符串	未设置	成功样片的公共 APIMaster ID；将其升级为新的 1080p 任务

请使用 JSON 布尔值，而非诸如 "false" 之类的字符串。冲突的别名、不支持的分辨率、无效的时长以及任务特定的约束将在任务创建或其预留扣费之前返回 HTTP 400。省略的可选数组表示无参考。

附加字段与输入形式

字段或输入	接口支持
`negative_prompt`	作为文本接受；当启用 `nsfw_check` 时包含在审核中
`first_frame_image` / `last_frame_image`	支持的字符串别名；请勿在 `image_with_roles` 中重复同一帧
Base64 / data-URL 图像	不支持作为生成 URL。请通过 `/v1/uploads/images` 上传文件并使用返回的 URL
`generation_type`	作为普通生成的可选字段接受；使用 `omni_reference_task_type` 作为任务类型约束
`camerafixed`	作为普通生成的布尔值接受；在提示词中描述所需的摄像机运动
`service_tier`	普通生成可选；样片和样片升级均拒绝

请勿依赖 generation_type、camerafixed 或 service_tier 来保证特定的视觉结果或调度优先级。它们不能替代文档中规定的任务类型和提示词要求。

选择任务类型

任务	输入与意图	必需设置
文本生成视频	无参考媒体的提示词	选择支持的宽高比、分辨率和时长
参考生成	参考图像/视频/音频及对新场景的描述	可使用固定宽高比；确保提示词明确描述参考生成
首帧生成	一张图像，角色为 `first_frame`	`aspect_ratio: "adaptive"`
首尾帧生成	一张 `first_frame` 和一张 `last_frame`	`aspect_ratio: "adaptive"`；尾帧需要首帧
视频编辑	源视频加上要求编辑、移除、替换或修改内容的提示词	`aspect_ratio: "adaptive"`, `duration: -1`；源视频 `4`–`30` 秒
视频扩展	源视频加上要求继续或扩展它的提示词	`aspect_ratio: "adaptive"`；保持参考媒体在下述限制内

omni_reference_task_type 可以显式选择 auto、reference、edit 或 extend。使用匹配的提示词：声明 reference 同时要求替换对象仍可能导致任务类型不匹配。对于编辑，省略的时长将归一化为 -1；省略的宽高比为 adaptive。显式值必须满足相同的约束。对于参考生成，除非这是您的预期操作，否则避免使用编辑或扩展指令。

同步任务类型验证

声明的类型	接受前的验证
`edit`	至少一个 `video_urls` 条目；宽高比省略或为 `adaptive`；时长省略或为 `-1`；源视频 `4`–`30` 秒
`extend`	至少一个 `video_urls` 条目；宽高比省略或为 `adaptive`
`reference`	适用常规支持的宽高比和时长限制；无编辑/扩展限制
`auto`	任务意图根据提示词和参考推断

显式选择会在提交时捕获无效参数：HTTP 400，无任务，无生成预留。任务意图也会在生成期间评估；与声明类型不一致的提示词可能会异步失败，错误为 InvalidParameter.TaskTypeMismatch。为 edit 编写编辑提示词，为 extend 编写延续提示词，为 reference 编写新场景提示词。

图像角色与首尾帧

image_with_roles 条目使用 {"url": "https://example.com/frame.png", "role": "first_frame"}。角色包括 first_frame、last_frame 和 reference_image。最多使用一个首帧和一个尾帧。参考图像指导外观或构图；它们不强制生成完全相同的起始帧。避免混合定义重叠的 image_urls 和 image_with_roles。

如果还包含视频或音频参考，帧角色可被视为通用参考图像，而非严格的首/尾帧任务。当需要精确的帧锚定时，请使用纯图像输入。

{
  "model": "seedance-2.5",
  "prompt": "The camera moves smoothly from the first view to the last view. Preserve the building and lighting.",
  "image_with_roles": [
    {"url": "https://example.com/first.png", "role": "first_frame"},
    {"url": "https://example.com/last.png", "role": "last_frame"}
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": false
}

对于单个起始帧，请移除 last_frame 条目。如果需要不同的输出宽高比，请在提交前将首张图像裁剪或填充至该宽高比；仅更改 aspect_ratio 是不够的。

图像、视频和音频参考

在提示词中为每个参考指定明确的目的。参考按数组顺序从 1 开始索引；诸如 @图片1、@视频1 和 @音频1 等描述可以标识图像、视频和音频参考。请勿引用请求中不存在的索引。

{
  "model": "seedance-2.5",
  "prompt": "Create a new coastal scene using @图片1 for the color palette, @视频1 for camera movement, and @音频1 for the rhythm. Do not edit or extend the original video.",
  "image_urls": ["https://example.com/palette.png"],
  "video_urls": ["https://example.com/camera-reference.mp4"],
  "audio_urls": ["https://example.com/rhythm.mp3"],
  "omni_reference_task_type": "reference",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}

对于纯音频参考生成，请保留 audio_urls 并移除图像/视频数组。所有媒体必须无需浏览器登录、Cookie 或额外授权标头即可被生成服务访问。

编辑视频

{
  "model": "seedance-2.5",
  "prompt": "Edit the video: replace the red umbrella with a blue umbrella while preserving the subject and camera motion.",
  "video_urls": ["https://example.com/source.mp4"],
  "omni_reference_task_type": "edit",
  "duration": -1,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": true,
  "output_format": "mov"
}

编辑遵循源片段的时长。自动时长可能需要更大的初始余额预留；请参阅下方的计费说明。

扩展视频

{
  "model": "seedance-2.5",
  "prompt": "Extend the video forward: the cyclist continues along the same path, keeping the lighting and camera direction consistent.",
  "video_urls": ["https://example.com/source.mp4"],
  "omni_reference_task_type": "extend",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": true
}

参考媒体要求

这些是输入媒体的限制，而非输出尺寸。文件下载成功仍可能因其实际格式、尺寸、时长或内容不合适而被拒绝。

输入	数量	尺寸与时长	文件要求
图片	最多 `30` 张参考图片；帧模式使用一张或两张图片	每边 `300`–`6000` 像素；宽高比 `0.4`–`2.5`	每个文件小于 `30 MB`。推荐 JPEG/PNG；其他接受的格式包括 WebP、BMP、TIFF、GIF、HEIC、HEIF，取决于解码支持
视频	最多 `10` 个；总时长最多 `30` 秒	每个片段 `2`–`30` 秒；编辑源 `4`–`30` 秒。每边 `300`–`6000` 像素；宽高比 `0.4`–`2.5`；像素数 `409600`–`8295044`；`24`–`60` FPS	每个文件最多 `200 MB`；MP4/MOV 格式，视频编码为 H.264 或 H.265，音频编码为 AAC 或 MP3；支持的分辨率等级 `480p`、`720p`、`1080p`
音频	最多 `10` 个；总时长最多 `30` 秒	每个片段 `2`–`30` 秒	每个文件最多 `15 MB`；WAV 或 MP3 格式

请使用直接的 HTTPS 文件 URL，而非分享页面的 HTML URL。.png 文件名不会使 HTML 错误页面成为有效的图片。确保临时签名 URL 在任务获取媒体期间保持有效。避免重定向到登录页面以及受 IP 或防盗链规则限制的链接。为获得最佳图片兼容性，请将文件转换为 RGB JPEG 或 PNG 格式，并验证其实际宽度和高度。

仅上传您有权使用的媒体。内容检查可能会拒绝真实人物图像或其他受限材料；请勿假设公开可访问的 URL 就保证会被接受。

上传并在生成前审核媒体

APIMaster 支持图像文件上传和 Seedance 媒体库。这是两个独立的步骤：上传文件会提供一个可下载的 URL；将该 URL 提交到媒体库则启动内容审核。只有已获批准的库资产才能在生成请求中使用 asset:// 进行引用。普通的非人物参考媒体仍可直接使用公开 URL，无需提交到媒体库。

当您需要重复使用某个素材或其原始 URL 是临时性的时候，媒体库尤其有用。审核成功后，请重复使用返回的 asset:// 地址；未来的引用将使用已批准的素材，而无需您重新提交其原始 URL。只要您需要引用该素材，就将其保留在您的媒体库中。

真实人物媒体必须先提交到媒体库并通过审核。 文件上传成功、URL 可访问或审核任务提交成功，并不意味着素材已获批准。请仅使用您有权上传和使用的媒体。审核批准并不能保证后续的每个生成请求都能通过其自身的内容检查。

推荐的流程是：如果需要公开文件 URL，则上传图像 → 提交素材进行审核 → 轮询审核任务 → 选择 Active 资产 → 提交视频生成 → 轮询视频任务。保存每个步骤返回的 ID；使用文档中描述的用于视频生成的查询端点。

素材规格和准备

上方的参考媒体表格同样适用于媒体库提交。请检查实际解码后的文件，而不仅仅是其扩展名。对于 Seedance 2.5：

素材类型	接受格式	文件限制	技术要求
图像	JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF；推荐使用 RGB JPEG/PNG	每个库来源低于 `30 MB`	宽度和高度各在 `300`–`6000` 像素之间；宽高比 `0.4`–`2.5`
视频	MP4、MOV；H.264/H.265 视频；存在时支持 AAC/MP3 音频	每个文件最多 `200 MB`	每个片段 `2`–`30` 秒；编辑源 `4`–`30` 秒；每边 `300`–`6000` 像素；宽高比 `0.4`–`2.5`；总像素数 `409600`–`8295044`；帧率 `24`–`60` FPS；支持的层级 `480p`、`720p`、`1080p`
音频	WAV、MP3	每个文件最多 `15 MB`	每个片段 `2`–`15` 秒

一次审核提交包含 1–20 个同类型资产。此批次限制与生成限制不同：最多 30 张图像、10 个视频或 10 个音频片段；引用的视频总时长不得超过 30 秒，引用的音频总时长不得超过 30 秒。上传 20 个素材并不意味着所有 20 个视频或音频片段都能在一次生成中使用。

对于最长 30 秒的视频源，请明确提交 model: "seedance-2.5"。媒体库提交的默认值是 seedance-2.0，这会将单个视频源限制在 15 秒以内。音频库摄入目前有单独的 15 秒限制，如下所述。当请求的模型对您的密钥可用且素材满足该模型的限制时，已批准的素材可以在 Seedance 2.0 和 2.5 之间重复使用。

音频库摄入： 提交时长在 2 到 15 秒之间的单个音频片段，即使使用 model: "seedance-2.5" 也是如此。这与生成时 2–30 秒的音频引用限制是分开的。请对较长的源进行修剪或分割；生成请求仍然最多允许 10 个音频引用，总时长最多 30 秒。

视频审核错误： 审核请求被接受并不表示视频可用。审核可能因 FormatUnsupported 或 Unsupported media format 而失败。请检查实际的容器、编解码器、尺寸、帧率、音轨和 URL 可访问性；仅在库视频变为 Active 后才引用它。真实人物视频需要在生成前获得审核批准。

请使用无需登录、Cookie、额外授权标头或防盗链限制即可直接下载文件的 HTTP(S) URL。确保签名 URL 在检索和审核期间保持有效，并且其内容保持不变。分享页面 HTML、过期链接、私有网络地址、损坏的编解码器或误导性的文件扩展名可能导致拒绝。请将视频和音频上传到您自己的文件存储，并提交其直接 URL；下面的图像文件上传端点不接受视频或音频。

步骤 1：上传本地图像文件

将多部分表单数据发送到 POST https://apimaster.ai/v1/uploads/images，其中一个字段名为 file。请勿手动设置 JSON 内容类型：您的 HTTP 客户端必须提供多部分边界。

curl --fail-with-body -sS "https://apimaster.ai/v1/uploads/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./reference.png"

示例响应：

{
  "url": "https://apimaster.ai/imgs/media_upload_example.png",
  "filename": "reference.png",
  "content_type": "image/png",
  "bytes": 123456,
  "created_at": 1790812800
}

此端点仅接受 JPEG、PNG、GIF 和 WebP 格式，最大文件大小为 20 MiB（20 × 1024 × 1024 字节）。它会验证检测到的图像格式和可读的图像尺寸；上传成功并不验证每个 Seedance 要求或批准内容。超过此上传限制的图像，以及此列表中不存在的但与媒体库兼容的格式，需要您自己的公开文件存储。

返回的 URL 使用 APIMaster 的域名，任何知道该 URL 的人都可以公开读取。它旨在用于 API 媒体输入，而不是永久归档存储；请保留您的原始文件，不要假设有保证的保留期。请勿上传需要下载身份验证的机密内容。在下一步中重复使用此 URL，或者在不需要媒体库审核时直接在生成请求中使用。

步骤 2：提交素材进行审核

将 JSON 提交到 POST https://apimaster.ai/v1/seedance2/private-avatar/assets。设置一个新的 group 或一个现有的 APIMaster group_id，切勿同时设置两者。两者都省略将自动创建一个新组。

curl --fail-with-body -sS "https://apimaster.ai/v1/seedance2/private-avatar/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "group": {"name": "My reference materials", "description": "Approved generation references"},
    "project_name": "default",
    "asset_type": "Image",
    "assets": [
      {"url": "https://apimaster.ai/imgs/media_upload_example.png", "name": "reference-portrait"}
    ]
  }'

对于视频或音频，请在相同的 assets 结构中使用 asset_type: "Video" 或 asset_type: "Audio" 以及直接 URL。请勿在一次提交中混合类型。

字段	类型	要求和行为
`model`	字符串	本指南使用 `seedance-2.5`；默认值为 `seedance-2.0`
`group`	对象	可选的新组：`name` 最多 255 个字符，`description` 最多 4000 个字符
`group_id`	字符串	可选的现有组 ID，由 APIMaster 返回；必须属于您的账户
`project_name`	字符串	可选；目前仅支持 `default`
`asset_type`	字符串	区分大小写的 `Image`、`Video` 或 `Audio`；默认 `Image`
`assets`	对象[]	必需的数组，包含 `1`–`20` 个选定类型的素材
`assets[].url`	字符串	必需的公开 HTTP(S) 文件 URL；最多 8192 个字符
`assets[].name`	字符串	可选的显示名称，最多 255 个字符；如果省略，将使用自动生成的名称

示例接受响应：

{
  "code": 200,
  "data": {
    "id": "asset_task_example",
    "object": "seedance.avatar.asset.task",
    "model": "seedance-2.5",
    "status": "processing",
    "progress": 0,
    "group_id": "group_example"
  }
}

保存 data.id 作为审核任务 ID，并保存 data.group_id 用于后续提交。HTTP 成功响应仅确认请求已被接受。请勿根据文件名或任务 ID 构造资产 ID。

步骤 3：轮询审核任务并选择已批准的资产

每隔 5–10 秒轮询一次 GET https://apimaster.ai/v1/tasks/{review_task_id}，直到 data.status 变为 completed 或 failed。此端点用于素材审核任务；请使用本页其他地方记录的用于视频生成的视频端点。

curl --fail-with-body -sS "https://apimaster.ai/v1/tasks/asset_task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

示例完成响应；为简洁起见，此处省略了时间戳和源 URL 字段：

{
  "code": 200,
  "data": {
    "id": "asset_task_example",
    "object": "seedance.avatar.asset.task",
    "model": "seedance-2.5",
    "status": "completed",
    "progress": 100,
    "group_id": "group_example",
    "result": {
      "assets": [{"id": "asset_example", "asset_id": "asset_example", "asset_url": "asset://asset_example", "name": "reference-portrait", "asset_type": "Image", "group_id": "group_example", "status": "Active"}],
      "usable_assets": [{"id": "asset_example", "asset_id": "asset_example", "asset_url": "asset://asset_example", "name": "reference-portrait", "asset_type": "Image", "group_id": "group_example", "status": "Active"}],
      "failed_assets": []
    }
  }
}

审核任务状态为 processing、completed 和 failed。素材状态为 Pending、Active 和 Failed；只有 Active 的素材可以被引用。请原样使用返回的 asset_url。它标识一个已批准的媒体库素材，而不是 HTTP 下载 URL。

一个批次可能部分成功。 一个被拒绝的素材可能导致整个审核任务变为 failed，而其他素材已经 Active。请检查 result.usable_assets 和 result.failed_assets，而不是在任务失败时丢弃所有项目。在素材结果可用之前失败，可能会返回一个安全的 error 消息而没有结果。请仅纠正并重新提交被拒绝的输入；避免重复已接受的输入。

在依赖媒体库列表之前，请轮询审核任务：列表不会自动轮询待处理的审核任务。任务查询和资产详情返回后续请求使用的公开素材 ID。

步骤 4：使用已批准的素材进行生成

在 image_urls、image_with_roles[].url、video_urls 或 audio_urls 中使用已批准的 asset_url，并匹配素材类型。这个首帧示例使用了已批准的图像：

{
  "model": "seedance-2.5",
  "prompt": "The person slowly turns toward the camera, natural lighting, gentle camera movement.",
  "image_with_roles": [{"url": "asset://asset_example", "role": "first_frame"}],
  "aspect_ratio": "adaptive",
  "duration": 5,
  "resolution": "720p",
  "generate_audio": false
}

将此 JSON 提交到 POST https://apimaster.ai/v1/videos/generations，然后按照下面的描述轮询返回的视频任务。在一个账户下批准的资产不能被另一个账户使用。请保留 APIMaster 返回的 ID；从其他服务复制的 ID 将无法使用。在同一请求中组合的素材必须来自兼容的媒体库上下文；如果不可用，请在同一个 APIMaster 组中创建它们，并在审核后重试。删除素材将阻止未来的请求引用它。

如果使用媒体库资产的请求无法提交，请在重新提交前检查其状态和您的任务历史记录。避免立即重复的生成请求，尤其是在网络超时之后。

列出、检查、重命名和删除素材

所有端点都需要 APIMaster API 密钥。媒体库的作用域限定在您的账户，因此属于同一账户的密钥可以访问其资源；另一账户的资源将返回 HTTP 404。列表操作仅返回您账户的素材和组。

方法	端点	用途
`POST`	`https://apimaster.ai/v1/seedance2/private-avatar/groups`	使用 `model`、`name` 和可选的 `description` 创建组
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/groups`	列出您的组
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	检查一个组
`PATCH`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	更新 `name` 和/或 `description`
`DELETE`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	删除一个空组
`POST`	`https://apimaster.ai/v1/seedance2/private-avatar/assets`	提交审核批次
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/assets`	列出您的素材
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	检查素材并刷新其审核状态
`PATCH`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	更新显示 `name`
`DELETE`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	删除素材
`GET`	`https://apimaster.ai/v1/tasks/{review_task_id}`	查询审核任务

列表查询接受 page（默认 1）和 limit（默认 20，范围 1–100）。素材列表还接受您的 group_id 和区分大小写的 status 过滤器。其响应为 {"code":200,"data":{"items":[],"total":0,"page":1,"limit":20}}；项目使用与素材/组详情相同的公开字段。列表结果不包括在 APIMaster 之外创建的资源。

示例：

# List approved materials in a group.
curl --fail-with-body -sS "https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_example&status=Active&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Rename one material without changing the source file.
curl --fail-with-body -sS -X PATCH "https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_example" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"approved-reference"}'

# Delete a material before deleting its group.
curl --fail-with-body -sS -X DELETE "https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

组创建默认为 seedance-2.5；为清晰起见，请明确提供 model。显示名称的更改不会替换素材文件或重复审核。要替换媒体，请提交新的审核。尚未完成审核的待处理素材无法重命名或删除，并返回 HTTP 409。在删除组之前，请删除组中的每个素材；非空组返回 HTTP 409。成功删除返回 {"code":200,"data":{"id":"asset_example","deleted":true}}（组删除返回其组 ID）。

费用、速率限制和错误

图像文件上传、素材审核和媒体库 CRUD 操作不产生生成费用，也不会创建视频使用计费记录。使用已批准素材的视频生成会根据所选模型和引用正常计费。免费的媒体库操作仍然需要有效的授权密钥，并且仍然受 API 密钥/模型速率限制。上传和创建端点还限制每个 IP 的请求；请间隔发送请求，而不是发送大量突发请求。

HTTP 状态码	含义	建议操作
`400`	JSON、字段、URL、图像数据、类型或批次大小无效	检查模式和实际文件属性
`401` / `403`	密钥缺失/无效或模型权限不足	验证您的 APIMaster 密钥和允许的模型
`404`	未知、已删除或无法访问的素材/组/审核任务	使用返回给同一账户的 ID
`400` / `409`	素材尚未就绪、素材上下文不兼容或组非空	完成审核、使用兼容的组或移除组成员
`413`	图像上传超过文件/正文大小限制	减小文件大小或使用您自己的公开存储
`429`	达到请求速率限制	减少并发并使用退避策略重试查询
`502` / `503`	审核服务不可用或响应无效	首先重试查询；保留现有的任务和素材 ID

审核任务可能返回 HTTP 200 但状态为 data.status: "failed"；请检查任务状态及其安全错误消息，而不要仅依赖 HTTP 状态码。阅读返回的解释，并保留公开的审核任务 ID 以供支持。

媒体库常见问题解答

审核需要多长时间？ 每隔 5–10 秒轮询一次。持续时间因素材和服务负载而异；视频和真实人物审核可能比图像审核耗时更长。提交被接受并不等于批准。
如果审核失败但没有解释怎么办？ 检查审核任务和 failed_assets；保留其公开的任务/资产 ID 以供支持。在提交纠正后的素材之前，请检查格式和 URL 可访问性。查询不会重新启动失败的审核。
我必须为 2.0 和 2.5 重新上传吗？ 当您的密钥有权访问目标模型且素材满足该模型的限制时，已批准的 APIMaster 资产可以重复使用。跨平台的 ID 无法重复使用。
批次可以部分成功吗？ 可以。请仅重复使用状态为 usable_assets 的 Active；单独纠正被拒绝的项目。
同步素材错误意味着什么？ HTTP 400 拒绝无效输入。invalid_asset_material 可能标识 assets[0]、assets[1] 等；索引从零开始。在重新提交之前，请纠正指定项目的格式或时长。

{
  "error": {
    "message": "invalid_asset_material: assets[0] video duration must be from 2 to 30 seconds",
    "type": "media_library_error"
  }
}

样片模式：从480p草稿到1080p最终版

样片是一次正常的计费生成，包含draft: true。它在样片任务创建时间起的7天内对升级有效。每次升级都是一个独立的任务和费用；同一个未过期的成功样片可以被多次升级。

步骤 1：生成并轮询样片

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5","prompt":"A colorful abstract pattern gently moves.","draft":true,"duration":5,"return_last_frame":true}'

省略的分辨率将变为480p。发送720p或1080p与draft: true会返回400。通过/v1/videos/{task_id}或/v1/video/generations/{task_id}轮询返回的公共ID，并在升级前等待成功。其他生成参数和媒体限制正常适用。

步骤 2：从样片创建最终视频

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5","draft_task_id":"task_preview_example","output_format":"mp4","return_last_frame":true,"watermark":false}'

响应包含一个新的公共任务ID。省略的分辨率将变为1080p；所有其他分辨率值将返回400。请使用属于样片账户的API密钥。如果任务缺失、不属于本账户、非样片任务、未完成、已过期或模型不同，将同步拒绝并返回400，不会创建任务或收取预留费用。

如果样片暂时不可用，请稍后使用相同的draft_task_id重试。不要用其他平台的ID替换它。样片升级不能被重新路由到不同的生成上下文。

继承字段和允许的更改

请不要重新发送继承的字段，即使它们的值相同、false、0或null：

prompt, image_urls, image_with_roles, video_urls, audio_urls, duration, size, aspect_ratio, ratio, seed, generate_audio, audio, omni_reference_task_type, generation_type, camerafixed, web_search, tools.

同样的限制也适用于APIMaster的输入别名和旧版包装器：seconds, images, image, input_reference, first_frame_image, last_frame_image, video_list, negative_prompt, metadata。

除了model、draft_task_id和固定的1080p分辨率外，可调整的字段仅为output_format、return_last_frame和watermark。省略的值将分别使用mp4、false和false。最后一帧和水印标志不会从样片继承。请勿将draft_task_id与draft: true结合使用。样片创建和升级都会拒绝service_tier。

样片和最终视频的预留费用

样片时长	样片预留费用	最终视频预留费用
显式指定`4`–`30`秒	按指定时长以480p计费；参考视频工作正常包含在内	相同时长按1080p层级计费，不含视频输入
`-1`，包括在`edit`中省略时长	最多30秒	最多30秒按1080p计费，不含视频输入
其他省略时长情况	5秒按480p计费	5秒按1080p计费，不含视频输入

样片工作遵循普通的480p定价；参考视频时长正常计入，合并计费时长上限为30秒。最终视频工作使用1080p层级且不含视频输入，排除样片的参考视频时长。成功后会结算实际使用量并退还或收取差额；失败则会全额退还预留费用。定价来自您的模型卡片和钱包记录。

可选的文本和图像审核

nsfw_check默认为false。在Seedance 2.0和2.5上，将其设置为true可启用对prompt、negative_prompt和图像输入的提交前检查：image_urls、image_with_roles[].url、首/尾帧别名以及图像类型的库资源。生成URL不接受base64图像；请先上传图像文件。视频、音频以及视频/音频类型的资源不在此文本/图像检查范围内。

检测到违规将返回HTTP 400，并遵循以下响应结构；不会创建视频任务或生成预留费用：

{
  "code": "nsfw_content_detected",
  "message": "Your request was rejected by content moderation (`nsfw_check` is enabled). Flagged categories: sexual.",
  "data": null
}

此可选检查不收取生成费用，也不是绝对的内容安全保证。检查失败或未检测到违规，并不代表后续生成会被批准。无论此标志如何，请仅使用已授权且合规的内容。

查询状态与下载

同一任务可通过任一查询格式读取。请以适中频率轮询，例如每 5–10 秒一次，并在达到终止状态时停止。生成时间取决于工作负载、片段时长、分辨率及参考内容；请勿因任务处理缓慢而创建重复任务。

curl --fail-with-body -sS "https://apimaster.ai/v1/video/generations/task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

完成响应

兼容格式，GET /v1/video/generations/{task_id}：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_example",
    "status": "succeeded",
    "url": "https://apimaster.ai/v1/videos/task_example/content",
    "format": "mp4",
    "error": null,
    "metadata": null,
    "usage": {"completion_tokens": 108900},
    "actual_time": 160,
    "last_frame_url": "https://apimaster.ai/v1/videos/task_example/last-frame"
  }
}

OpenAI 风格格式，GET /v1/videos/{task_id}：

{
  "id": "task_example",
  "object": "video",
  "model": "seedance-2.5",
  "status": "completed",
  "progress": "100%",
  "url": "https://apimaster.ai/v1/videos/task_example/content",
  "usage": {"completion_tokens": 108900},
  "actual_time": 160,
  "last_frame_url": "https://apimaster.ai/v1/videos/task_example/last-frame"
}

含义	兼容格式位置	OpenAI 风格格式位置
公开任务 ID	`data.task_id`	`id`
等待中	`data.status: queued`	`status: queued`
生成中	`data.status: processing`	`status: in_progress`
成功	`data.status: succeeded`	`status: completed`
失败	`data.status: failed`	`status: failed`
视频下载 URL	`data.url`	`url`
完成令牌数	`data.usage.completion_tokens`	`usage.completion_tokens`
耗时秒数	`data.actual_time`	`actual_time`
最后一帧图像 URL	`data.last_frame_url`	`last_frame_url`
失败说明	`data.error.message`	`error.message`
输出容器	`data.format`	保存时使用请求的 `output_format`
旧版元数据	`data.metadata`，当前为 `null`	未使用

actual_time 是完成时间减去提交时间，单位为秒，包含等待时间；它不是视频的时长。usage.completion_tokens 是记录的生成统计量，与消费日志中的令牌计数匹配。APIMaster 的货币结算使用视频时长及其适用层级；令牌统计量不是货币价格公式。响应中不包含金额字段；请使用您钱包的消费记录进行结算。

使用量可能在刚完成时缺失；请稍后再次查询。last_frame_url 仅在成功且您请求了 return_last_frame: true 且有最后一帧可用时返回。当未请求、仍在处理中或失败时，该字段会被省略，而不是设置为 null。样片升级使用其自身的标志。

失败响应

失败的任务仍可通过 HTTP 200 查询。OpenAI 风格响应可能包含：

{
  "id": "task_example",
  "object": "video",
  "model": "seedance-2.5",
  "status": "failed",
  "progress": "100%",
  "error": {"code": "task_failed", "message": "[upstream_error] Unsupported media format."}
}

兼容格式将说明置于 data.error.message。失败的任务没有视频或最后一帧下载。请保留公开任务 ID 和说明以寻求支持。

下载视频和最后一帧

下载任一 URL 时发送 Authorization: Bearer YOUR_API_KEY。请使用属于任务账户的密钥。视频内容根据请求为 MP4 或 MOV；保存 MOV 时使用 .mov 扩展名。最后一帧是图像，因此请根据返回的内容类型选择其扩展名。

curl --fail-with-body -L "https://apimaster.ai/v1/videos/task_example/last-frame" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o last-frame.jpg

请及时下载并保存成功的文件。可用性并非永久；保留任务 ID 并不保证其输出文件保持可下载状态。如果文件不再可用，下载将返回 HTTP 410 及 error.message: "Media has expired or is no longer available"。不可用或未请求的最后一帧返回 HTTP 404。缺少下载认证返回 HTTP 401。

Python：提交、轮询和保存

import os
import time
import requests

base = "https://apimaster.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['APIMASTER_API_KEY']}"}
payload = {
    "model": "seedance-2.5",
    "prompt": "A lighthouse above a calm sea, slow camera push-in, no text.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "generate_audio": True,
    "watermark": False,
    "return_last_frame": True,
}
response = requests.post(f"{base}/videos/generations", headers=headers,
                         json=payload, timeout=60)
response.raise_for_status()
created = response.json()
data = created.get("data")
if isinstance(data, list) and data:
    task_id = data[0].get("task_id")
else:
    item = data if isinstance(data, dict) else created
    task_id = item.get("task_id") or item.get("id")
if not task_id:
    raise RuntimeError("No task ID returned; inspect the submission response.")
print("task_id:", task_id)

# Example client timeout, not a promised generation deadline.
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    response = requests.get(f"{base}/videos/{task_id}", headers=headers, timeout=60)
    response.raise_for_status()
    task = response.json()
    state = task.get("status")
    if state == "failed":
        error = task.get("error") or {}
        raise RuntimeError(error.get("message", "Video generation failed."))
    if state == "completed":
        result = requests.get(f"{base}/videos/{task_id}/content", headers=headers,
                              timeout=120, stream=True)
        result.raise_for_status()
        with open("output.mp4", "wb") as output:
            for chunk in result.iter_content(1024 * 1024):
                if chunk:
                    output.write(chunk)
        print("Saved output.mp4")
        print("usage:", task.get("usage"), "actual_time:", task.get("actual_time"))
        if task.get("last_frame_url"):
            frame = requests.get(task["last_frame_url"], headers=headers, timeout=60)
            frame.raise_for_status()
            with open("last-frame.jpg", "wb") as image:
                image.write(frame.content)
            print("Saved last-frame.jpg")
        break
    time.sleep(5)
else:
    raise TimeoutError(f"Task {task_id} is still pending; keep this ID and query it later.")

提交期间连接超时会使结果不确定：请保留任何返回的任务 ID，并在重新提交前检查您的任务历史记录。轮询超时不会取消任务。当您不确定计费提交是否被接受时，请避免自动重试。

计费、预留和退款

计费使用时长（秒），并取决于分辨率、输入媒体类型以及您账户的适用价格。在当前 Seedance 2.5 配置中，生成音频与静音音频不选择单独的价格层级。请在提交前查看模型卡片和钱包的视频/媒体定价；本页面不硬编码变化的价格。

提交会预留预估金额。省略普通时长会预留 5 秒。对于 duration: -1，预估使用 30 秒的最大值，因此即使结果更短也需要足够的余额。
使用参考视频时，可计费工作可能包括参考视频时长加上生成视频时长。5 秒的输出不一定仅按 5 秒的工作计费。
成功生成后，最终测量的使用量可能会产生额外费用或退还差额。请使用最终钱包记录确认结算。
失败的任务会退还生成预留金额。失败的任务可能仍会显示其原始消费记录以及匹配的退款；检查净费用时请将两者都计入。
更正无效请求需要重新提交。现有的失败任务 ID 无法通过继续轮询来重新启动。

JavaScript、Go、Java 和 PHP 示例

这些示例提交一个文生视频任务并打印其响应。保存 data[0].task_id，然后使用上述查询/下载流程。请从服务器环境中读取您的密钥。

JavaScript (Node.js)

const response = await fetch("https://apimaster.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIMASTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.5", prompt: "A lighthouse at sunrise, slow camera push-in.",
    duration: 5, resolution: "720p", aspect_ratio: "adaptive",
    generate_audio: true, watermark: false, output_format: "mp4",
  }),
});
const body = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`);
console.log(JSON.parse(body));

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func main() {
    payload, err := json.Marshal(map[string]any{
        "model": "seedance-2.5", "prompt": "A lighthouse at sunrise, slow camera push-in.",
        "duration": 5, "resolution": "720p", "aspect_ratio": "adaptive",
        "generate_audio": true, "watermark": false, "output_format": "mp4",
    })
    if err != nil { panic(err) }
    req, err := http.NewRequest("POST", "https://apimaster.ai/v1/videos/generations", bytes.NewReader(payload))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + os.Getenv("APIMASTER_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    response, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
    if err != nil { panic(err) }
    defer response.Body.Close()
    body, err := io.ReadAll(response.Body)
    if err != nil { panic(err) }
    if response.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, body)) }
    fmt.Println(string(body))
}

Java (JDK 11+)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class SeedanceExample {
    public static void main(String[] args) throws Exception {
        String json = "{\"model\":\"seedance-2.5\",\"prompt\":\"A lighthouse at sunrise.\","
            + "\"duration\":5,\"resolution\":\"720p\",\"aspect_ratio\":\"adaptive\","
            + "\"generate_audio\":true,\"watermark\":false,\"output_format\":\"mp4\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://apimaster.ai/v1/videos/generations"))
            .timeout(Duration.ofSeconds(60))
            .header("Authorization", "Bearer " + System.getenv("APIMASTER_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json)).build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException("HTTP " + response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

PHP

<?php
$payload = [
    'model' => 'seedance-2.5', 'prompt' => 'A lighthouse at sunrise, slow camera push-in.',
    'duration' => 5, 'resolution' => '720p', 'aspect_ratio' => 'adaptive',
    'generate_audio' => true, 'watermark' => false, 'output_format' => 'mp4',
];
$handle = curl_init('https://apimaster.ai/v1/videos/generations');
curl_setopt_array($handle, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('APIMASTER_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
]);
$body = curl_exec($handle);
if ($body === false) { throw new RuntimeException(curl_error($handle)); }
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);
if ($status >= 400) { throw new RuntimeException("HTTP $status: $body"); }
print_r(json_decode($body, true, 512, JSON_THROW_ON_ERROR));

从其他 Seedance 2.5 集成迁移

将您的基础 URL 设置为 https://apimaster.ai/v1 并提交到 POST /v1/videos/generations。使用本页的 APIMaster 字段定义和默认值；迁移现有集成时，请保持时长、宽高比和音频参数明确。

视频请使用 GET /v1/video/generations/{task_id} 或 GET /v1/videos/{task_id}。/v1/tasks/{id} 也处理媒体审核任务；对于 APIMaster 视频 ID，它会返回兼容的视频响应。建议优先使用两个专用的视频端点，以保持视频处理和审核处理的清晰性。

其他集成	APIMaster 兼容性	APIMaster OpenAI 风格
`pending`	`data.status: queued`	`status: queued`
`processing`	`data.status: processing`	`status: in_progress`
`completed`	`data.status: succeeded`	`status: completed`
`failed`	`data.status: failed`	`status: failed`
`data.result.videos[].url[0]`	`data.url`	`url`
最后一帧结果	`data.last_frame_url`	`last_frame_url`
生成用量	`data.usage.completion_tokens`	`usage.completion_tokens`
耗时	`data.actual_time`	`actual_time`

使用您账户的 Bearer 密钥下载视频和最后一帧 URL。APIMaster 不返回金额字段；请使用钱包消费记录。任务 ID、asset:// ID 和 draft_task_id 是 APIMaster 特有的，不能跨平台复制。请在 APIMaster 中重新提交并审核您的素材。请及时保存输出结果，不要假设其他服务的保留期适用。

Seedance 2.0 与 2.5 的差异

更换模型时，请使用特定模型的文档。限制条件不能从模型的版本号推断。

能力	Seedance 2.0	Seedance 2.5
公开模型	`seedance-2.0`	`seedance-2.5`
默认时长	`4` 秒	`5` 秒；编辑任务默认为 `-1`
生成时长	参考 2.0 模型文档中记录的模式	`4`–`30` 秒，或 `-1`
分辨率	`480p`, `720p`, `1080p`, `4K`	`480p`, `720p`, `1080p`
图像/视频/音频数量及总时长	遵循 2.0 模型的媒体限制	`30` 张图像，`10` 个视频总计最多 `30` 秒，`10` 个音频片段总计最多 `30` 秒
纯音频参考	遵循 2.0 模型文档中记录的模式	支持
输出格式	`mp4`, `mov`	`mp4`, `mov`
水印	遵循 2.0 模型文档中记录的选项	默认 `false`
样片与升级	此工作流不支持	480p 样片 → 1080p 最终版；有效期为 7 天
媒体库视频摄入默认值	单个视频限制 `15` 秒	明确选择时，单个视频限制 `30` 秒
媒体库音频摄入	`2`–`15` 秒	`2`–`15` 秒
已批准的 `asset://` 参考	同一账户已批准的资产，受模型权限和限制约束	相同规则；不接受跨平台 ID

错误响应结构

提交验证失败返回 HTTP 400 及一个 error 对象：

{
  "error": {
    "message": "draft resolution must be 480p",
    "type": "invalid_request_error"
  }
}

某些请求拒绝路径使用 code / message / data 封装，包括审核和无效媒体输入：

{
  "code": "invalid_request",
  "message": "Invalid format for image_with_roles[0].url. Only http/https URLs or asset:// private asset URLs are supported.",
  "data": null
}

下载认证缺失返回 HTTP 401：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: request_example)",
    "type": "new_api_error"
  }
}

请处理两种错误封装：存在时读取 error.message，否则读取 message。不要依赖单一的错误代码字段来检测失败。视频查询返回 HTTP 200 时，任务仍可能已失败。

提交消息	含义
`unsupported seedance-2.5 resolution "4k"`	请使用支持的分辨率
`seedance-2.5 duration must be -1 or an integer from 4 to 30`	时长超出允许范围
`first/last frame aspect_ratio must be adaptive`	纯图像帧任务使用固定宽高比
`edit requires at least one video_urls entry`	缺少编辑源
`extend requires at least one video_urls entry`	缺少扩展源
`edit duration must be -1`	明确的编辑时长不是自动的
`draft resolution must be 480p`	样片分辨率无效
`draft_task_id resolution must be 1080p`	升级分辨率无效
`draft and draft_task_id cannot be used together`	样片字段互斥
`service_tier is not supported for draft tasks`	为样片或升级提供了调度字段
`draft_task_id was not found in your account`	缺少或无法访问样片 ID
`draft_task_id is not a draft task`	将普通任务作为样片提供
`draft_task_id has not completed successfully`	样片待处理或失败
`draft_task_id has expired; drafts are valid for 7 days`	样片超过 7 天
`draft_task_id model does not match`	源模型不同
`Draft is temporarily unavailable; retry with the same draft_task_id later`	请稍后重试，不要更改样片 ID
`prompt must not be supplied with draft_task_id`	重新提交了继承的字段；等效错误会列出其他禁止字段

故障排除

区分同步提交错误与异步失败：HTTP 200 响应附带任务 ID 仅表示请求已被接受。任务后续可能变为 failed。

错误或现象	可能原因	应对措施
无效的 `ratio` / 首帧宽高比必须与图像一致	在帧任务中使用了固定宽高比	设置 `aspect_ratio: "adaptive"`；若需特定宽高比，请对首张图像进行裁剪/填充
无效的 `content[1]` / 无效的图像格式	URL 返回 HTML、链接已过期，或图像不受支持/无法解码	打开无需登录的直接文件 URL；转换为 JPEG/PNG 格式；验证尺寸并使用新任务重试
图像边长或宽高比超出范围	图像尺寸过小/过大或过宽/过高	每条边应在 `300`–`6000` 像素之间；宽高比应在 `0.4`–`2.5` 之间
`InvalidParameter.TaskTypeConstraint`	编辑/扩展/帧设置违反了其任务特定的约束条件	使用 `adaptive`；编辑任务还需满足 `duration: -1`
`InvalidParameter.TaskTypeMismatch`	声明的任务类型与提示词意图不符	重写提示词并选择匹配的 `omni_reference_task_type`
内容被拒绝 / 审核阻止	输入内容或提示词违反了适用的内容规则	使用合规的媒体素材并修改提示词；请勿原封不动地重试已被拒绝的相同内容
HTTP `400`	缺少提示词、不支持的分辨率/时长、无效的媒体文件或冲突的别名	在重新提交前，根据本页内容检查请求
HTTP `401` / `403`	无效的密钥或授权不足	使用来自任务所属账户的有效的 APIMaster 密钥
余额不足，包括 HTTP `402` 或余额/配额错误	可用钱包/密钥额度不足以覆盖预扣费用	检查钱包余额、密钥额度以及自动时长计算的预扣费用
HTTP `429`	速率或并发限制	退避重试；轮询时复用现有的任务 ID
HTTP `500` / `502` / 网络超时	临时服务或连接故障	采用退避策略重试读取操作；在重试提交前检查任务历史记录
任务已完成但下载失败	下载过早、缺少身份验证或输出不可用	再次查询任务状态，发送同一账户的密钥，并保留任务 ID 以备联系支持

用户任务日志和使用日志详情会显示安全的失败说明。联系支持时，请提供公开任务 ID、大致提交时间、模型、分辨率、时长以及相关错误信息。切勿发送您的 API 密钥或授权头信息。

相关链接：视频 API 概述 · Seedance 2.0