Seedance 2.5 Flash API 教程:异步任务、限制与错误

推理时代阅读约 8 分钟
Seedance 2.5 Flash API 教程:异步任务、限制与错误

通过 doubao-seedance-2-5-flash 调用 POST /ai/v1/videos,轮询任务,然后下载结果。当前 AIHubMix schema 支持 480p/720p 输出、4–30 秒视频,以及最多 10 个图像、5 个视频和 5 个音频参考。使用旧版 /v1/videos 的客户端需要同时更改端点和模型 ID。

本指南于 2026 年 11 月 16 日核验。上面的短 ID 和 doubao-seedance-2-5-flash-261115 均返回了模型 schema,并对 1080p 请求返回 400 schema_violation。另一次创建 4 秒 480p 视频的尝试返回 402 insufficient_quota;未生成视频。以下工作流基于当前 schema 和文档,但本次核验未能端到端验证成功生成、延迟、MOV 输出和编辑功能。

前置条件与 schema 发现

Seedance 2.5 Flash 模型页面列出了本指南中使用的短 ID。提交任务前:

  1. 在 AIHubMix 控制台中启用异步媒体任务。文档说明,未启用此功能的账户会收到错误 403 async_not_enabled。
  2. 确保 API 密钥有访问权限,且账户余额充足。实时核验返回了 402 insufficient_quota,并附带消息 Your account has insufficient quota. Add credits and try again.
  3. 在 shell 中导出 AIHUBMIX_API_KEY。请勿将密钥放入源文件或浏览器代码中。
  4. 获取当前 schema;发现 schema 的请求无需身份验证。
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

11 月 16 日的 schema 仅为 Flash 列出了 /ai/v1/videos。它接受 resolution 值 480p 和 720p(默认值为 720p),duration 可设为 4 到 30 之间的整数,或设为 -1 由模型选择时长。需要可预测的预算时,请指定明确的时长。

创建、轮询与下载

AIHubMix 视频生成 API将创建任务、查询状态和下载分开处理。创建请求返回 HTTP 成功,表示任务已被接受;只有 status: "completed" 才能确认任务完成。查询请求可能返回 HTTP 200,但任务本身的状态却是 status: "failed"。

提交文生视频任务

此示例请求生成一个 10 秒、720p、16:9、带音频的产品视频。它仅使用文本,因此无需依赖托管在其他地方的参考图像。

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

收到任务 id 后立即保存。每隔 15 秒轮询一次 GET /ai/v1/videos/{id},直到状态变为 completed、failed 或 cancelled。活跃任务的轮询请使用视频详情路由:它会刷新供应商状态,而统一任务列表不能替代这项检查。任务完成后,通过 GET /ai/v1/videos/{id}/content 下载,并使用相同的 Bearer 标头。

完整的 Python 客户端

使用 python3 -m pip install requests 安装依赖,将以下内容保存为 seedance_flash.py,然后在已设置 API 密钥的 shell 中运行 python3 seedance_flash.py。此示例实现了文档所述的工作流;由于上述配额错误,未能完成生成测试。

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

20 分钟的期限是客户端等待时限,不代表服务器会取消任务,也不保证生成耗时。若轮询或下载失败,请保留任务 ID 并重试相应操作。如果超时或供应商状态不确定,请勿自动再次提交生成请求。

按照 BytePlus 官方在线推理费率,Flash 在不含视频输入时的费用为每百万 token $7.00,在 480p/720p 下含视频输入时为 $4.30。对于纯文本示例,估算为 10 × 1280 × 720 × 24 / 1024 = 216,000 个 token:使用 Flash 为 $1.51,使用旗舰版 2.5 的 720p 则为 $2.31。这些是根据 BytePlus 费率计算出的估算值,并非实测的 AIHubMix 账单。

参考素材与 Webhook

要使用媒体素材引导视频,请添加 input_references 条目,其中包含 type(image_url、video_url 或 audio_url)以及指向可访问媒体的 url。schema 对这些类型的数量上限为 10 / 5 / 5。如需控制首尾帧,请改用 frame_images;每个条目包含 frame_type 和嵌套字段 image_url.url。请勿同时传入非空的 frame_images 和 input_references。帧工作流要求设置 aspect_ratio: "adaptive",并且指定尾帧时必须同时指定首帧。

异步任务文档介绍了通过 webhook_url 使用 HTTPS 回调。Flash 当前的 schema 包含该字段,但没有 webhook_events_filter,并设置了 additionalProperties: false,因此遵循此模型 schema 时请省略该筛选字段。文档说明,默认会发送 completed、failed 和 cancelled 事件。投递采用至少一次机制,最多尝试六次,重试间隔为 1、4、16、64 和 256 秒;请根据 event_id 去重。任务级回调没有单独的签名密钥,因此请查询任务以确认最终状态。文档还介绍了适用于需要签名验证的应用的账户级订阅。

错误:实测结果与文档说明

1080p:实测的 schema 拒绝

两个 AIHubMix 模型 ID 对带有 resolution: "1080p" 的 4 秒请求均返回了 HTTP 400。返回的错误字段如下:

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

响应还包含一个请求跟踪 ID,此处省略。这是观察到的网关拒绝,并非推断出的上游错误。它既不能证明生成成功,也不能作为速度测量结果。

以下其他限制来自当前 Flash schema;本次实时核验未单独提交这些无效组合。

输入问题 Schema 要求 解决方法
4K 输出 480p 或 720p 降低分辨率
参考素材过多 10 个图像 / 5 个视频 / 5 个音频 减少素材数量
两个参考数组 只能有一个非空数组 选择一种工作流
仅指定尾帧 还必须提供首帧 同时提供两帧
带帧时使用固定比例 自适应比例 使用自适应比例

真人参考素材:使用已验证的素材

AIHubMix 文档说明,当 Doubao 因真人图像触发特定隐私拒绝时,会返回 doubao_real_person_required。本次核验未触发此错误。文档中的错误消息为:

此请求使用了真人图像。请完成真人验证并使用有效的素材引用。请参阅 https://docs.aihubmix.com/cn/api/doubao-real-person-assets。

请遵循 Doubao 真人素材指南:通过 /ai/v1/asset-groups 创建素材组,通过 /ai/v1/asset-groups/{id}/verification-sessions 创建验证会话,让图中人物完成网页验证,通过 /ai/v1/asset-groups/{id}/assets 注册素材,并等待其状态变为有效。在生成参考中使用 asset://<ASSET_ID>。原始照片 URL 不能替代同意及素材注册流程。

配额、请求大小与下载

实测的 402 insufficient_quota 阻止了有效分辨率请求进入生成阶段。请先充值再重试;更改正确的提示词或模型 ID 无法解决此响应。403 async_not_enabled 则是另一种文档中说明的前置条件错误,需要在控制台中启用相关功能。

AIHubMix 文档说明请求正文大小上限为 32 MiB,超过限制会返回 413 request_too_large。使用公共 URL 可避免 Base64 膨胀请求正文,但引用的媒体仍须符合模型自身的大小和格式限制。

视频完成后请尽快保存。AIHubMix 现有的 Seedance 2.5 集成指南提醒,输出 URL 的有效期很短,约为 30 分钟;本次未核实 Flash 的固定保留期限。视频 API 可能返回 expires_at: null,但这并不意味着内容会被无限期保存。文档列出的下载错误包括 410 artifact_expired 和 429 too_many_downloads。如果下载遇到临时服务错误,请针对现有任务重试下载,而不是重新生成视频。

即使请求有效,也可能遇到的迁移陷阱

Volcengine Seedance 2.5 指南明确将 Flash 列入该系列,并确认支持 MOV 输出、编辑和延长视频;但这些供应商提供的功能必须与通过网关实际验证的功能区分开来。

  • MOV 和编辑字段已开放,但本次未进行端到端测试。Flash 的 schema 接受 extra.output_format: "mp4" 或 "mov",以及 extra.omni_reference_task_type 的值 auto、reference、edit 和 extend。如果明确发送任务类型字段,schema 要求 input_references 非空。edit 还需要视频参考、自适应比例和 duration: -1;extend 则需要视频参考和自适应比例。
  • 明确指定任务类型,不代表模型一定会认可。Ark 文档说明,如果推断出的任务类型与参数冲突,会产生异步错误 InvalidParameter.TaskTypeConstraint;如果推断出的类型与明确请求的类型不同,则会产生 InvalidParameter.TaskTypeMismatch。本次未实测 AIHubMix 的具体映射;请检查返回任务中的 error,而不要假定网关一定会返回某个错误代码。
  • Flash 不支持 Draft 升级。供应商将两阶段 480p Draft 到最终版工作流限制为旗舰版 2.5。Flash 不支持此功能,当前 AIHubMix 对两种模型的 schema 均未包含 draft 和 draft_task。
  • 视频输入会改变计费方式。官方计费会根据输入和输出视频时长计算,并且可能设有最低 token 数。$4.30/M 的费率并不意味着带视频引导的任务一定比其他条件相同的纯文本任务更便宜。请查看实际用量和账户账单,不要只依赖公式估算。
  • 有些描述仍不够明确。Flash 的网关 schema 暴露了 extra.priority、extra.safety_identifier 和 extra.tools,但其描述仍标注“仅适用于 2.0 系列”。Ark 的创建任务参考文档也将 priority 和 tools 列为 2.5 系列可用参数。仅凭 schema 暴露这些字段,并不能验证它们在 AIHubMix 上的实际效果;投入生产使用前,请先验证相应功能。

上线前检查清单

  • 启用异步任务,并检查账户余额。
  • 使用简短版 Flash ID,通过 /ai/v1/videos 调用,并获取当前 schema。
  • 选择 480p 或 720p,并明确指定 4–30 秒范围内的时长。
  • 参考素材数量限制为 10 张图片、5 段视频和 5 段音频。
  • 将帧参考与其他参考素材分开,并为帧参考使用自适应比例。
  • 涉及真实人物肖像的参考素材,请通过已验证且处于启用状态的素材调用。
  • 保存任务 ID,检查任务的终态状态,并及时下载结果。
  • 如果生成状态不确定,请针对现有任务重试查询或下载。

常见问题

Flash 可以使用兼容 OpenAI 的 /v1/videos 路径吗?
当前 Flash schema 仅列出 /ai/v1/videos。本指南中的示例请使用该原生异步路径。

为什么使用 aspect_ratio: "16:9" 的帧图片请求会失败?
Flash 的 schema 要求:提供非空的 frame_images 时,必须设置 aspect_ratio: "adaptive"。指定末帧时也必须提供首帧;帧参考不能与非空的 input_references 同时使用。

如何解决 doubao_real_person_required?
请按照个人验证和素材注册流程操作,等待素材变为启用状态,然后通过素材 URI 引用它。该错误代码表示 Doubao 特有的隐私拦截;本次检查未能复现。

为什么一段较短的参考视频费用会高于公式估算?
如果输入包含视频,供应商的计费规则可能会设置最低 token 消耗。公式仅为估算;请查看实际消耗和账户计费记录,确认扣费金额。

生成失败或审核拒绝会产生费用吗?
BytePlus 和 Volcengine 的官方计费规则规定,仅对成功生成计费;生成失败和内容审核拒绝不收费。AIHubMix 的错误文档建议查看计费记录,以确认历史扣费;本次未测得任何成功或失败生成的账单。

Flash 结果可以下载多长时间?
完成后请立即下载。现有的 Seedance 2.5 指南提示,结果 URL 的有效期约为 30 分钟,但 Flash 的确切保留时长尚未验证;过期时间字段为 null 并不表示结果会永久保留。

AIHubMix 支持 MOV 输出以及编辑/扩展功能吗?
当前 Flash schema 在 extra 下提供了相应字段,供应商文档也说明支持这些功能。由于创建测试因配额不足而中止,尚未验证这些功能通过 AIHubMix 端到端使用时的实际表现。

继续阅读:Seedance 2.5 Flash 系列

资料来源

文档和 schema 于 2026 年 11 月 16 日核查;验证响应记录于 08:26 UTC。价格为 BytePlus 官方估算,并非实测的网关扣费。

一个网关接入多家 AI 服务商, 为生产环境而生。

访问推理时代官网