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、burst 20）。上限を超えたリクエストは Retry-After: 1 header 付きで 429 rate_limited を返します。作成（POST）とキャンセル（DELETE）はこの制限の対象外です。

ポーリングは1秒に1回以下にしてください。または、タスク作成時に 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 に設定されます。エラーコードの全一覧は Error codes をご覧ください。

Video object

フィールド型説明
idstring一意のタスク識別子（UUID）
statusenumState machine を参照
modelstringModel slug
promptstring元の prompt
unsigned_urlsstring[]completed の場合に存在。アップストリームの元動画URL（一時的、24hで期限切れになる場合があります）
mirror_urlsstring[]completed で、モデルのプロバイダーがCDNミラーを有効にしている場合に存在。永続的な署名付きURL — Video URLs を参照
errorobjectfailed の場合に存在：{code, message}
usageobjectcompleted の場合に存在：{video_seconds, video_cost}。video_seconds は課金対象の秒数（v2v入力秒数を含む）です。video_cost はプラットフォーム tier price での実際の請求額で、精度低下を避けるため固定小数点の10桁 decimal string です
created_at / updated_atintegerUnix 秒

State machine

OpenRouter の命名をベースに、cancelled / expired を拡張した7つの状態です。

StatusTerminal説明
pending—受理済み、まだアップストリームへ送信されていません
queued—アップストリームへ送信済み、キューで待機中
in_progress—アップストリームで生成中
completed✓成功、動画URLが利用可能
failed✓失敗（タイムアウト、error.code=expired を含む）
cancelled✓キャンセル済み
expired✓期限切れ

遷移：pending → queued → in_progress → completed が成功パスです。任意の非終端状態は failed、cancelled、または expired に遷移できます。

Video URLs

成功したタスクは、モデルのプロバイダーでCDNミラーが有効かどうかに応じて、2種類のURLセットを返す場合があります。

フィールドソース特徴
unsigned_urlsアップストリームプロバイダーの元アドレス一時的 — 常に存在 · 24hで期限切れになる場合があります · 署名なし
mirror_urlsofox CDN mirror永続的 — CDN有効プロバイダーのみ · リクエストごとに署名 · TTL あり

mirror_urls（永続的で安定）を優先してください。モデルが unsigned_urls だけを返す場合は、アップストリームの一時アドレスが期限切れになる前に、速やかにファイルをダウンロードまたは再ホストしてください。

Last updated on
プロバイダールーティングタスクのキャンセル