查询任务状态


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

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

Terminal


curl https://api.ofox.ai/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": "google/veo-3.1",
  "prompt": "A golden retriever running on the beach at sunset",
  "unsigned_urls": ["https://upstream.example/out.mp4"],
  "mirror_urls":   ["https://cdn.ofox.ai/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 任务对象

字段	类型	说明
`id`	string	任务唯一标识（UUID）
`status`	enum	见状态机
`model`	string	模型 slug
`prompt`	string	原始提示词
`unsigned_urls`	string[]	`completed` 时出现。上游原始视频 URL（临时，可能 24h 过期）
`mirror_urls`	string[]	`completed` 且该模型 provider 启用 CDN 镜像时出现。持久签名 URL，见视频 URL
`error`	object	`failed` 时出现：`{code, message}`
`usage`	object	`completed` 时出现：`{video_seconds, video_cost}`。`video_seconds` 为计费秒数（含 v2v 输入秒）；`video_cost` 为按平台档价计费的实际费用，定点 10 位小数字符串（防精度丢失）
`created_at` / `updated_at`	integer	Unix 秒

状态机

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_urls`	ofox CDN 镜像	持久——仅启用 CDN 的 provider · 每次请求现签 · 有 TTL

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

查询任务状态

限流保护

响应

已完成

失败

Video 任务对象

状态机

视频 URL