视频生成

视频生成采用异步任务模式。所有请求使用本平台令牌鉴权：

生成视频API文档，交给 AI 编程助手即可接入视频生成、结果查询和完成通知。真实令牌和模型值仍需由你提供。

Authorization: Bearer sk-你的令牌

线路 ID

同一个视频模型可能提供多条可用线路。线路 ID 是正整数，用于在创建任务时指定其中一条线路；它不是 model 值，也不是视频任务 ID。

可使用同一个平台令牌查询指定模型当前公开且可用的线路：

curl "https://your-domain.example/api/platform/model-lines?model=video-model-id" \-H "Authorization: Bearer sk-你的令牌"

响应中 data.items[].id 就是创建视频任务时可使用的线路 ID：

{
    "success": true,
    "data": {
        "auto_switch_enabled": true,
        "current_id": 0,
        "items": [
            {
                "id": 12,
                "name": "线路 1"
            }
        ]
    }
}

创建任务时，可在 JSON 请求体中传入要使用的线路 ID：

{"lineId": 12}

• 不传 lineId 时，平台按该模型当前的线路策略自动选择。
• 传入当前模型的可用线路 ID 时，本次任务固定使用该线路，不再在其他线路之间自动切换。
• 非正整数会返回 400 错误；线路已停用、已删除或不属于当前模型时返回 503 错误，不会改用其他线路。

创建视频任务

POST /v1/videos
Content-Type: application/json

请求字段

Seedance 参考素材时长

上下界均包含在允许范围内，视频和音频分别累计。URL 素材由平台读取实际时长；超限或无法确认时长时，在提交生成和扣费前返回 400。使用 asset:// 视频或音频素材 ID 时，必须提供对应的 videoDurations 或 audioDurations，数组长度与同类素材数量一致，可使用小数秒。

generationType 取值

videoQualityMode 取值

videoQualityMode 适用于支持双画质的线路：native 为原生画质，enhanced 为画质增强。resolution 表示最终输出分辨率。480p 同样可选两种画质，按对应档位计价；不支持双画质的线路传入该字段会返回参数错误。

需要原生画质时，请明确传入 "videoQualityMode": "native"；省略该字段会沿用线路默认画质，默认值可能是增强模式。

请求示例

以下示例假设所选线路支持双画质。

curl https://your-domain.example/v1/videos \-H "Authorization: Bearer sk-你的令牌" \-H "Content-Type: application/json" \-d '{  "model": "video-model-id",  "lineId": 12,  "generationType": "text-to-video",  "prompt": "黄昏海边，一架纸飞机从镜头前飞过",  "aspectRatio": "16:9",  "seconds": 5,  "resolution": "720p",  "videoQualityMode": "native",  "generateAudio": true,  "negativePrompt": "模糊、闪烁",  "callbackUrl": "https://example.com/video-callback"}'

创建成功后返回视频任务对象：

{
    "id": "task_xxx",
    "object": "video",
    "model": "video-model-id",
    "status": "queued",
    "progress": 0,
    "created_at": 1782658000
}

callbackUrl 也适用于 POST /v1/video/generations 和 POST /v1/videos/{video_id}/remix，JSON 与 multipart 请求均可传入。未传时只需按下文的查询接口获取结果。

任务完成通知（可选）

视频处理需要时间。创建任务后，你会先拿到任务 ID，稍后才能获取结果。你可以定时查询，也可以让平台在处理结束时主动通知你的服务器，这就是“回调”。

没有自己的服务器时，不需要填写 callbackUrl，按下文每 60 秒查询一次即可。

设置通知接收地址

如果你有自己的服务器，在创建任务的请求中加入：

{
    "callbackUrl": "https://your-service.example/video-callback"
}

将示例地址换成你服务器上用来接收通知的接口。这个接口需要能从公网访问，并使用 HTTPS。

你会收到什么

处理成功或失败后，平台会向这个地址发送一份 JSON 通知。下面是成功通知的示例，只展示关键字段：

POST /video-callback HTTP/1.1
Host: your-service.example
Content-Type: application/json
X-Video-Event-Id: video:task_xxx:SUCCESS

{
    "id": "task_xxx",
    "status": "completed",
    "url": "https://example.com/result.mp4"
}

失败通知中的关键字段如下：

{
    "id": "task_xxx",
    "status": "failed",
    "error": {
        "message": "视频处理失败"
    }
}

通知中的字段与查询任务时返回的字段相同，可以用同一套方式读取结果。

收到通知后怎么处理

1. 你的接收接口尽快返回 HTTP 200 或 204，表示“已收到”；其他 2xx 状态码也可以。耗时处理放到后台执行。
2. 检查通知中的 id 是否属于你创建的任务，再用自己的平台令牌调用 GET /v1/videos/{task_id} 确认结果。通知本身不带签名或密钥，确认后再更新业务状态或展示视频。
3. 同一条通知可能重复收到。X-Video-Event-Id 是通知编号，重复发送时保持相同；你的服务器应记住已处理的编号，避免重复处理。

如果平台没有成功送达通知，最多会尝试发送 5 次。因此，使用通知时仍建议每 60 秒查询一次，以免漏掉结果。接收地址应直接处理请求，平台不会跟随地址重定向。创建任务时未填写 callbackUrl，该任务就不会收到完成通知。

查询视频任务

GET /v1/videos/{task_id}

任务状态包括 queued、in_progress、completed 和 failed。任务完成后，响应中会包含视频结果：

{
    "id": "task_xxx",
    "object": "video",
    "model": "video-model-id",
    "status": "completed",
    "progress": 100,
    "created_at": 1782658000,
    "completed_at": 1782658060,
    "url": "https://example.com/result.mp4",
    "metadata": {
        "url": "https://example.com/result.mp4",
        "video_url": "https://example.com/result.mp4",
        "videos": [
            {
                "url": "https://example.com/result.mp4"
            }
        ]
    }
}

url 是最终视频地址，并保留在 metadata.url / metadata.video_url 中。完成通知使用相同字段。

有自己的服务器时，收到完成通知后立即查询，并每 60 秒查询一次，以免漏掉结果。只有客户端时，每 60 秒查询一次；应用重新进入前台或网络恢复后可立即查询一次。成功（completed）或失败（failed）后停止查询。提高查询频率不会加快任务完成，请遵循上述间隔。任务完成后请及时保存结果。

获取视频内容

任务完成后可通过以下接口读取视频内容：

GET /v1/videos/{task_id}/content

该接口会传输视频文件，请在确认任务完成后调用，不要用它轮询任务状态。