キュー・制限・再試行
H3 動画タスク API · /api/v3
キューと同時実行
| ルール | 動作 |
|---|---|
| 同時実行数・送信 RPM・待機件数 | 顧客アカウントとモデルの組み合わせで集計します。同一アカウントのキーは上限を共有します。 |
| 取得の制限 | 単一取得 20 QPS、一覧 1 QPS、キャンセル・削除 20 QPS。それぞれアカウント内で共有します。 |
| 実行順序 | アカウントを公平に巡回し、300 秒以上待機したタスクを保護したうえで、priority と作成順に割り当てます。実行中の推論は中断しません。 |
| 容量とキュー | 検証済み仕様のリクエストを永続キューに保存し、GPU の使用中や一時的なオフライン時は待機します。待ち時間の予測が長いだけでは拒否しません。アカウントの送信頻度・待機件数・安全上限に達すると 429 を返す場合があります。 |
同時実行数と待機件数は管理者が設定します。新規アカウントの既定値は待機 200 件、毎分 180 件の送信です。待ち時間の予測は完了時刻を保証しません。キーを増やしてもアカウント上限は回避できません。
安全な再試行
Idempotency-Key: customer-video-20261102-001同じアカウント・キー・リクエストでは元のタスクを返し、重複受付しません。同じキーで異なるリクエストを送ると 409 を返します。新しいタスクには新しいキーを使用します。
429 / 503 では、次のヘッダーに従います： Retry-After。ジッター付き指数バックオフを使用します。取得に失敗した場合は取得のみ再試行します。作成がタイムアウトした場合は、元の冪等キーで同じリクエストを再試行し、別のタスクを新規作成しないでください。
有効期限と通知
| 時間・通知 | 説明 |
|---|---|
| タスクの有効期間 | 受付から待機時間を含めて計算します。既定値は 172800 秒、設定範囲は 3600～259200 秒で、プラットフォーム上限が適用されます。 |
| 動画リンク | 生成が完了して配信可能になってから固定で 1 時間有効です。取得しても更新されず、期限切れ後の成功タスクでは URL が null の場合があります。 |
| タスク記録 | 作成から 7 日間。キャンセル済み記録は 24 時間保持します。 |
| HTTPS コールバック | callback_url には queued、running、終端状態のスナップショットを送信します。中間状態は 1 回、終端状態は最大 3 回送信を試行します。2xx 応答で配信成功とみなします。 |
コールバックは重複したり順不同で届いたりします。タスク ID と終端状態で重複排除し、取得 API の結果を正としてください。イベントを保存して速やかに 2xx を返し、その後非同期で処理します。コールバック URL に API キーを含める必要はありません。
タスク完了コールバックの受信
{
"callback_url": "https://YOUR_APP_HOST/webhooks/fablun"
}本文は単一タスク取得と同じ構造です。成功時の動画 URL は次の項目から取得します： content.video_url 。タイムアウトは 5 秒です。終端状態の配信失敗時は約 5 秒、15 秒後に再試行し、初回を含め最大 3 回です。受信失敗で生成がキャンセルされたり、再課金されたりすることはありません。
| リクエストヘッダー | 用途 |
|---|---|
| X-Fablun-Timestamp | 署名タイムスタンプ（秒） |
| X-Fablun-Signature | sha256= に続く HMAC-SHA256 の 16 進数署名 |
| X-Fablun-Event-ID | 受信側の重複排除に使う固定イベント ID |
署名対象： timestamp + "." + 生のリクエスト本文。アカウントのコールバック署名シークレットを使用し、定時間比較とタイムスタンプの検証を行います（推奨許容幅は 5 分）。シークレットはアカウント所有者のみ閲覧できます。管理者がリセットした場合は受信側も更新してください。互換性のため旧 X-Nabit-Timestamp、X-Nabit-Signature、X-Ravenzet-Event-ID も送信しますが、新規導入では X-Fablun ヘッダーを使用してください。シークレットは「組織 → タスクコールバック」で確認できます。