エラーと制限
VideoUpscaler API のエラー形式、ステータスコード、レート制限、再試行のガイドライン。
エラー形式
すべてのエラーは同じ JSON 形式です。プログラムでは code を使用してください。message は人が読むためのもので、変更される可能性があります。
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits for this video. Buy credits to continue."
}
}ステータスコード
| ステータス | コード | 意味 | 再試行 |
|---|---|---|---|
400 | invalid_request | リクエストの形式が正しくない | 不可 — リクエストを修正してください |
401 | unauthorized | APIキーが指定されていないか無効 | 不可 |
402 | insufficient_credits | クレジットが不足している | クレジット購入後に可 |
403 | paid_plan_required | アカウントが一度もクレジットを購入しておらず、サブスクリプションも契約していない | クレジット購入後に可 |
403 | invalid_upload_token | アップロード URL が無効または有効期限切れ | 新しいアップロード URL を取得してください |
403 | invalid_stream_token | イベントストリーム URL が無効または有効期限切れ | もう一度 /tasks/{id}/events を開いてください |
404 | not_found | 該当するタスクがアカウントにない | 不可 |
409 | idempotency_conflict | Idempotency-Key が別のパラメータで再利用された | 新しいキーを使用してください |
411 | invalid_request | アップロードの PUT にボディまたは Content-Length がない | 不可 — リクエストを修正してください |
413 | file_too_large | 動画がサイズ上限を超えている | 不可 |
422 | video_fetch_failed | video_url をダウンロードできなかった | URL を修正した後に可 |
422 | unsupported_video | 読み取り可能な MP4、MOV、WebM ではない | 不可 |
422 | video_too_long | 動画が解像度ごとの上限を超えている | 不可 |
422 | video_not_found | この video_url に何もアップロードされていない | アップロード完了後に可 |
429 | rate_limited | リクエストが多すぎる | 可（Retry-After 秒後） |
500 | internal_error | サーバー側で問題が発生した | 可（同じ Idempotency-Key で） |
502 | upstream_error | 処理を開始できなかった。課金分はすべて返還済み | 可（新しい Idempotency-Key で） |
504 | upstream_timeout | video_url のダウンロードに時間がかかりすぎた | 可、またはより高速なホストを使用してください |
制限
| 制限 | 値 |
|---|---|
| リクエスト数 | APIキーごとに 1 分あたり約 120 回 |
| 動画の長さ | 1080p は 1200 秒、2k・4k は 600 秒 |
リモートの video_url のサイズ | 500MB |
| アップロードファイルのサイズ | 100MB |
| アップロード URL の有効期間 | 1 時間 |
| 有効な APIキー数 | アカウントごとに 20 個 |
安全な再試行
/upscale には必ず Idempotency-Key を付けて送信してください。リクエストがタイムアウトした場合や 500 または 504 が返された場合は、同じキーで再試行してください。二重に課金されることなく、すでに作成されたタスクが返されます。
502 upstream_error は別です。タスクは作成されましたが開始に失敗して返金済みのため、同じキーでは失敗したタスクが返され続けます。新しいキーで再試行してください。