视频生成

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

下载图片与视频 API 接入指南（Markdown），交给 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

请求字段

generationType 取值

videoQualityMode 取值

videoQualityMode 适用于已开启双画质的线路，线路规则中的 video.quality_modes.enabled 为 true。native 直接生成原生画质；enhanced 使用该线路的增强预设，可能先生成较低分辨率的视频，再增强到请求的输出分辨率。resolution 表示最终输出分辨率，例如增强模式下可能先生成 480p，再输出 720p。480p 不支持 enhanced；不支持双画质的线路传入该字段会返回参数错误。

需要原生画质时，请明确传入 "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 请求均可传入。平台保存该字段，不转发给视频供应商。未传时只需按下文的查询接口获取结果。

异步终态回调

任务成功或失败后，平台向 callbackUrl 发送 POST 请求，Content-Type 为 application/json。请求体与 GET /v1/videos/{task_id} 返回的终态任务对象同形，status 为 completed 或 failed。例如：

X-Video-Event-Id: video:task_xxx:SUCCESS

事件 ID 对同一任务终态保持稳定，接收方应按该 ID 去重，并返回任意 HTTP 2xx 表示已收到。回调失败最多尝试 5 次，最终失败会被记录。回调不附带密钥或签名；需要核实结果时，用自己的平台令牌查询 GET /v1/videos/{task_id}。

回调地址在提交和发送时都会校验，只允许公网 HTTPS，且不会跟随重定向。接收方应快速返回 2xx；后续处理可以在自己的服务内异步完成。未配置 callbackUrl 的已有任务不会补发回调。

callbackUrl 是发给接入方服务端的 Webhook。只有浏览器、桌面或移动客户端、没有公网 HTTPS 接收服务时，可不传该字段，按下文的状态接口定时查询。若有自己的服务端，可由服务端接收回调，再通过自己的 SSE、WebSocket 或推送服务通知客户端。对外视频 API 当前没有供 API 令牌直接订阅的消息接口。

Seedance 2.0 / 2.5 擦除字幕

使用 seedance-2.0-erase 可以自动识别并擦除视频字幕，再修复擦除区域。该模型值同时支持处理 Seedance 2.0 和 Seedance 2.5 生成的视频；处理 Seedance 2.5 视频时，model 仍填写 seedance-2.0-erase。

也可以使用统一字段 videoUrls: ["https://example.com/source.mp4"] 代替 video_url，但一次任务只能传入一个最长 60 秒的视频。

以下示例仅擦除画面下方区域中的字幕：

curl https://your-domain.example/v1/videos \-H "Authorization: Bearer sk-你的令牌" \-H "Content-Type: application/json" \-d '{  "model": "seedance-2.0-erase",  "video_url": "https://example.com/seedance-2.5-source.mp4",  "mode": "Subtitle",  "output_encode_mode": "Quality",  "erase_ratio_location": [    {      "top_left_x": 0,      "top_left_y": 0.7,      "bottom_right_x": 1,      "bottom_right_y": 1    }  ]}'

擦除任务与普通视频任务使用相同的异步响应、查询和内容获取接口。

查询视频任务

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",
    "native_video_url": "https://example.com/original.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 中。线路执行了视频增强且保存了原片时，native_video_url 返回增强前已归档的视频地址；原片分辨率取决于实际线路，可能是 480P 或 720P。未增强、失败、尚未完成或无已归档原片的任务不返回该字段。临时存储的原片链接会过期，需要时重新查询任务获取新签名。终态回调使用相同字段。

有服务端时，推荐以终态回调触发查询，并每 60 秒查询一次作为兜底。纯客户端接入时，每 60 秒查询一次；应用重新进入前台或网络恢复后可立即查询一次，得到 completed 或 failed 后停止。进行中的状态查询优先读取本站缓存或任务记录，不会因客户端查询频率提高而加快上游生成或增加上游状态轮询。过密查询会增加本站 API、缓存和数据库负载；任务完成后，首次读取结果还可能触发视频归档，获取媒体内容也可能受上游或对象存储可用性影响。

获取视频内容

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

GET /v1/videos/{task_id}/content

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