视频生成与任务查询
Seedance 等视频模型的异步创建与状态查询。
/v1/videos/generationshttps://api.hanrouter.ai/v1管理 API Key地址与认证
OpenAI 兼容客户端的 Base URL 为 https://api.hanrouter.ai/v1,请求头为 Authorization: Bearer $HANROUTER_API_KEY。不要重复拼接 /v1。所有厂商都使用本站密钥,不需要向客户端填写上游厂商密钥。
Anthropic SDK 与 Claude Code 的 Base URL 使用 https://api.hanrouter.ai(不含 /v1),由客户端拼接 /v1/messages。Google 模型优先使用本站 OpenAI 兼容接口。
视频任务流程
视频通常异步生成:提交一次 → 保存任务 ID → 使用同一 Key 轮询 → 到达成功或失败终态 → 下载结果。HTTP 200 仅代表请求被接受,不等于视频生成完成。先从 GET /v1/models 选择视频输出模型并确认分组权限。
提交文生视频任务
本站创作页面使用 POST /v1/videos/generations,发送 model、prompt、duration、resolution。将占位模型 ID 替换为当前 Key 可用且支持该协议的模型。以下 5 秒、720p 仅为示例值,不是全部模型的共同能力;以渠道实际限制及报价为准。
curl --max-time 300 "https://api.hanrouter.ai/v1/videos/generations" \
-H "Authorization: Bearer $HANROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_VIDEO_MODEL_ID",
"prompt": "A golden bull runs forward, slow cinematic camera movement",
"duration": 5,
"resolution": "720p"
}'图生视频:参考首帧
支持该方式的渠道可添加 image: {"url":"https://..."},与本站创作页首帧输入一致。将示例地址换成上游可访问的图片。部分渠道接受 data URL,其他渠道只接受公开 HTTPS URL;图片格式、比例及大小限制由模型决定。
curl --max-time 300 "https://api.hanrouter.ai/v1/videos/generations" \
-H "Authorization: Bearer $HANROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_VIDEO_MODEL_ID",
"prompt": "A golden bull runs forward, slow cinematic camera movement",
"duration": 5,
"resolution": "720p",
"image": {
"url": "https://example.com/first-frame.png"
}
}'Seedance 原生 content 协议
仅当 Seedance 渠道明确支持 BytePlus / ModelArk 原生透传时,使用 content 数组代替上述 prompt 方式。文本块为 {type:"text",text:"..."};常见首帧图像块为 {type:"image_url",image_url:{url:"https://..."},role:"first_frame"}。注意 role 的层级随网关适配可能不同,不能直接混用参考站的嵌套格式。
ratio、generate_audio、seed、尾帧、参考视频/音频、Draft 和 wait 均为模型与渠道相关能力。本文不承诺所有 Seedance 版本支持 4–15 秒、同步等待、音频生成或视频续写;未确认支持的字段先不发送。
curl --max-time 300 "https://api.hanrouter.ai/v1/videos/generations" \
-H "Authorization: Bearer $HANROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_SEEDANCE_MODEL_ID",
"content": [
{
"type": "text",
"text": "A cat runs along the beach at sunset"
}
],
"ratio": "16:9",
"duration": 5
}'保存任务 ID 与轮询地址
提交响应可能使用 id、task_id 或 request_id,状态可能为 submitted、queued 或 processing。保存完整响应和实际任务 ID。本站创作页查询 GET /v1/videos/{id};使用 /v1/videos/generations/{id} 的上游原生渠道必须先确认该路由已开放,不要默认参考站的查询路径在本站通用。
# Illustrative submission response (not a real task)
{"id":"task-id-from-response","status":"processing"}
# Replace TASK_ID with the ID actually returned
curl "https://api.hanrouter.ai/v1/videos/$TASK_ID" \
-H "Authorization: Bearer $HANROUTER_API_KEY"状态、结果与安全重试
建议每 5 秒查询一次,并遵守 Retry-After。成功状态可为 succeeded / completed,失败状态可为 failed / error / expired / canceled,具体以响应为准。不同适配器可能在 url、video_url、content.video_url、content[].video_url 或 result 中返回结果,不能把所有厂商写死成同一结构。终态成功但没有文件地址时,保留原始响应并联系支持。
查询 404 时先核对任务 ID、原 Key、所用路由及保留期限;不要重新提交代替查询。连接超时不代表任务未创建。400 检查参数与参考文件可访问性;401/403 检查 Key 及权限;402 检查余额;429 降低并发;5xx 保存 X-Request-Id 与脱敏错误。不要承诺失败必退款,实际扣费、退款及计费单位以控制台用量和订单为准。请及时下载视频,远程 URL 可能过期。
请求参数
model- 必填 string:当前 Key 可用的准确模型 ID。
prompt- string:图片生成或视频 prompt 协议的提示词;使用原生 content 时按渠道要求选择。
content- Seedance 输入数组:文本、图像或模型支持的参考内容。
duration- 可选 integer:视频秒数,以模型限制为准。
resolution- 可选 string:模型支持的分辨率。
ratio- 可选 string:模型支持的宽高比,例如 16:9;仅向支持此字段的渠道发送。
generate_audio- 可选 boolean:是否生成音频,仅适用于支持该能力的模型与渠道。
seed- 可选 integer:随机种子,取值范围由模型与渠道决定。
请求示例
示例采用当前目录中的模型 ID。实际可调用范围取决于 API Key 的分组权限,请先查询 GET /v1/models。
curl -X POST "https://api.hanrouter.ai/v1/videos/generations" \
-H "Authorization: Bearer $HANROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "your-model-id",
"prompt": "A red bicycle beside a tree, slow camera movement",
"duration": 5,
"resolution": "720p"
}'响应示例
{
"id": "task-id-from-response",
"status": "submitted"
}