Skip to Content
API 参考视频生成查询任务

查询任务状态

GET https://api.ofox.io/v1/videos/{id}

查询任务的状态与结果。创建任务后，轮询此端点直到 status 进入终态——completed、failed、cancelled 或 expired。

Terminal
curl https://api.ofox.io/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718 \
  -H "Authorization: Bearer $OFOX_API_KEY"

限流保护

本端点按 API Key 独立限流（默认 5 req/s、突发 20）。超限返回 429 rate_limited，并带 Retry-After: 1 响应头。创建（POST）与取消（DELETE）不受此限流影响。

建议轮询间隔不快于每秒一次，或在创建任务时传 callback_url，用 webhook 代替轮询。

响应

{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "completed",
  "model": "bytedance/seedance-2.5",
  "prompt": "A golden retriever running on the beach at sunset",
  "unsigned_urls": ["https://upstream.example/out.mp4"],
  "mirror_urls":   ["https://cdn.ofox.io/videos/vgen_xxx.mp4?sig=..."],
  "usage": {
    "video_seconds": 5,
    "video_cost": "0.4000000000"
  },
  "created_at": 1776211362,
  "updated_at": 1776211400
}

超时会以 status: "failed" 上报，且 error.code 为 expired。完整错误码见 错误码。

Video 任务对象

字段类型说明
idstring任务唯一标识（UUID）
statusenum见 状态机
modelstring模型 slug
promptstring原始提示词
unsigned_urlsstring[]completed 时出现。上游原始视频 URL（临时，可能 24h 过期）
mirror_urlsstring[]completed 且该模型 provider 启用 CDN 镜像时出现。持久签名 URL，见 视频 URL
errorobjectfailed 时出现：{code, message}
usageobjectcompleted 时出现：{video_seconds, video_cost}。video_seconds 为计费秒数（含 v2v 输入秒）；video_cost 为按平台档价计费的实际费用，定点 10 位小数字符串（防精度丢失）
created_at / updated_atintegerUnix 秒

状态机

7 个状态，以 OpenRouter 命名为基底并补充 cancelled / expired。

状态终态说明
pending—已受理，尚未提交上游
queued—已提交上游，排队中
in_progress—上游生成中
completed✓成功，视频 URL 可用
failed✓失败（含超时，error.code=expired）
cancelled✓已取消
expired✓过期

流转：pending → queued → in_progress → completed 为成功路径。任意非终态可转 failed、cancelled 或 expired。

视频 URL

成功任务可能返回两组 URL，取决于该模型 provider 是否启用 CDN 镜像。

字段来源特性
unsigned_urls上游供应商原始地址临时——恒有 · 可能 24h 过期 · 未签名
mirror_urlsofox CDN 镜像持久——仅启用 CDN 的 provider · 每次请求现签 · 有 TTL

优先使用 mirror_urls（持久、稳定）。当模型只返回 unsigned_urls 时，请尽快下载或转存，避免上游临时地址过期。

Last updated on
供应商路由取消任务