视频生成任务

Swarmix 异步视频任务协议。平台负责鉴权、路由、余额预留、轮询恢复和完成后的统一结算。

POST/v1/videos

异步结算

创建任务只返回平台任务 ID。请轮询 GET /v1/videos/{task_id}；按受理时价格快照预留余额，任务完成后按实际交付和平台计量合约结算；无法确认用量或费用时进入复核。

素材输入

新请求使用上游可读取的在线 URL，或所选模型明确支持的内联 Base64。原始 Base64、data URI 等格式及大小限制须遵循该模型协议；不能据此推断其他厂商也支持。平台不提供素材上传或长期归档，不接收平台文件 ID。右侧为 H3 的 URL 参考图样例；其他模型请使用其已声明的输入字段。

内联 Base64 不建立独立文件台账，但完整请求快照会持久化于任务记录，用于恢复和相同幂等请求重放。这不等于提供素材长期归档。

创建请求

字段	类型	必填	说明
`model`	string	是	已上架且分组为 video 的模型 ID。
`prompt`	string	二选一	文本提示词；也可以改用 content 数组。
`content`	array	二选一	文本、图片或视频输入内容；具体类型以模型能力为准。
`seconds`	integer		请求视频秒数；可选值及原生时长字段以模型和上游为准。
`resolution`	string		模型已配置售价的分辨率档位，例如 480P、720P。
`reference_images`	array		H3 使用包含 url 的对象数组；其他模型的参考输入按其协议填写。
`ratio`	string		例如 16:9、9:16 或 1:1。
`generate_audio`	boolean		是否同时生成音轨。
`watermark`	boolean		是否添加水印。

查询与取消

GET/v1/videos/{task_id}

只允许创建该任务的客户查询。完成响应保留上游结果字段，并把 ID 统一替换为平台任务 ID。

DELETE/v1/videos/{task_id}

取消能力以所选模型方案为准，不支持的方案会拒绝取消。仅在上游确认结果后处理预留余额。

完成任务返回上游实际结果。供应商 URL 的权限和有效期遵循上游，平台不自动下载或长期归档产物。

计费规则

视频按平台分辨率档位和计费整秒结算，具体单价见已上架模型价格。每个任务固定使用受理时的价格版本，后续调价不会改写在途任务。