Skip to content
RouteAPI RouteAPI

创建视频生成任务

RouteAPI 的视频生成是一套异步任务 API。你提交请求，拿到 task_id，轮询该任务直到它进入终态，然后下载视频。平台上的所有视频模型——Seedance、Sora、Veo、Wan、Kling、Hailuo、Vidu 等——都使用同一组端点，因为 RouteAPI 会把你的请求转换成所选上游期望的形式。

视频模型会出现在 GET /v1/models 中；走 OpenAI 视频格式的渠道，其 supported_endpoint_types 会显示 openai-video，控制台的模型页面也可以按模型配置该字段。无论哪种情况，模型 ID 都应取自该列表——见模型。模型专属参数按厂商单独说明：Seedance、Hailuo、Wan。同一套 API 的 OpenAI/Sora 方言见 OpenAI 视频格式。

端点

Section titled “端点”
方法路径用途文档位置
POST/v1/video/generations提交生成任务本页
GET/v1/video/generations/{task_id}读取任务记录获取视频任务
POST/v1/videos提交生成任务（OpenAI 方言）OpenAI 视频格式
GET/v1/videos/{task_id}以 OpenAI video 对象读取任务OpenAI 视频格式
POST/v1/videos/{video_id}/remix基于已有视频创建派生任务OpenAI 视频格式
GET/v1/videos/{task_id}/content下载生成完成的视频字节获取视频任务

POST /v1/video/generations 和 POST /v1/videos 是同一次任务操作的两种路径，请求与响应方言不同。两者的提交响应都是 OpenAI video 对象；GET 端点则不同（任务记录与 video 对象），因此每个提交路径要搭配对应的 GET 使用。

任务如何运行

Section titled “任务如何运行”
  1. 提交 — 把 prompt 和 model 发送到 POST /v1/video/generations（或 POST /v1/videos），保存返回的 task_id。预估费用会在这一步从余额中预扣。
  2. 轮询 — 每 10–15 秒调用一次对应的 GET 端点。生成通常需要一到几分钟；分辨率越高、时长越长，耗时越久。
  3. 完成 — 当状态报告成功时，下载视频或读取其 URL。如果任务失败或始终未进入终态，预扣金额会被退回。

提交任务

Section titled “提交任务”
POST /v1/video/generations

请求字段

Section titled “请求字段”

每个视频模型都接受这层通用信封。模型专属选项放在 metadata 里；各适配器实际读取的键见对应厂商页面。

字段类型必填说明
modelstring是来自 GET /v1/models 的模型 ID
promptstring是文本提示词。缺失、为空或只有空白的 prompt 会被拒绝并返回 400
imagestring否单张图像（URL 或 Base64/data URI）。按 images 的第一项处理
imagesstring[]否参考图 / 首帧图。含义取决于模型
sizestring否尺寸或分辨率提示，如 1280x720 或 720p，取决于模型
durationinteger否时长（秒）。RouteAPI 会拒绝负值和大于 3600 的值
secondsstring否时长的旧式字符串形式。读取该字段的模型会用它代替 duration
input_referencestring否OpenAI 风格的参考图字段，由支持它的适配器读取（例如 Sora 和 Wan）
ratiostring否宽高比，如 16:9 或 9:16；由 Seedance 适配器读取
resolutionstring否输出分辨率档位，如 720p 或 1080p；由 Seedance 适配器读取
generate_audioboolean否是否生成配乐。Seedance 上显式的 false 会被转发而不是丢弃
metadataobject否供应商专属参数。对 Seedance 来说，metadata 中的同名值优先于顶层值

RouteAPI 不认识的顶层字段会被忽略；模型专属参数请放在 metadata 下。

提交端点也接受 multipart/form-data 请求体：标量表单字段映射到同名字段，文件直接上传（例如 Sora 的 input_reference）。未知的表单字段会成为 metadata 项。

提交示例

Section titled “提交示例”
Terminal window
curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "An orange cat stretching on a windowsill at sunrise",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false
  }'

提交响应

Section titled “提交响应”
{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1792048458
}

task_id（及其别名 id）是 RouteAPI 的任务 ID，后续每次调用都用它。上游供应商的任务 ID 不是你要轮询的值——即使可见，它也只存在于存储的上游响应体中（任务记录上的 data.data）。

提交成功时还会返回 X-New-Api-Other-Ratios 响应头，其中包含实际应用的计费倍率——例如 Sora 的 {"seconds":5,"size":1}，或带视频输入的 Seedance 请求的 {"video_input":0.608695652174}。对账时很有用。

提交阶段的错误

Section titled “提交阶段的错误”

请求一旦完成路由，任务端点会以任务错误结构作答：

{ "code": "invalid_request", "message": "prompt is required", "data": null }
状态码错误码含义
400invalid_request缺少或空白 prompt、metadata 字段类型错误，或请求体无法解析
400invalid_json在自行校验请求体的适配器上（Sora 与 Wan），JSON 格式错误
400missing_model缺少 model；由自行校验请求体的适配器（Sora 与 Wan）返回。其他路径会在路由前以中间件错误拒绝缺少 model 的请求
400invalid_secondsduration / seconds 为负或大于 3600
400invalid_size模型不接受该尺寸，例如不支持的 Sora 尺寸
400model_price_errorRouteAPI 无法为该模型计价；不会提交到上游
400model_not_supported模型解析到渠道已不再提供的模型，例如 Seedance 1.x
400task_not_existRemix 的原任务未知或属于其他账户
400task_source_unavailableRemix 的原任务所在渠道已删除、禁用，或缺少对应适配器
403insufficient_user_quota / pre_consume_token_quota_failed账户余额或 Key 额度不足以覆盖预估费用；不会提交到上游
429—上游容量耗尽；消息会被替换为通用的「请稍后重试」文案
500build_request_failed、do_request_failed、invalid_response任务无法转换、上游连接失败，或上游未返回任务 ID
500get_channel_failed、task_persistence_failed、gen_relay_info_failedRouteAPI 无法选渠道或记录任务；不产生扣费（预扣会退回）
502upstream_task_id_missing上游接受了任务但没有返回任务 ID；任务被置为失败以释放预扣
任意fail_to_fetch_task上游对提交请求返回非 200 状态码；HTTP 状态码即为上游的状态码

在路由之前被拒绝的请求——API Key 缺失或无效（401）、IP 限制、分组无权限、模型不在 Key 的白名单内（403），或模型没有可用渠道（503，错误码 model_not_found）——使用标准的中间件错误体 {"error": {"message": ..., "type": "error", "code": ...}}，而不是任务结构。

提交之后发生的失败（内容审核、供应商超时、取消）不会表现为 HTTP 错误。它们会以 FAILURE 连同 fail_reason 出现在任务记录中，预扣金额会被退回。

下一步

Section titled “下一步”