テキスト→動画APIのエラーコード徹底解説

テキスト→動画APIの失敗のほとんどは、5つのカテゴリに集約されます。不正なリクエスト、認証の問題、レート制限、セーフティブロック、サーバー障害です。 HTTPステータス、エラーボディ全文、リクエストIDまたはタスクID、そして失敗した時刻を確認すれば、たいていは原因をすばやく特定できます。

要点をまとめると次のとおりです。

• 400系エラーはたいていリクエストを修正する必要があることを意味します。
• 401/403はたいていAPIキー、アクセス権、課金、IPルールに関係します。
• 429はリクエスト、ジョブ、または利用上限に達したことを意味します。
• 送信時の200 OKは動画が完成したことを意味し ません。 それでもジョブをポーリングしてfailedをチェックする必要があります。
• 500系エラーはリトライが必要になることが多いですが、ジョブがまだ実行中かどうかを確認した 後で のみ行います。
• セーフティブロックは生成の前・途中・後に発生する可能性があり、一部のAPIはジョブ全体を失敗させる代わりにより少ないクリップを返すことがあります。

いくつか目立つ数字があります。Sora 2などを使う動画ジョブはGPUを30〜90秒占有することがあり、クライアントのタイムアウトは10分以上必要になる場合があります。よく使われるリトライ計画は5秒から開始、上限60秒、3回で停止です。

失敗するジョブと重複課金を減らしたいなら、ワークフローをシンプルに保ちます。

• エラーボディとタスクIDをログに残す
• APIレイヤーのエラーとジョブレベルの失敗を区別する
• 429と5xxのケースのみリトライする
• 同じジョブを再送信する前にタスクの状態を確認する
• latestのようなエイリアスではなく、正確なモデルバージョンを固定する

良好な開発者体験を実現するAPIエラーメッセージ

クイック比較

簡単に言えば、送信の成功はレンダリングの成功ではありません。ポーリング結果を信頼できる情報源として扱い、ステータスコードだけでなくエラーペイロードを使って次に何をするか判断すべきです。

クライアント側のリクエストエラー: 修正できる400系コード

エラーの詳細をログに残したら、次はリクエスト側で何が問題だったかを突き止めます。まずエラーボディから始め、次にHTTPコードを修正内容に対応づけます。

400、404、413、415: 各コードが動画リクエストで意味すること

各コードはそれぞれ異なる種類のリクエストミスを示します。400はたいてい不正なJSON、必須フィールドの欠落、または無効なパラメータ型を意味します。たとえばdurationを整数（6）ではなく文字列（"6"）として渡すとバリデーションに失敗します ^[4]。404はモデルIDまたはエンドポイントパスが誤っていることを意味し、[wan-2.7](https://apimart.ai/ja/model/wan-2-7) or [wan-2.6](https://apimart.ai/model/wan-2-6)ではなくwan2.7のような小さなタイプミスが原因になることがよくあります ^[7]。413は参照画像や動画がアップロードサイズの上限を超えている場合に発生します ^[4][7]。415はContent-Typeヘッダーが誤っているか、ファイル形式がモデルでサポートされていないことを意味します ^[5]。

バリデーション失敗を引き起こすモデルとパラメータの不一致

JSONがきれいでも、モデルはすべて同じルールに従うわけではないため、リクエストがバリデーションに失敗することがあります。解像度、長さ、アスペクト比、アセット制限はモデルごとに変わり得ます。

MiniMax-Hailuo-2.3を例に取りましょう。768pで10秒をサポートしますが、1080pをリクエストすると最大の長さは6秒に下がります ^[6]。アセットのルールも同様に厳格になり得ます。Kling 3.0は入力画像が両辺とも最低300px、アスペクト比が1:2.5〜2.5:1であることを要求します。Wan 2.7は参照動画が2〜10秒の長さで100MB以下であることを要求します ^[4][7]。

422はたいていパラメータ同士が衝突していることを意味します。たとえばSkyReels V4は、同じリクエストでImage-to-VideoとOmniのフィールドを組み合わせると422を返します ^[8]。

ちょっとした習慣で多くの時間を節約できます。汎用的なエイリアスではなく、固定したバージョン文字列を使うことです。パラメータのルールはモデルバージョン間で変わり得ます ^[3]。それでもバリデーションに失敗する場合は、リトライする前にそのモデルの正確な制限を確認してください。

リクエストがバリデーションを通過しても失敗する場合は、次に認証、レート制限、セーフティチェックに進みます。

認証、権限、レート制限

バリデーションを通過すると、残りの失敗のほとんどは3つに集約されます。認証、権限、またはレート制限です。

401と403: APIキーとアクセスのエラー

401 Unauthorizedエラーは、リクエストに有効な認証情報が含まれていなかったことを意味します。よくある原因は、APIキーの欠落、無効なキー、無効化または削除されたキー、または壊れたAuthorizationヘッダーです ^[9][1][2]。

多くのAPIは次を期待します。

Authorization: Bearer YOUR_API_KEY

一部のプラットフォームは代わりにx-api-keyを使います。そのため、ヘッダー名や形式が違うと、それだけで401が発生することがあります ^[1][10]。

基本から始めましょう。環境変数を確認し、キーがまだ有効であることを確かめ、CI/CDの設定が各環境でシークレットを正しく注入していることを確認します ^[3]。HTTPステータスコードで止まらず、レスポンスボディを読むことも役立ちます。invalid_api_key、token_expired、account_bannedのようなエラーは、たいてい何が壊れたのかをはるかに速く教えてくれます ^[9][3]。

403 Forbiddenは、サーバーがあなたを認識したものの、それでもリクエストをブロックしたことを意味します。これはたいていアクセスの問題を示します。キーに適切なモデルスコープがない、アカウントプランにそのエンドポイントが含まれていない、クレジットを使い切っている、またはリクエストIPが許可リストにない、といったことが考えられます ^[3][9]。

ここでもレスポンスボディが重要です。insufficient_creditsが見えたら課金を確認します。permission_errorが見えたらスコープ、モデルアクセス、またはプラン制限を確認します。そしてアクセスに問題がないのにトラフィックが多すぎる場合、次に行き着く先はたいてい429です。

429: レート制限とクォータ超過のエラー

認証に成功すると、次のボトルネックになりやすいのはリクエスト量です。429 Too Many Requestsエラーは、スロットル、同時実行の上限、または利用上限に達したことを意味します ^[3][9][10]。平たく言えば、短い時間に多くのリクエストを送った、一度に多くのジョブを実行した、または課金上限を超えた、ということです ^[3][9]。

ここでもレスポンスボディが最良の手がかりを与えてくれます。rate_limit_exceededはたいてい指数バックオフを使うべきことを意味します。spend_limit_exceededは課金設定を確認すべき時であることを意味します ^[3][9]。

可能なときはバッチジョブをローカルでキューに入れ、次のヘッダーに注意を払いましょう ^[2]。

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

APIMartを使っている場合、モデル横断で1つのキーを使えるため認証のずれを減らせます ^[3]。それでもデバッグの流れはほぼ同じです。レスポンスボディを読み、環境変数を確認し、アカウントが呼び出しているモデルにアクセスできることを確かめます。

セーフティブロック、タイムアウト、サーバー側の障害

リクエストのバリデーションと認証を通過すると、残る失敗はたいてい2つのカテゴリに分かれます。モデレーションによるブロックとサーバー側の問題です。認証、クォータ、バリデーションがクリアされたら、残りのデバッグをこの2つの経路に分けましょう。

動画生成におけるモデレーションとコンテンツポリシーのエラー

セーフティブロックは3つの異なるタイミングで発生し得ます。生成が始まる前（リクエストが即座に拒否される）、レンダリング中（ジョブが途中で停止される）、または動画が生成された後（出力が配信前にフィルタされる）です ^[11]。最後のケースが人々を混乱させます。ジョブが完了しても、結果がフィルタされれば何も配信されないことがあります。

ポーリングベースのAPIでは、HTTPステータスが誤解を招くことがあります。ステータスチェックで200 OKが返ってくる一方で、JSONボディにはstate: "failed"とあり、SensitiveContentDetectedやNSFWのようなエラーが含まれていることがあります ^[12]。実際には、HTTPステータスコードではなくポーリングのボディが信頼できる情報源です。

モデレーションブロックが発動した場合、まったく同じプロンプトをリトライしてはいけません。書き直しましょう。平易で技術的な撮影用語は、厳格なセーフティフィルターによる誤検知を減らすのに役立ちます ^[11]。たとえば次のようなものです。

• gimbal shot
• medium tracking shot
• golden hour lighting

ここにはもう一つのひねりがあります。Google Veoを含む一部のモデルは、いくつかの出力がセーフティフィルターにブロックされたとき、ジョブ全体を失敗させる代わりに、要求した数より少ないクリップを返すことがあります ^[3]。そのため、リクエストが完了したかどうかだけを確認してはいけません。返されたアセットの数が要求した数と一致しているかを確認しましょう。

プロンプトに問題がなさそうなのにジョブがなお失敗する場合は、次のレイヤーであるサーバーの安定性に進みます。

500、502、503、非同期動画ジョブのタイムアウトエラー

サーバー側の障害はデバッグの流れの別の部分に位置します。テキスト→動画ジョブはGPUスロットを30〜90秒占有することが多く ^[3]、そのため過負荷やタイムアウトの影響を受けやすくなります。

500と504エラーの場合は、リトライする前にジョブ状態を確認します。むやみなリトライは重複レンダリングを生み、コストを倍にしかねません ^[3]。すべてのtaskIdやprediction_idをログに残し、新しいジョブを送信する前にステータスエンドポイントを直接照会できるようにしましょう ^[3][13]。

リトライが安全な場合は、ジッター付きの指数バックオフを使います。実用的な設定は次のとおりです。

• 5秒から開始する
• 上限を60秒にする
• 3回試行したら停止する ^[13][12]

クライアントのタイムアウトを10分以上に設定し ^[3]、predict_timeの値の上昇でアラートを出しましょう ^[3]。

テキスト→動画APIの手順ごとのデバッグワークフロー

エラーを分類し、正しい修正を適用する

このワークフローを使えば、症状から修正まで一度のパスで進めます。まず、レスポンスボディ全文を読みます。次に、HTTPステータスコードとエラーボディの内容で失敗を分類します。一部のプロバイダーは独自のエラー範囲も送りますが、主な指針はHTTPステータスコードとエラーボディにすべきです ^[3][1]。

レスポンスボディから始め、結果を次のいずれかのグループに分類します。

ジョブが送信されたら、HTTPレスポンスだけで考えるのをやめ、タスクの状態も見ましょう。非同期ジョブでは、同じジョブを再送信する前に、ポーリングのレスポンスでfailedやexpiredを確認します。その一手順で、余分なコストと多くの混乱を避けられます。

コードに手を付ける前に、プロバイダーのステータスページを確認しましょう。サービスが劣化している場合、ローカルのデバッグでは大した情報は得られません。その後、x-deny-reasonレスポンスヘッダーを調べます。このチェックを飛ばすと、プロキシレベルの拒否がモデルのエラーのように見えることがあります ^[3]。

また、latestではなくkling-v3.0-stdのような正確なモデルバージョン文字列を固定しましょう。サイレントなモデル更新は、前日まで問題なく動いていたパイプラインに新たなバリデーション失敗をもたらすことがあります ^[3]。

より信頼性の高い連携のための要点

テキスト→動画APIの失敗のほとんどは、繰り返し現れるいくつかのパターンに従います。4xxエラーが出たら、リクエスト、認証情報、または設定を変更する必要があります。同じ呼び出しを再送信しても、たいてい何も直りません。

• リクエストの入力をログに残す。モデルID、プロンプトのハッシュ、パラメータ（ログのベストプラクティスはAI APIチュートリアルを参照）。
• タスクID、最終ステータス、predict_time、エラーメッセージ全文をログに残す。
• 重複レンダリングとコスト倍増を避けるため、タスク状態を確認した後で429と5xxのみリトライする ^[3]。
• predict_timeのスパイクに注意する - インフラ劣化の初期サインになり得ます ^[3]。

よくある質問

動画ジョブが実際に失敗したかどうかはどうすればわかりますか？

ジョブを送信したときに得たタスクIDでタスクステータスエンドポイントをポーリングします。statusフィールドがfailedとして返ってきたら、そのジョブは通っていません。

次に、レスポンスのerrorフィールドを見ます。それが失敗の理由を教えてくれるので、次に何をするか判断できます。

• プロンプトを調整する
• アカウント残高を確認する
• インフラの問題であれば待つ

ジョブがfailed状態に入ったときに自動通知を受け取るために、webhookを使うこともできます。

テキスト→動画APIのリクエストはいつリトライすべきですか？

429レート制限や500サーバー側の問題のような一時的なエラーは、指数バックオフでリトライします。これにより再試行が遅くなり、システムを叩き続けるのを避けられます。

504 Gateway Timeoutやタスクの失敗の場合は、再試行する前にタスク状態を確認します。むやみなリトライは重複レンダリングを引き起こし、余分なコストを追加しかねません。

400や401エラーはリトライしないでください。これらはたいてい、まずリクエスト自体を修正する必要があることを意味します。

なぜプロンプトは送信後にブロックされることがあるのですか？

プロンプトがブロックされるのは、たいていプロバイダーのセーフティまたはモデレーションのルールに引っかかるからです。それは送信した瞬間に起こることもあれば、システムが禁止された映像や音声コンテンツを検出した場合に、後の生成中に起こることもあります。

よくあるトリガーには、センシティブな話題、暴力、未成年者、著作権保護された素材が含まれます。そしてモデレーションシステムは安全側に倒しがちなので、無害なプロンプトでもフラグが立つことがあります。

そうなった場合は、より中立的で描写的な言葉でリクエストを書き直しましょう。