视频生成任务

视频生成使用异步任务接口：创建任务后返回 video_task_*，客户端通过查询接口轮询状态和结果。接口使用 API Key 鉴权，不使用控制台 JWT。

Base URL: https://llm.xiaoyue9527.xyz/v1
Authorization: Bearer sk-gtw-REPLACE_ME
Content-Type: application/json

接口列表

接口	方法	用途
/v1/video/generations/tasks	POST	创建视频生成任务
/v1/video/generations/tasks/{task_id}	GET	查询单个任务
/v1/video/generations/tasks	GET	查询任务列表
/v1/video/generations/tasks/{task_id}/cancel	POST	取消任务
/v1/video/generations/tasks/{task_id}	DELETE	取消任务

兼容短路径：/v1/video/tasks、/v1/video/tasks/{task_id} 和 /v1/video/tasks/{task_id}/cancel。

火山 Ark v3 基础任务协议兼容入口

已经使用火山 Ark 视频任务 SDK 的客户端可以继续使用 SDK，并替换 SDK 的 base_url 与 API Key。兼容范围是创建、查询、列表和删除任务的路径、鉴权与基础 wire shape；请求参数仍必须落在平台模型与某一条实际渠道的完整能力交集内：

base_url = https://llm.xiaoyue9527.xyz/api/v3
api_key  = sk-gtw-REPLACE_ME

接口	方法	用途
/api/v3/contents/generations/tasks	POST	创建任务
/api/v3/contents/generations/tasks/{task_id}	GET	查询任务
/api/v3/contents/generations/tasks	GET	查询最近 7 天任务列表
/api/v3/contents/generations/tasks/{task_id}	DELETE	按状态取消或删除任务

模型既可以填写平台模型 ID，也可以填写任一已启用视频渠道为该平台模型精确配置的 官方模型 ID；官方 Ark 与兼容供应商渠道都参与这一无歧义映射。 创建响应、查询状态、列表分页和 DELETE 语义按火山任务协议映射，平台任务 ID 仍为 video_task_*，用它继续查询即可。

兼容入口的 Idempotency-Key 可选：生产调用仍建议提供稳定键，以便在网络超时时安全 重试；省略后任务可以创建，但重复请求可能生成并计费多次。平台原生 /v1 接口仍要求 显式幂等键。

这不是火山全部模型、编辑模式和默认值语义的无条件复刻。兼容入口不会扩大供应商能力。 每个请求仍需通过模型权限、平台能力、候选渠道能力、 素材与 credential 绑定、价格、额度和并发检查。特殊供应商只有在支持请求全部参数时 才会成为候选；不支持的参数会在产生上游费用前跳过该渠道，且没有其他完整候选时明确 拒绝，不会被静默丢弃。高级参数是否开放以模型能力上界与实际候选渠道完整能力的交集为准。

当前 Seedance 2.5 请求应显式提供渠道支持的正数时长（通常为 4～30 秒）、比例和 分辨率。火山原生的 duration=-1、依赖具体任务角色的 adaptive、编辑/延长和 部分 role 自动语义尚未纳入本兼容合同；省略参数时平台会按已发布能力合同归一化， 不保证与所有火山原生模型的省略语义相同。调用前请读取供应商 video_profiles，不要 把不同 profile 的字段组合在同一个请求里。

audio_url 是 content[] 中的参考音频条目，不是已承诺透传的顶层请求字段；实际可用 顶层字段以 route profile 的 supported_fields 为准。generate_audio 控制生成结果 是否带音轨，两者互不替代。 省略 generate_audio 时按当前能力合同的默认值处理。显式传 false 只会选择能保证 无音轨结果的渠道，平台不会把它改成 true。

列表参数兼容 filter.model、filter.service_tier、filter.status、重复的 filter.task_ids、page_num 和 page_size，并固定隔离到当前 API Key。DELETE 对排队任务执行取消，运行中任务拒绝删除； 成功、失败和过期任务删除后不再从兼容查询返回，但平台仍保留审计与计费事实。

兼容入口把排队态返回为 queued，把平台内部的运行、取消中和待确认态统一返回为 processing；成功与失败分别为 succeeded、failed。成功响应仅在渠道返回了 经过校验的豆包任务标识（直连 Ark 可由其任务 ID 确认）时附带 doubao-id；后续 查询始终使用平台返回的 id，链式供应商的平台任务号不会被冒充为 doubao-id。

创建任务

平台原生 /v1/video/... 创建入口必须提供幂等键，推荐使用 Idempotency-Key。也可以使用 X-Request-ID 请求头或请求体里的 request_id；优先级依次为 Idempotency-Key、X-Request-ID、 request_id。/api/v3/... 兼容入口允许省略；需要安全重试时仍应显式提供， 并复用同一个键和相同请求体。

curl -X POST https://llm.xiaoyue9527.xyz/v1/video/generations/tasks \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: biz-video-20260707-0001' \
  -d '{
    "model": "seedance-2-0-fast",
    "content": [
      {
        "type": "text",
        "text": "A calm 3 second cinematic shot of a blue glass cube on a clean white desk."
      }
    ],
    "duration": 3,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false
  }'

平台会先规范化 model、content、时长、比例和分辨率，再同时校验平台模型与实际渠道的能力合同。不支持的参数在产生上游费用前返回 400 video_parameter_not_supported；未知字段默认不会透传，渠道明确配置为 omit 的字段会在发往供应商前移除。

调用前可通过 GET /v1/model-catalog/{model} 的 video 字段读取当前支持的任务模式、 输入媒体、分辨率、比例、默认时长、分类素材数量、来源类型、支持字段和 generate_audio 策略。固定供应商的控制台会进一步按该供应商的完整能力 profile 预检，不能把多个不完整 profile 拼成一套并不存在的能力。能力配置不可用时返回 503 video_capability_unavailable，平台不会绕过校验调用供应商。

图片或视频输入可以直接使用 HTTPS URL，也可以先通过视频素材库创建稳定的 llmgw_asset:// URI。素材 URI 会按实际路由供应商转换，平台任务中保留租户隔离的素材版本快照。

视频价格按模型、任务模式、输出分辨率桶、输入是否含视频、计费模式和计费单位匹配。选定实际渠道后，平台会把客户售价、该供应商 credential 的成本价和当前租户折扣写入不可变任务快照，再进行额度预留；价格组合不完整时返回 503 video_pricing_unavailable，不会创建上游任务。任务创建后的改价、停价、折扣或路由变化不影响该任务最终结算。

查询任务

curl 'https://llm.xiaoyue9527.xyz/v1/video/generations/tasks/video_task_xxx?refresh=true' \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME'

非终态任务查询时会同步上游状态；终态任务如需强制再次同步，可传 refresh=true。

成功任务会在 content.video_url 返回视频结果链接：

{
  "id": "video_task_xxx",
  "object": "video.generation.task",
  "created": 1783000000,
  "updated": 1783000010,
  "model": "seedance-2-0-fast",
  "status": "succeeded",
  "prompt": "A calm 3 second cinematic shot of a blue glass cube on a clean white desk.",
  "content": {
    "video_url": "https://example.com/video.mp4"
  },
  "usage": {
    "completion_tokens": 108900,
    "total_tokens": 108900
  },
  "billing": {
    "status": "settled",
    "billing_event_id": "8f3c...",
    "estimated_cost_units": 500000000,
    "user_cost_units": 108900000,
    "promo_credit_used_units": 0,
    "paid_credit_used_units": 0,
    "wallet_charged_units": 108900000
  }
}

字段说明

字段	说明
id	平台视频任务 ID
status	creating / queued / running / cancelling / succeeded / failed / cancelled / expired / unknown
prompt	创建和单任务查询响应中的创作提示词正文；不包含素材 URL 或原始请求对象
prompt_preview	任务列表中的提示词摘要，最多 160 个 Unicode 字符
prompt_truncated	列表摘要是否被截断；未截断时省略
content.video_url	成功后的视频结果链接
usage	上游返回的 usage 原文
billing.status	pending / reserved / settled / not_charged
billing.estimated_cost_units	创建任务时用于额度预占的预估费用，不是最终扣费
billing.user_cost_units	结算后的客户实际费用；存在时应优先用于展示和对账
billing.promo_credit_used_units / billing.paid_credit_used_units / billing.wallet_charged_units	结算后的赠金、付费包、钱包扣费拆分

金额字段使用平台统一高精度单位：1 元 = 100,000,000 units。任务创建时返回的预估费用用于预算预占，终态任务应以 billing.user_cost_units 为准。not_charged 表示终态任务未产生扣费，此时不要把预估值展示为实际费用。

列表和取消

查询列表：

curl 'https://llm.xiaoyue9527.xyz/v1/video/generations/tasks?limit=20&status=succeeded&model=seedance-2-0-fast&scope=api_key' \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME'

列表参数：

参数	默认值	说明
from	当前时间前 24 小时	RFC3339 起始时间
to	当前时间	RFC3339 结束时间；时间窗最长 31 天
status	空	按任务状态过滤
model	空	按模型 ID 过滤
scope	api_key	api_key 仅当前 Key；account 查询当前账号下任务
limit	50	每页数量，最大 100
after	空	使用上一页 next_cursor 继续分页

列表响应包含 object: "list"、data、has_more，还有下一页时会返回 next_cursor：

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "cursor_xxx"
}

列表项只返回有界的 prompt_preview，不会返回 prompt 正文；创建响应和单任务详情返回 完整 prompt。平台优先拼接规范化 content[] 中的文本段，并兼容历史任务的顶层 prompt。图片、视频、音频 URL、工具定义、安全标识和其他原始请求字段不会随响应返回。 历史任务不需要迁移，只要保存的请求中仍有文本提示词即可回显。

取消任务：

curl -X POST https://llm.xiaoyue9527.xyz/v1/video/generations/tasks/video_task_xxx/cancel \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME'

终态任务重复取消会直接返回当前任务。

限制和错误

项	说明
请求体大小	最大 4 MiB
单个字符串字段	最大 2 MiB
内联 data:*;base64 素材	最大 512 KiB；建议改用对象存储 URL
列表时间窗	最大 31 天
活跃任务限制	超限返回 429 video_task_limit_exceeded

常见错误包括 idempotency_key_required、idempotency_conflict、insufficient_quota、budget_exceeded、model_not_found、task_not_found、request_too_large。