Skip to content
RouteAPI RouteAPI

OpenAI 视频格式

POST /v1/videos 和 GET /v1/videos/{task_id} 是同一套异步任务 API 的 OpenAI 视频方言，任务流程见创建视频生成任务和获取视频生成任务状态。提交请求体使用相同的字段，区别在响应：提交响应和 GET 都返回 OpenAI video 对象，而不是任务记录。Sora 模型使用这一格式，OpenAI SDK 的视频客户端也按这一格式解析。

端点

Section titled “端点”
方法路径用途
POST/v1/videos提交生成任务
GET/v1/videos/{task_id}以 OpenAI video 对象读取任务
GET/v1/videos/{task_id}/content下载生成完成的视频字节
POST/v1/videos/{video_id}/remix基于已有视频创建派生任务

提交

Section titled “提交”
Terminal window
curl https://api.routeapi.ai/v1/videos \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A calico cat playing a piano on stage",
    "size": "1280x720",
    "seconds": "4"
  }'

请求字段就是创建视频生成任务中列出的那一组：model、prompt、seconds / duration、size、input_reference、images 和 metadata。支持参考图的模型会读取 input_reference。也接受 multipart/form-data，可以直接上传文件：

Terminal window
curl https://api.routeapi.ai/v1/videos \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "model=sora-2" \
  -F "prompt=A calico cat playing a piano on stage" \
  -F "size=1280x720" \
  -F "seconds=4" \
  -F "input_reference=@cat.jpg"

提交响应

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

id 就是 RouteAPI 的任务 ID。task_id 是兼容别名，后续可能不再返回，请读取 id。后续轮询和下载一律使用这个 id；存储的上游响应体里出现的 ID 不是你要用的值。

提交响应还会带上 X-New-Api-Other-Ratios 响应头，包含实际应用的计费倍率，例如 Sora 请求的 {"seconds":5,"size":1}。

获取 video 对象

Section titled “获取 video 对象”
GET /v1/videos/{task_id}
Terminal window
curl https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY"
{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1792048458,
  "completed_at": 1792048569,
  "metadata": { "url": "https://...mp4" }
}
字段说明
idRouteAPI 任务 ID
object固定为 "video"
model执行该任务的模型
statusqueued、in_progress、completed 或 failed
progress0–100 的整数
created_at / completed_atUnix 秒。部分适配器会用该行的最后更新时间填充 completed_at，因此请用 status 判断是否完成，而不要依赖这个字段
expires_at、size、seconds、remixed_from_video_id仅在供应商返回时出现
metadata.url对会通过 video 对象报告 URL 的供应商，这里是视频 URL。若想无论供应商都拿到字节，请使用 /v1/videos/{task_id}/content
error.code / error.message任务失败时设置，例如 Seedance 的 expired 或 cancelled

上游响应体自带的字段（如 expires_at 或 size）只在供应商返回时才出现；上表是 RouteAPI 保证映射的字段集合。在 Gemini 和 Vertex 渠道上，构建该对象前会先从供应商刷新任务状态。

任务按 API Key 所属用户隔离：属于其他账户的 id 会被报告为 task_not_exist，与任务记录端点一致。

下载内容

Section titled “下载内容”
GET /v1/videos/{task_id}/content

返回视频字节，经 RouteAPI 流式传输。响应带有 Cache-Control: public, max-age=86400 和上游的 Content-Type。该路由接受 API Key 或控制台会话，且只返回调用方自己任务的视频。错误码与 curl 示例见下载视频。

Remix

Section titled “Remix”
POST /v1/videos/{video_id}/remix

基于已有视频创建新任务。RouteAPI 会在你的任务中查找 video_id，从中推导出模型，并把请求固定到生成原视频的渠道，以保证结果兼容。

Terminal window
curl https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV/remix \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "The same cat, now wearing a tiny hat" }'

Remix 对 Sora 系列（sora-2、sora-2-pro）有实际意义：请求会转发到上游自己的 remix 端点，且 prompt 为必填。对其他平台，请求仍会被接受，模型和渠道从原任务解析，任务由该模型的适配器构建——但上游不会收到 remix 指令，因此新任务只是一次普通生成，而不是 video_id 的派生。

适配器记录了原任务的计费倍率时，remix 会继承这些倍率，因此新任务按原任务计价，而不是按默认值。

Sora

Section titled “Sora”

Sora 模型直接使用这组端点，真正起作用的参数是 size 和 seconds。

模型可用尺寸
sora-2720x1280、1280x720
sora-2-pro720x1280、1280x720、1792x1024、1024x1792
  • 不支持的尺寸会在预扣任何费用之前返回 400，错误码 invalid_size。
  • 默认值为 720x1280 和 4 秒。
  • seconds（或 duration）与其他视频模型同样校验：负值和大于 3600 的值会被拒绝，返回 400 invalid_seconds。
  • input_reference 作为参考图转发；JSON 与 multipart 提交都可用。
  • 计费由 seconds 和 size 计算：1792x1024 或 1024x1792 输出在按秒价格之外还要乘上尺寸倍率（1.666667）。实际应用的倍率会通过 X-New-Api-Other-Ratios 返回。
  • 该系列支持 Remix。

可用性和价格因账户而异——请确认模型出现在 GET /v1/models 中，并查看模型详情页。

错误

Section titled “错误”

完成路由后适用任务错误结构：

状态码错误码含义
400invalid_request缺少或空白 prompt、请求体格式错误，或字段类型错误
400invalid_secondsduration / seconds 为负或大于 3600
400invalid_size模型不接受该尺寸（例如不支持的 Sora 尺寸）
400task_not_existremix 中的 video_id 未知或属于其他账户
400task_source_unavailable原任务的渠道已删除、禁用，或缺少对应适配器
400asset_remix_conflict对非素材任务做 remix 时试图引用 asset:// 素材
429—上游容量耗尽；消息会被替换为通用的重试提示
500build_request_failed、do_request_failed任务无法转换或上游连接失败
500convert_to_openai_video_failed存储的任务数据无法转换为 video 对象
501not_implemented在适配器没有 OpenAI video 转换的平台调用 GET /v1/videos/{task_id}
任意fail_to_fetch_task上游对提交请求返回非 200 状态码；HTTP 状态码即为上游的状态码

在路由之前被拒绝的请求改用标准错误体 {"error": {"message": ..., "type": "error", "code": ...}}。

下一步

Section titled “下一步”