バッチAI生成API：安全な送信・ポーリング・検証

バッチ生成クライアントは、全プロンプトを同時送信するループではなく、記録を持つキューとして作ります。各項目には安定したローカルID、model_id、検証済みinput、送信状態、task_uuid、時刻、終端状態、output、エラー詳細が必要です。NamiFusion Marketplace REST APIはPOST /api/v1/marketplace/run/{model_id}で一件を送信し、task_uuidとstatusを返します。その後GET /api/v1/marketplace/run/tasks/{task_uuid}をcompleted、failed、cancelledまで読みます。非同期なので中断後に再開でき、長い生成で一つのリクエストを保持しません。

契約確認と入力準備

API Keysページでキーを作り、ソース管理外に保存します。バッチ前にGET /api/v1/marketplace/modelsで有効モデルを探し、GET /api/v1/marketplace/models/detail?model_id={model_id}で現在のparametersを読み、そのスキーマからリクエストを作ります。必須項目は必ず含め、任意項目は意図的に設定するか適用可能な既定値がある場合だけ含めます。prompt、size、seed、メディアキーが全モデル共通とは限りません。メディアは現在のパラメータが示す形式で渡します。通常は到達可能なURLを使い、そのパラメータがbase64の自動アップロードを明示的にサポートする場合だけbase64を送ります。

クレジット消費前にバッチを正規化します。重複ローカルID、空の必須プロンプト、非対応URL、検証スキーマとmodelが違う行を拒否します。正規化リクエストのダイジェストを保存し、誤重複を検出できるようにします。混在入力はモデル別キューに分けます。検証、時間、費用、並列方針が異なるためです。各モデルで一件のカナリアを実行し、出力契約を確認してから残りを解放します。

一件を正しく送信・照会する

リクエスト本文ではモデル項目をinput内に置きます。MODEL_IDと例の項目はライブのモデル詳細に合わせて置き換えます。成功応答のtask_uuidを最初に永続化します。モデル経路ではなくタスク経路を照会し、completed、failed、cancelledでのみ停止します。completedのoutputが常にURL一件とは仮定せず、現在の応答形を検証します。failedまたはcancelledの終端応答も診断用に保存します。認証はAuthorization: Bearer YOUR_API_KEYまたはX-API-Keyです。実キーをコード、ログ、画面、クライアントJavaScriptに置かないでください。

# 1) Submit — returns { "task_uuid": "...", "status": ... }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/MODEL_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"prompt":"A precise, model-compatible prompt"}}'

# 2) Poll until status is completed, failed, or cancelled
curl "https://www.namifusion.com/api/v1/marketplace/run/tasks/TASK_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

一件処理を制限付きバッチへ拡張する

1. 全行を送信せず読み込み・検証します。
2. カナリア一件を送り終端出力を確認します。
3. 行ごとではなく小さなworker poolを使います。
4. 各行をまずsubmittingとして保存し、送信後task_uuidとsubmittedを保存します。送信後の通信失敗は曖昧なので、再送前に記録とタスク一覧を確認します。
5. 実行中UUIDを適度な間隔とjitterで照会します。
6. 429の待機指示に従い、一時的5xxはbackoffします。
7. 終端タスクの照会を止めます。
8. API状態と内容レビューを別に記録します。
9. ローカルID、model、request digest、task_uuid、状態、output、レビュー結果のmanifestを出力します。
10. 再起動後は未完了行だけ再開します。

出力検証と失敗診断

API成功はプロバイダーが処理を完了した意味で、企画適合の意味ではありません。期待出力が存在し到達可能か確認し、形式、寸法または時間、破損、用途別ルールを検査します。画像は人体、文字、人物、構図、動画は冒頭の忠実度、時間的歪み、音声、終了フレームを確認します。原因分類後だけ再試行します。無効パラメータはスキーマまたは入力を修正し、内容不良はプロンプト、参照、モデル、設定を修正します。一時的障害は遅延再試行できます。失敗を繰り返し再送せず、完了したが不採用の出力は元との来歴を持つ意図的な新改訂にします。

レート、費用、運用上の制約

Marketplace実行はクレジットを前払いで消費します。価格、パラメータ課金、処理時間、タイムアウト、出力形式はモデルごとに違うため、現在のモデル詳細を取得し、解放前に推定バッチ合計を運用者へ示します。API key呼び出しはアカウント共通の毎分枠を使い、明示設定したrate_limit_per_minuteも適用される場合があります。普遍的な並列数を固定せず設定可能にし、429時は下げ、サーバー指示に従います。最大試行数、スケジューラ側のバッチ支出上限、停止スイッチを設けます。照合完了まで生タスク記録を残します。長いモデルではtask_uuidを保って後で続け、クライアント期限を失敗の証拠にしません。