本番前チェックリスト

デモならリクエスト 1 回で足りますが、プロダクトはタイムアウト、重複した Webhook、期限切れのリンク、漏れたキーに耐えなければなりません。公開前にこのリストを確認してください。

キー

• キーはサーバーのシークレット管理にあり、ブラウザーやアプリのバンドルには入っていない。
• 環境ごと・サービスごとに別のキーを使い、1 つだけ無効化できる。
• 本番のキーは使うモデルだけに絞り、1 日の利用上限を設定している。
• 停止なしでキーをローテーションする方法を知っている（認証）。

タスクの作成

• すべての createTask に、自分のジョブ ID から作った Idempotency-Key を付け、一度だけ生成して再試行のたびに使い回している。
• 再試行するのは 429、500、503、50301 だけで、バックオフと Retry-After を守っている（エラー）。
• 400 や 40004 など「リクエストを直すべき」エラーは、再試行せずに表示またはログに残している。
• 価格を見せるなら、先に見積もって quoteId と expectedCredits を渡し、40901 に対処している。
• 残高不足（40201）が、ユーザーより先に担当者へ届く（アラート、メール、バナーなど）。

結果の受け取り

• タスクに callBackUrl を付け、エンドポイントで署名を検証し、古いタイムスタンプを拒否している。
• Webhook のハンドラーはすぐに 2xx を返し、処理はバックグラウンドで行っている。
• 重複した配信は request_id で無視している。
• Webhook が届かなかったタスクを定期的に読み直している。
• succeeded、failed、expired、canceled 以外の状態は「まだ実行中」として扱っている。

ファイル

• 完成したファイルは、約 20 分で切れる署名付き URL を参照するのではなく、自分のストレージ（またはアセットライブラリ）にコピーしている。
• 保存しているのは署名付きリンクではなく taskId。
• ダウンロードのコードが署名付き URL に API キーを送っていない。
• 参照ファイルは、ファイルそのものを指す公開 HTTPS リンク、アップロード、アセットのいずれかで、共有ページではない。

費用

• 各モデルの料金単位（画像ごと、秒ごと、リクエストごと）と、料金を上げる設定を把握している。
• プレビューやテストは最も安い解像度と最短の長さで行っている。
• 暴走したループが残高を使い切る前に止まるよう、利用上限を設けている。
• 見積もり額がそのまま請求されたと思い込まず、credits と settled を確認している。

監視

• 失敗のたびに request_id、taskId、code、errorCode をログに残している。
• モデルごとの failed の割合を見ている。急に増えたら、たいていプロンプト・入力・モデルのどれかが変わっている。
• モデルごとに createTask から Webhook までの時間を追い、外れ値でアラートを出している。
• API コンソールのログと利用状況のページの場所を、チームの誰かが知っている。

コンテンツ

PopNow は一般向けのサービスです。モデルにはそれぞれのコンテンツルールがあり、断られたリクエストは content_rejected で失敗します。ユーザーがプロンプトを書くなら、生のエラーをそのまま見せず、なぜ断られたのかを自分の画面で伝え、書き直せるようにしてください。