flux-3-generate

FLUX 3 Generate

非同期 API を通じて準備済みのプランを実行し、有効期限のある成果物を保持して、MP4 を検証します。リクエストを作成する前にFLUX 3 API referenceをお読みください。このスキルの記述と異なる場合は、API reference が優先されます。BFL_API_KEY の値を x-key ヘッダーで認証に使用します。変数が存在することを値を表示せずに確認し、キーをプロンプト、ログ、保存するリクエストボディに決して含めないでください。

リクエストの形式

すべてのリクエストで mode（必須、文字列は完全一致）を指定し、対応するメディアフィールドを含めます。

mode	メディアフィールド	モデルの動作
t2v	なし	テキストのみからクリップを生成します
i2v	keyframes（必須）	画像をピクセル単位でそのまま固定フレームとして画面に配置します
v2v	start_video（必須）	クリップの最終フレームから続きを生成します
draft_enhance	draft_cache（必須）	キャッシュされたドラフトをフル品質で再生成します。他のフィールドは prompt も含めて受け付けません

• スキーマは厳密です。認識されないフィールドがあると、そのフィールド名を示す 422（Extra inputs are not permitted）が返されます。必須フィールドが欠けている場合も同様に 422 が返されます。
• 生成モードの設定：aspect_ratio（auto、21:9、2:1、16:9、4:3、1:1、3:4、9:16）、duration（整数の 5～20、または "auto"）、resolution（hd または fhd）、generate_audio（ブール値）、draft（ブール値）、version。
• 制約は相互に影響します（例：高解像度の動画入力では、長さが制限される場合があります）。各フィールドが独立していると決めつけず、リファレンスをお読みください。
• キーフレームを 3 枚以上、単独で指定する場合、およびすべての [seconds, image] 形式のタイムスタンプ付きキーフレームでは、整数の duration が必要です。メディアは公開 URL またはインラインの base64 で渡します。キーフレーム画像は少なくとも 256x256 にしてください。

ジョブの実行

1. 一度だけ送信します。 返されたタスクの id と polling_url を、秘密情報を含まないリクエストとともに保存します。
2. 6 秒ごとにポーリングし、x-key ヘッダーを付けてリダイレクトに従いながら、終端状態になるまで続けます。複雑なブリーフではプランニングに時間がかかるのが通常であり、処理が停止したわけではありません。API のステータス文字列は完全一致です。Pending、Reasoning、Generating ではポーリングを続けます。Ready（成功）、Error、Request Moderated、Content Moderated、Task not found（失敗）では停止します。これらの終端ステータスが後から Ready になることはありません。
   • 送信時の 429 は、組織の同時実行上限に達しており、タスクが作成されていないことを意味します。ポーリングするものはありません。空きができるまで待ち、同じボディを再送信してください。
   • ポーリング時の 429 は、タスクが存在し、そのまま処理されていることを意味します。バックオフして、同じ polling_url へのポーリングを続けてください。再送信はしないでください。2 回目のレンダリング料金が発生します。
   • 503：上限を設けたバックオフを行います。
3. すぐにダウンロードします。 観測された署名付きサンプル URL とドラフトキャッシュ URL は、結果が Ready になってから約 1 時間で期限切れになります。URL 自体の se= クエリパラメーターが正式な有効期限です。固定の時間を決めつけず、その値を確認してください。動画出力はリストである result.samples に含まれます。ドラフトバンドルは、こちらもリストである result.draft_caches に含まれます。単数形の result.draft_cache はそのリストの最初の要素であり、全要素ではありません。両方のリストのすべての要素を反復処理し、他の作業に移る前にすべてダウンロードして、各要素のローカルパスとタスク ID を記録してください。単数形の result.draft_cache キーだけを読むクライアントは、有効期限切れ後に復元できない支払い済みの成果物を、気付かないまま取りこぼします。ダウンロードしたファイルに加えて、タスク ID とステータスも保存してください。
4. 検証します：コンテナがデコードできること、長さ・解像度・アスペクト比が意図どおりであること、音声が要求した場合にのみ含まれていることを確認します。技術的に有効であることは、クリエイティブ面で承認されたことを意味しません。専門的な確認は担当するスペシャリストに依頼してください。

下書き

コンセプトが未検証の間は draft: true を追加してください。ステップ数を抑えた高速プレビューと draft_cache の組み合わせなら、フルレンダリングよりも大幅に低コストです。下書きは、イベントの判読性、構図、連続性を基準に評価してください。低ステップによるトレードオフとして映像がぼやけますが、フル品質では解消されます。選んだキャッシュのみを高品質化してください（同じ生成を再生するため、複数のキャッシュがある場合は、下書きとキャッシュの対応関係を維持してください）。

再実行するたびに、重要な要素を1つ変更してください。構造が似た結果が2回続けて得られなかった場合は、形容詞を増やすのではなく、クリエイティブスキルに戻ってください。

参考資料

• references/api-quick-reference.md