# API リクエストがタイムアウトしたときに動画ジョブの重複を防ぐには？ > 出力ごとに安定した操作キーを割り当て、送信前に要求を永続化し、対応時は文書化されたプロバイダーの冪等性を使い、曖昧なタイムアウトを照合してから再試行します。タイムアウトは拒否を意味せず、結果が不明であることを意味します。 # API リクエストがタイムアウトしたときに動画ジョブの重複を防ぐには？ 送信タイムアウトは曖昧な結果を作ります。要求がサービス到達前に失敗した可能性、到達後に拒否された可能性、リモート動画ジョブを作成したものの応答だけが戻らなかった可能性があります。直ちに再試行すると、1 本の予定動画が 2 回の有料生成になるかもしれません。 解決策は、動画 API の周囲に冪等な操作層を設けることです。意図した操作を先に作成して保存し、安定したキーを与え、各試行を記録し、文書化された冪等性や検索機能を使います。結果を証明できなければ、失敗扱いではなく明示的な不明状態へ移します。 ## 1 つの意図した副作用を定義する 冪等キーは個別の HTTP 試行ではなく、ユーザーが作成を求めたものを識別します。再試行ごとに新しいキーを作ると、プロバイダーは重複を認識できません。 カタログ処理の操作は次の要素で定義できます。 * 商品 ID * クリエイティブテンプレート版 * ソースメディアのフィンガープリント * プロンプト版 * locale * アスペクト比 * バリエーション名 固定されたキー順と正規化済み値で標準表現を作り、ハッシュを計算します。読みやすい要素とハッシュを保存します。ユーザーが独立した新規生成を意図した場合は、同じプロンプトでも新しい操作またはバリエーションを作ります。 再試行ループ内でランダム UUID を作らないでください。最初の要求前に操作キーを作り、その副作用が終了状態になるまで再利用します。 ## 送信前に永続化する ネットワーク呼び出し前にローカル DB が操作を認識している必要があります。API 副作用に対する先行書き込みです。 | フィールド | 目的 | |---|---| | 操作キー | ローカルの重複意図を防ぐ | | 要求ハッシュ | 送信パラメータを証明 | | 状態 | 準備、送信、不明、完了を区別 | | 試行回数 | 上限付きポリシーを適用 | | プロバイダーとモデル | 経路と照合に使用 | | リモートジョブ ID | 再送せず照会再開 | | 最新エラー | 診断情報を保持 | | 出力チェックサム | 重複または変更を検出 | 操作キーに一意制約を設けます。2 つの worker が同じ操作を作ろうとしても、1 つのレコードへ収束させます。送信前に原子的更新またはリースで取得します。 ## 文書化された範囲で冪等性を使う 一部の API は冪等キーを受け取り、同じキーの再送時に最初に受理した結果を返します。エンドポイント、保持期間、パラメータ比較、エラー挙動が明示されている場合に最も有効です。 次を確認します。 * 動画生成エンドポイントがキーに対応するか * どれくらい保持されるか * 同じキーと異なるパラメータが拒否されるか * 再試行で元のリモート ID が返るか 決済や同期テキストで使える header が非同期動画にも適用されるとは限りません。OpenAI 互換の要求形式だけで、ジョブ作成が自動的に冪等になるわけではありません。 ## タイムアウトを不明結果として扱う 期待ではなく証拠に基づく状態を使います。 | 状態 | 証拠 | 次の処理 | |---|---|---| | `prepared` | ローカル記録あり、未送信 | 送信 | | `sending` | worker が呼び出し開始 | 結果またはタイムアウトを待つ | | `accepted` | リモート ID を受領 | 照会 | | `unknown` | 確認なしでタイムアウト | 照合 | | `failed` | 明示的拒否または終了失敗 | 失敗方針を適用 | | `complete` | 出力を永続保存 | 既存結果を返す | `unknown` と `failed` の違いが重要です。ネットワーク例外はクライアント接続の証拠であり、プロバイダー側処理の証拠ではありません。 クライアント参照やメタデータが使えるならローカルキーを付け、後の一覧やサポート照会で検索できるようにします。 ## 再試行前に照合する 照合 worker が不明操作を調査します。 1. 障害前にリモート ID が保存されたか確認する。 2. 対応時は冪等キーまたはクライアント参照で検索する。 3. 作成時刻、モデル、要求指紋で限定した一覧を検索する。 4. タイムアウト後に届いた webhook を確認する。 5. 十分早く出る場合は利用量や請求イベントを比較する。 6. ジョブ不存在を証明できるか、冪等性で安全な場合だけ再試行する。 時刻とプロンプトだけの照合は誤判定を起こします。複数属性を使い、不確実ならレビューへ送ります。検索も冪等性もない場合、待機、重複受容、費用と期限に基づく人の判断が必要です。 ## 転送再試行と生成再試行を分ける HTTP ライブラリはネットワークエラーを自動再試行することがあります。読み取りには便利ですが、副作用のある POST には危険です。安定キーと文書化された対応がなければ無効にします。 2 種類のカウンターを使います。 * 同じ保護済み操作を送る転送試行 * 終了失敗や品質拒否後に代替出力を作る生成試行 転送再試行は同じリモートジョブへ収束します。生成再試行は新しい有料クリエイティブ試行で、元の制作ジョブに紐づけつつ別 ID を持ちます。 ## リースで同時 worker を制御する タイムアウトだけが重複原因ではありません。2 つの worker が同じ項目を取ったり、遅い worker がリース切れ後も実行したりします。 所有者、取得時刻、期限を含む原子的リースで取得します。送信前に所有権と既存リモート ID の不在を確認します。リモート ID はトランザクションまたは条件付き更新で保存し、他 worker が進めていたら失敗させます。 古い worker が書き込み得る場合は fencing token を使います。取得ごとに版を増やし、DB は最新版だけを受け入れます。 ## webhook とポーリングを収束させる 非同期ジョブでは同じ遷移を webhook と照会が報告します。ハンドラーも冪等にします。 イベント ID で重複排除し、`processing` が `complete` を後退させない条件付き更新を使います。同じ出力の再ダウンロードは決定的な一時キーへ書き、チェックサムを検証して 1 つの最終オブジェクトへ収束させます。 ```text 完了イベントを受信 リモート ID で操作を検索 決定的な保存キーへコピー メディアとチェックサムを検証 永続 URI を記録 未完了なら完了へ更新 ``` どの手順で落ちても、次のハンドラーは新しい動画を作らず再開できます。 ## 重複監査に十分な証拠を記録する 送信前後の時刻、タイムアウト種別、要求ハッシュ、冪等キー、レスポンス header、リモート ID、再試行判断を保存します。資格情報と機密データはマスクします。 | 指標 | 分かること | |---|---| | 不明送信 | ネットワークまたはプロバイダーの曖昧さ | | 再試行なしで照合済み | 回避した重複 | | 保護済み再試行 | 障害時の冪等挙動 | | 重複疑いジョブ | 残存する財務リスク | | 重複チェックサム | 同一または繰り返し出力 | | 不明状態の時間 | 復旧速度 | 不明結果が増えたら、上限を増やす前に原因を調査します。ネットワーク悪化と積極的な再試行の組み合わせは費用を急増させます。 ## プロバイダー挙動をアダプターに閉じ込める マルチモデルアプリは能力フラグを持つ内部送信インターフェースを提供します。アダプターが schema、冪等性、検索、状態マッピング、出力抽出を担当します。 [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=avoid-duplicate-video-jobs-api-timeout) は、OpenAI 互換の単一プラットフォームでテキスト、画像、動画を使うチームの統合作業を減らせます。それでも正確なモデルとエンドポイントの現在の挙動を確認します。互換性は非同期ジョブの普遍的な冪等性を保証しません。 受理済みとリモート ID、明示的拒否、結果不明など正規化した結果を返します。転送例外をプロバイダー失敗へ変換しないでください。 ## 曖昧なケースを意図的に試験する 本番前に、送信前、バイト送出後、受理後、応答受信後で DB 更新前、webhook 配信中に障害を注入します。 冪等性がある場合、1 操作が最大 1 リモートジョブになることを確認します。ない場合は `unknown` に入り、自動再送が止まり、判断に十分な証拠が出ることを確認します。 同時 worker、期限切れリース、遅延または重複 webhook、再起動、古いキーと変更パラメータも試験します。請求書で重複を発見するより安価です。 ## まとめ 各出力へ永続的な操作キーを与え、その操作を HTTP 試行と分離します。送信前に意図を保存し、文書化された冪等性を使い、タイムアウトを照合が必要な不明結果として扱います。リース、条件付き状態更新、冪等ハンドラー、永続ログにより、再試行は重複購入ではなく制御された復旧になります。 ## FAQ ### HTTP タイムアウトは動画 API がジョブを作らなかったことを意味しますか？ いいえ。クライアントが応答を受け取れなくても、プロバイダーが要求を受理してジョブを作っている場合があります。照合が終わるまで結果不明として扱います。 ### 冪等キーは何を表すべきですか？ 商品、テンプレート版、locale、アスペクト比、バリエーションなど、1 つの意図した副作用を表します。その操作の再試行では同じキーを使い、本当に新しい出力には新しいキーを使います。 ### DB の一意制約ですべての重複を防げますか？ ローカルの重複操作は防げますが、プロバイダーが 2 つの要求を受理することまでは防げません。プロバイダーの冪等性または照合手順と組み合わせます。 ### すべてのタイムアウトを自動再試行すべきですか？ いいえ。要求が冪等、またはリモート結果を判定できる場合だけ安全です。それ以外は不明状態にして先に照合します。 ### 冪等性の記録はどれくらい保持すべきですか？ 再試行期間、プロバイダーの検索期間、請求異議期間、監査要件をすべて満たす期間です。文書化された挙動と事業リスクに合わせます。 ### OpenAI 互換 API なら全動画モデルで同じ冪等性が保証されますか？ いいえ。トランスポートは共通化できても、非同期ジョブ作成と冪等性はモデルやプロバイダー固有の場合があります。現在のエンドポイント資料を確認してください。