Skip to Content
API リファレンス動画生成エラーコード

エラー

Video API endpoints からのすべてのエラーは、同じ JSON shape を使用します：

{
  "error": {
    "code": "...",
    "message": "..."
  }
}

HTTP status は問題の種類を示します。error.code はコード上で分岐に使える安定した文字列です。error.message を parse するのではなく、常に error.code で判定してください。

エラーコード

HTTPCode意味
400invalid_request必須パラメータが欠落している、または値が無効です
400invalid_callback_urlcallback_url が HTTPS ではない、または private network を指しています（SSRF checks によりブロック）
400references_conflictframe_images と input_references が同じリクエストで送信されました（同時使用不可）
400too_many_referencesinput_references が上限を超えています（画像 > 9 / 音声 > 3 / 動画 > 1）
400cancel_not_supportedアップストリームプロバイダーがこの job を中断できません
400cancel_failedjob はすでに終端状態で、キャンセルできません
401unauthorized / invalid_api_key認証に失敗しました
401upstream_auth_failedアップストリームプロバイダーの認証に失敗しました
402insufficient_creditsjob を受理するための残高が不足しています
404not_foundjob が存在しない、またはアクセス権がありません
404model_not_foundリクエストされた model が存在しません
429rate_limitedリクエストが多すぎます（ポーリングレート制限またはアップストリームレート制限）
502upstream_error / route_errorアップストリームプロバイダーのエラー / ルーティング失敗
500internal_error予期しない内部エラー

references_conflict と too_many_references は request-body validation errors です。正確な上限は 動画を作成 をご覧ください。cancel_not_supported と cancel_failed は 動画をキャンセル で説明しています。not_found は、未知の job と、別の API key が所有する job の両方で返されます。この2つは意図的に区別できません。

real_person 前処理エラー

real_person: true の画像前処理が入力画像の問題で失敗した場合、API は HTTP 400 と error.code: "invalid_request" を返します。error.message の末尾には次の安定した理由コードのいずれかと、失敗した参照位置（例：input_references[0]）が含まれます：

理由コード修正内容
bad_data_uridata: URI の形式または base64 ペイロードが無効です
download_failed接続、タイムアウト、アクセス制御の問題で画像をダウンロードできません
unreachable画像 URL が成功以外の HTTP ステータスを返しました
not_imageダウンロード内容がサポート対象のデコード可能な画像ではありません
too_large画像がサイズ、ピクセル数、または1リクエストあたりの処理上限を超えています
{
  "error": {
    "code": "invalid_request",
    "message": "real_person image processing failed — input_references[0]: ... (not_image)"
  }
}

アプリケーションの分岐では引き続き error.code を使用し、理由コードと参照位置は入力の修正や診断に利用してください。

402 残高不足

insufficient_credits は job 作成時（POST /v1/videos）にのみ返されます。事前承認が有効な場合、ofox は job を受理する前に、リクエストされた resolution と duration からコストを見積もります。その見積もりが残高を超える場合、リクエストは即座に拒否されます。job record は作成されず、課金も発生しません。

{ "error": { "code": "insufficient_credits", "message": "..." } }

insufficient_credits は Video API が返す唯一の 402 code です。この1つの code を処理し、残高を追加してから再試行してください。

429 レート制限

rate_limited は、GET /v1/videos/{id} の key ごとのポーリング制限と、アップストリームのレート制限の両方を表します。ポーリング制限に達した場合、レスポンスには Retry-After header が含まれます：

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
 
{ "error": { "code": "rate_limited", "message": "..." } }

Retry-After header に従い、再試行前にバックオフしてください。頻繁にポーリングしている場合は、webhook 通知 に切り替えると、ofox が終端状態を push するため、ポーリング制限を完全に回避できます。Job 作成（POST）とキャンセル（DELETE）はポーリング制限の影響を受けません。

Last updated on
Webhook 通知