black-forest-labs-flux

Black Forest Labs FLUX で画像を生成する

作業全体で、次の根拠表記を使用してください。

• [Documented] は、BFL のドキュメント、BFL のモデルカード／リポジトリ、BFL の法的条項、または BFL が執筆した論文に記載されている事実を意味します。
• [Inference] は、文書化された事実から導ける結論ですが、BFL が直接述べているわけではないことを意味します。
• [Heuristic] は、実際の出力で検証する必要がある、本番運用向けのアドバイスを意味します。

すべてのエンドポイント名、上限、価格、ライセンス、利用規約は変更される可能性があるものとして扱ってください。以下の情報は 2026-07-09 に確認したものです。重大な影響を伴う実行の前に、最新の BFL API リファレンス、リリースノート、モデルカード、適用されるライセンスを再確認してください。

実行環境を混同しない

パラメーターを選択したり権利について述べたりする前に、実行環境を特定してください。

1. BFL 公式 API — リクエストは x-key を付けて、公式の api.bfl.ai エンドポイントに送信します。BFL がリクエストスキーマ、モデレーション、課金、非同期の結果契約、サービス利用規約を定めます。[Documented: D1, D2, D9]
2. サードパーティのホスト型ゲートウェイ — モデルのスラッグ、受け付けるパラメーター、保持、モデレーション、価格、バージョン固定を定めるのは、BFL の公式 API ではなくゲートウェイです。BFL のフィールドや上限がそのまま使えると思い込まないでください。プロバイダーの最新ドキュメントと契約を確認してください。[Inference]
3. ローカル／オープンウェイトでのデプロイ — 重みと推論は、チェックポイント固有のライセンスに基づくインフラストラクチャ上で実行されます。BFL API のモデレーション、保持ポリシー、署名付き結果 URL は自動的には適用されません。フィルタリング、来歴管理、ストレージ制御、容量計画を自分で実装してください。[Documented: D10, D11]

ダウンロード可能な FLUX チェックポイントをすべて「オープンソース」と呼ばないでください。FLUX.2 [klein] 4B は Apache-2.0 ですが、FLUX.2 [klein] 9B と FLUX.2 [dev] は、商用の重みライセンスが適用される場合を除き、FLUX Non-Commercial License の対象となるダウンロード可能なオープンウェイトです。[Documented: D10]

用途に応じてモデルファミリーを選択する

現行の FLUX.2 の選択肢

ニーズ	選択肢	実行環境と重要な事実
本番環境での生成／編集の大半	FLUX.2 [pro]	BFL が推奨する出発点です。公式 API のエンドポイントには、変更される可能性がある flux-2-pro-preview と、固定された flux-2-pro があります。API では最大 8 個、BFL のプレイグラウンドでは最大 10 個の参照画像を利用できます。[Documented: D1, D2]
最も難しい編集、最も高い指示への忠実度、最高の最終品質	FLUX.2 [max]	公式 API／プレイグラウンドで利用でき、API では最大 8 個の参照画像を利用できます。グラウンディング検索を備えた FLUX.2 の選択肢です。その品質や最新コンテキスト機能がコストに見合う場合にのみ使用してください。[Documented: D1, D2]
タイポグラフィ、小さなディテールの保持、サンプリングの調整	FLUX.2 [flex]	公式 API で利用できます。guidance は 1.5～10、steps は 1～50 に設定できます。プロンプトのアップサンプリングと、API で最大 8 個の参照画像をサポートします。guidance を高くすると、指示への忠実度と引き換えにリアリズムが低下することがあります。[Documented: D1, D2]
レイテンシーを重視したプレビュー、対話型ツール、大量処理	FLUX.2 [klein] 4B または 9B	公式 API とダウンロード可能な重みを利用でき、最大 4 個の参照画像を使えます。プロンプトのアップサンプリングには対応していないため、必要な情報をすべて含むプロンプトを作成してください。4B は Apache-2.0、9B は別途ライセンスが付与されない限り FLUX NCL の対象です。[Documented: D1, D10]
サンプリングを全面的に制御したローカル環境でのカスタマイズや研究	FLUX.2 [dev] または [klein] Base チェックポイント	ローカル／オープンウェイトでの実行であり、BFL の公開 API ではありません。BFL は [dev] で参照画像を最大 6 個までとすることを推奨しています。蒸留版の klein は少ないステップで本番環境に利用できる一方、Base バリアントはファインチューニングと多様性のために完全な学習信号を保持しています。正確なチェックポイントのライセンスを確認してください。[Documented: D1, D10]

プレビューエンドポイントの基盤モデルが変わっても問題ない場合に限り、最新の品質や速度を確認する目的で使用してください。回帰テストのベースライン、承認、コンプライアンス上、再現性が重要な用途には固定エンドポイントを使用してください。プレビューではリクエスト契約が同じでも出力が変わることがあります。[Documented: D1, D12]

特殊なパスとレガシーパス

• マスクによる削除と背景の再構成には、FLUX Eraseを使用します。消去の指示は固定されており、呼び出し側からセマンティックプロンプトを指定する必要はありません。[文書化済み：D7]
• キャンバスを拡張するには、FLUX Outpaintingを使用します。現在の直接エンドポイントでは、highとfastのモードを利用できます。[文書化済み：D7]
• 黒／白またはアルファマスクを、指定したプロンプトの内容で塗りつぶす必要がある場合は、**FLUX.1 Fill [pro]またはライセンス取得済みのFill [dev]**を使用します。現行のAPIリファレンスでは、引き続きレガシーパスとして扱われています。[文書化済み：D7、D10]
• 承認済みの反復編集ワークフロー、または互換性の制約があるワークフローでは、**FLUX.1 Kontext [pro]/[max]**を引き続き使用します。BFLは新規プロジェクトにFLUX.2を推奨しています。BFLの論文では、Kontextの統合された生成／編集機能が裏付けられ、複数ターンにわたる一貫性が評価されていますが、それによって現行のデフォルトになるわけではありません。[文書化済み：D13]
• FLUX1.1 [pro]/Ultra/Raw、FLUX.1 [dev]/[schnell]、Depth、Canny、Reduxは、それぞれ固有のレガシーな動作、アダプター、またはデプロイ済みアセットが必要な場合に限り、引き続き使用します。固定済みのワークフローを無断で移行しないでください。並行して受け入れテストを実施してください。[文書化済み：D9、D10]

ブリーフを生成要件に変換する

プロンプトを作成する前に、次の項目を記録します。

• 最終的な用途、対象者、対象地域、および商用利用の有無
• 実行環境、エンドポイント／チェックポイント、バージョン戦略、ライセンス
• 出力数、サイズ／アスペクト比、形式、期限、コスト上限
• 被写体、動作／状態、環境、構図、スタイル／媒体、光、配色、必要なテキスト
• 譲れないアイデンティティ／製品／ロゴの形状と、変更可能な要素
• 各入力画像の所有者、同意の状況、用途、機密性、許可される変換
• テキスト、色、アイデンティティ、製品の形状、事実性、アーティファクトに関する受け入れテスト

モデルのライセンス、入力の権利、同意、または要求された表現について未解決の問題がある場合は、作業を中止してください。プロバイダーがリクエストを受け付けたことを、公開許可が得られたと解釈しないでください。

目に見える完成状態をもとにプロンプトを作成する

自然言語のプロンプトは、明確な視覚的描写として記述します。優先度の高い内容を先に書きます。次の順序が役立ちます。

画像の種類 + 被写体 + 動作／状態 + 構図 + 環境 + スタイル／媒体 + 照明 + 配色 + 素材／ディテール + 必要なテキスト

これは目安であり、必須の形式ではありません。出力の見た目を変えるディテールだけを追加します。FLUX.2は非常に長いプロンプトに対応していますが、BFLは短く始めて、有用な具体性を追加していく方法を推奨しています。[文書化済み：D3]

多くのFLUXパスでは有効なネガティブプロンプトを利用できないため、肯定的な置き換え表現を使用します。「人物なし」は「人影のない歩行者広場」に、「ぼかしなし」は「全体にピントの合った描写」に置き換えます。[文書化済み：D4]

複雑な自動化ブリーフでは、JSON形式の文字列をプロンプト値として渡します。文書化されていないトップレベルのJSON制御スキーマを独自に作らないでください。プロンプト内で使用できるキーには、scene、subjects、composition、camera、lighting、color_palette、style、textなどがあります。FLUXはこの構造を言語として解釈します。[文書化済み：D1、D5]

プロンプトの拡張

• [pro]/[max]では、プロンプトの拡張がデフォルトで有効です。文言をそのまま使用する必要がある場合は、disable_pup: trueを設定します。[文書化済み：D2]
• [flex]では、prompt_upsamplingで制御します。[文書化済み：D2]
• [klein]にはプロンプトの拡張機能がありません。視覚的な指示をすべて指定してください。[文書化済み：D4]
• [ヒューリスティック] 正確なブランドコピー、厳密に指定したレイアウト、管理されたA/Bテスト、修正用プロンプトでは拡張を無効にします。大まかなアイデア出しでは有効のままにします。

ダイレクト API の運用パターン

現在の FLUX.2 ダイレクトエンドポイントでは、次の手順で進めます。

1. prompt、任意の input_image から input_image_8（klein では _4 まで）、寸法、任意の seed、モデレーション設定、フォーマット、任意の Webhook フィールドを含む JSON を POST します。そのエンドポイントで文書化されているフィールドだけを使用してください。［文書化済み：D2］
2. id、polling_url、報告されたコスト、入力のメガピクセル数、出力のメガピクセル数を記録します。
3. 返された URL を Ready になるまでポーリングします。モデレーション、エラー、タスクが見つからない状態を明示的に処理してください。無期限にポーリングしてはいけません。
4. アセットを直ちにダウンロードします。BFL の署名付き結果 URL は 10 分間有効です。元のレスポンス、エンドポイント、プロンプト、パラメーター、入力ハッシュ、出力ハッシュ、タイムスタンプを保存してください。［文書化済み：D5、D9］
5. API キー、生の機密入力 URL、Webhook シークレットをログに記録してはいけません。設定済みのシークレットを使って Webhook コールバックを認証します。

任意の seed を指定すると再現性を高められますが、プレビューエンドポイントの変更、別のゲートウェイ、別のローカルランタイム、重みの変更があった場合に、ピクセル単位で同一の結果になると約束してはいけません。［文書化済み＋推論：D1、D2］

参照画像を使った編集を明確な仕様にする

参照画像が 1 枚の場合

編集内容と保持条件の両方を指定します。

紙のラベルをマットなネイビーブルー（色 #102A43）のラベルに置き換えてください。ボトルのシルエット、キャップ、ガラスの反射、カメラアングル、手の位置、影、背景は変更しないでください。

変更前と変更後の正確なテキストを引用符で指定します。例：「NORTH」を「EMBER」に置き換え、文字の高さ、ベースライン、カーニング、エンボス加工、遠近感を保ってください。 BFL は、テキストを引用符で囲み、変更内容と保持条件を正確に記述することを明示的に推奨しています。［文書化済み：D5］

複数の参照画像

プロンプトを書く前に、各画像に 1 つずつ役割を割り当てます。

入力	役割の例	保持する要素
image 1	ベースとなる構図	カメラ、背景、スケール
image 2	製品のアイデンティティ	シルエット、ラベルの形状、素材
image 3	人物のアイデンティティ	顔の構造、髪、肌の細部
image 4	衣装	カット、柄、トリム
image 5	スタイルの参照	パレット、コントラスト、テクスチャのみ

次に、それぞれの役割を明記します。image 1 をベースとなるシーンとして使用し、image 2 のボトルをテーブルに置いてください。image 3 の人物に image 4 のジャケットを着せ、image 5 のカラーグレーディングと粒状感だけを適用してください。 BFL は、「image 1」「image 2」のように各画像とその役割を指定することを推奨しています。［文書化済み：D6］

独立した情報をもたらす範囲で、参照画像はできるだけ少なくしてください。生成前に、矛盾するポーズ、照明、レンズ、アイデンティティ、スタイルの手がかりを解消します。BFL ダイレクト API の現在の上限は、[max]/[pro]/[flex] が 8 枚、[klein] が 4 枚、ローカル [dev] が推奨 6 枚です。[pro] ガイドには入力と出力を合計した 9MP の予算も記載されているため、出力解像度を上げると、使用できる参照画像の数が減ることがあります。［文書化済み：D1、D6］

［ヒューリスティック］ 入力インデックス、役割、クロップ、出所、ハッシュを記載したコンタクトシートを作成します。まずアイデンティティ／製品とスタイルの参照を別々に試し、それぞれの仕様が機能してから組み合わせます。

タイポグラフィ、色、レイアウトを制御する

タイポグラフィ

1. 埋め込みテキストや細部の表現が重要な場合は [flex] を優先します。最大限の一貫性が必要な最終編集には [max] を使用します。［文書化済み：D1、D2］
2. 正確な文言を引用符で囲み、プロンプトの前のほうに記述します。
3. 配置、階層、サイズのクラス、整列、フォントの特徴、色、素材を指定します。例：上部 3 分の 1 に、コンデンス体の太字サンセリフで、大きく中央揃えの見出し「MOVE LIGHT」を配置し、色は #F7F3E8、表面に平らに印刷してください。［文書化済み：D5］
4. 生成する文字列は短くします。必要に応じて、見出し、サブ見出し、CTA を別々のパスで生成してください。［文書化済み＋ヒューリスティック：D5］
5. 100～200％のズームで校正します。すべての字形、数字、句読点、ベースライン、改行、ブランド名の綴りを確認してください。
6. ［ヒューリスティック］ 法的表記、価格、長い本文、アクセシビリティ上重要なテキストについては、ビジュアル用の画像を生成し、最終的な文言はデザイン／合成ツールで決定論的に組版してください。

色

各 16 進コードを名前付きのオブジェクトまたはコンポーネントに割り当てます。パレットだけを提示して、決定的な割り当てを期待しないでください。BFL では、オブジェクトに紐づけた 16 進コードによる制御が文書化されています。[文書化済み：D1、D5]

プロンプトの例：Bottle body: color #0B3D2E. Cap: color #F2C94C. Wordmark "MOSS": color #FFFFFF. Background: uniform color #E9E3D5.

［ヒューリスティック］ 「正確な色」は制御に関する主張として扱い、色管理された成果物の証明とはみなさないでください。最終エクスポートファイルから複数のピクセルをサンプリングし、色空間／プロファイルと圧縮を確認してください。ブランドの許容範囲が契約で定められている場合は、後処理で修正してください。

構図とサンプリング

• 生成前に幅と高さを意図したフレーミングに合わせます。後からのクロップで構図を修正できると考えないでください。FLUX.2 の直接エンドポイントは柔軟な寸法を受け入れ、文書化されている場合は最大 4MP で出力します。[文書化済み：D1、D4]
• 必要な場合にのみ [flex] ガイダンスを使用します。指示が反映されない場合は少しずつ値を上げ、顔、素材、光が合成的になった場合は下げてください。[文書化済み＋ヒューリスティック：D2]
• プロンプトと参照画像が適切であることを確認してから、[flex] のステップ数を増やしてください。ステップ数を増やしても、矛盾する依頼は解決できません。[文書化済み＋ヒューリスティック：D2]
• プロンプトの変更を 1 つだけテストするときは、シード、寸法、エンドポイント、アップサンプリングの選択、入力を固定します。診断実行ごとに変更する変数は 1 つにしてください。[ヒューリスティック]

マスク駆動の操作を正しく使う

モデル名だけでなく、意味的な操作に基づいて選択します。

• オブジェクトを削除して背景を再構成する： FLUX Erase を使用します。同じサイズの白黒 PNG マスクを指定します。白は削除、黒は保持です。文書化されている dilate_pixels: 10 から始め、ハローやソフトエッジが出る場合は値を大きくします。現在の範囲は 0～25 です。[文書化済み：D7]
• 指定した内容で領域を塗りつぶす： FLUX.1 Fill [pro] の直接 API、または適切なライセンスを取得した Fill [dev] チェックポイントを使用します。同じサイズの白黒マスク（白＝インペイント、黒＝保持）またはアルファマスクに、変更後の状態を指定するプロンプトを添えます。[文書化済み：D7]
• 境界の外側へ拡張する： 現行の FLUX Outpainting を使用します。reference_offset_x / reference_offset_y でターゲットキャンバスと参照画像の配置を設定し、キャンバス外に配置された画像を auto_crop でクロップしてよいか、または 422 でジョブを停止するかを決めます。ディテールと一貫性を重視する場合は high、適したシーンで速度を重視する場合は fast を選択します。現在の fast モードでは、画像 URL ではなく base64 形式の画像入力が必要です。また、配置する参照画像は各辺が 64 px 以上、アスペクト比が 8:1 以下である必要があり、キャンバスと内部パディングの合計は 4 MP 未満でなければなりません。実行前に、現在の仕様を正確に確認してください。[文書化済み：D7]
• マスクを使わずに文脈に沿った変更を加える： 入力画像と、保持する対象を明示したリストを指定して FLUX.2 編集を使用します。[文書化済み：D5]

マスクのエッジをフル解像度で確認します。削除するオブジェクトに含まれる場合は、影、反射、接地部分、遮蔽された部分も含めてください。継ぎ目やハローが見える場合、多くはプロンプトより先にマスクや遷移の問題を疑うべきです。[ヒューリスティック]

失敗の種類ごとに反復する

失敗	まず診断すること	修正アクション
主題またはトリミングが違う	優先順位／順序またはアスペクト比	主題とフレーミングを先に指定します。コンテキストを簡素化し、最終寸法を設定します。
参照画像のアイデンティティが混ざる	役割が曖昧、または参照画像が多すぎる	各画像の役割にラベルを付けます。不要な参照画像を削除し、アイデンティティとポーズを別々に処理します。
指示していない部分が変わる	編集指示に維持する要素がない	維持する要素を簡潔に列挙します。1回の処理につき局所的な編集を1つ行い、QA後にのみ承認済みの出力を再利用します。
テキストのスペルが間違っている	コピーが多すぎる、階層が不適切、モデルが違う	[flex] または [max] に切り替えます。短いコピーを引用符で囲んで先に指定し、長いテキストは後工程で組版します。
ブランドカラーが合わない	Hex がオブジェクトに紐付いていない、または書き出しで変化した	コードをコンポーネントに紐付けます。アップサンプリングを無効にし、出力をサンプリングして、カラーマネジメントされた後工程で補正します。
[flex] の仕上がりが過剰になる	ガイダンスが強すぎる、またはプロンプトに情報を詰め込みすぎている	ガイダンスを弱め、一般的な品質を表す形容詞を削除します。ステップ数は維持してテストします。
マスクによる削除後にハローが残る	マスクがエッジ／影を含んでいない	マスクを広げるか、dilate_pixels を使用します。影／反射も含めて、Erase を再実行します。
インペイントの境目やテクスチャに不連続がある	マスクが狭すぎる、またはコンテキストが不十分	ローカルパイプラインでマスクをぼかす／広げます。プロンプトに周囲の素材／光を含め、Fill の制限を確認します。
複数ターンで品質が低下する	再エンコードの繰り返しと累積的な変化	最後に承認されたマスターに戻り、編集を分岐させます。変更しない領域を比較し、実用的であればローカルで合成します。
API の結果が消える	署名付き URL の期限切れ	10 分以内にポーリングしてダウンロードし、出力を直ちに保存します。
同じシードでも出力が変わる	プレビュー／モデル／ランタイムが変更された	エンドポイント／チェックポイントと環境を固定し、ハッシュを保存します。以前のシードは来歴情報の一要素にすぎないものとして扱います。

すべての不具合に対して、形容詞を追加することで対応しないでください。失敗の種類に応じて、曖昧さを減らす、変数を切り分ける、またはツール／モデルを変更してください。

本番用 QA を実施する

該当するゲートのいずれかに不合格となる出力は、却下するか修正してください。

• ブリーフ： 主題、動作、数、設定、アスペクト比、構図、感情的な印象が正しいこと。
• アイデンティティ／製品： 顔、シルエット、プロポーション、パッケージの形状、ロゴ、素材、特徴的なマークが安定していること。
• 編集： 指定されたピクセルが変更されていること。保護対象のコンテンツ、フレーミング、ライティング、影が許容できる範囲で維持されていること。
• タイポグラフィ： テキスト、大小文字、句読点、字形の整合性、改行、階層、安全マージンが正確であること。
• 色： 指定されたコンポーネントが意図した Hex の見た目になっていること。書き出し後、最終ファイルが測定可能な許容誤差を満たすこと。
• 解剖学／物理： 手、関節、反射、接地影、遠近法、オクルージョン、繰り返しの構造がもっともらしいこと。
• 技術： 必要なピクセル寸法、形式、アルファ、カラープロファイル、圧縮を満たし、境目、ハロー、バンディング、意図しないトリミングがないこと。
• シリーズ： キャラクター／製品、服装、パレット、レンズ、光、スタイルについて、コンタクトシート全体で一貫性があること。
• 権利／安全性： 入力の権利と同意が記録されていること。禁止された用途や誤解を招く用途がないこと。必要な場合は合成画像であることを開示していること。プライバシーおよび機密データの取り扱いが承認されていること。
• 来歴： エンドポイント／チェックポイント、サーフェス／プロバイダー、プロンプト、パラメーター、シード、入力／出力ハッシュ、モデル／ライセンスのバージョン、日付、人間による承認を保持していること。

現在の出来事や事実を含む画像については、描写されている主張をすべて個別に確認してください。FLUX.2 [max] のグラウンディング検索は、編集上のファクトチェック、情報源の来歴、実在の人物／出来事を描写する許可の代わりにはなりません。[文書化済み + ヒューリスティック：D1、D11]

権利、プライバシー、安全性

• すべての参照素材、ロゴ、製品画像、肖像、スタイル素材、データセットについて、所有権または使用許可を確認してください。BFL は、ユーザーに第三者の知的財産権、プライバシー権、パブリシティ権を尊重するよう求めています。［文書化済み：D11］
• 識別可能な人物を編集する場合は、明示的な許可を得てください。本人の同意のない親密な画像、有害ななりすまし、嫌がらせ、プライバシー侵害、または実際の出来事と誤認させる画像を作成しないでください。［文書化済み：D11］
• 現行の BFL Usage Policy に従ってください。同ポリシーでは、違法、虐待的、監視・生体認証関連、政治運動関連、有害な個人データに関するもの、差別的な重大な影響を及ぼすもの、誤解を招くものなど、さまざまな用途が制限されています。［文書化済み：D11］
• API の入出力に関するプライバシーは、契約上の問題として扱ってください。BFL が公開している API 規約では、サービスの運用と改善のために、BFL が入力と出力を広範に使用する権利を認めています。適用される契約および組織のポリシーで許可されていない限り、機密情報、規制対象の情報、またはクライアントの機微情報をアップロードしないでください。［文書化済み：D11］
• BFL は出力の所有権を主張しないとしていますが、出力の使用と第三者の権利についてはユーザーが引き続き責任を負います。また、出力の類似性と著作権保護の可否は、管轄地域や事実関係によって異なります。独占的な権利を約束しないでください。［文書化済み＋推論：D11］
• セルフホストする場合は、チェックポイントのライセンスをモデルの使用に厳密に適用してください。公開されている FLUX NCL では、ライセンスに準拠した出力は商用利用できますが、モデルや派生物を商用または本番用途で使用することは制限されています。必要な商用ウェイトライセンスなしに、NCL チェックポイントを有料製品や本番サービスとして運用しないでください。また、ライセンスで求められているフィルタリングまたはレビュー、開示の措置も実施してください。［文書化済み：D10］
• AI に関する開示と来歴情報を保持してください。公式の FLUX.2 リポジトリでは、不可視の透かしと C2PA 形式のメタデータが推奨されています。必要な来歴情報を削除しないでください。［文書化済み：D10］

完全な例

例 1 — API を直接利用した製品のキービジュアル

目的： ブランドカラーを制御し、短い見出しを入れた 4:5 のキャンペーン用マスターを作成します。

選択： 本番環境のスナップショットを固定するため、BFL の直接利用で flux-2-pro を使用します。タイポグラフィが繰り返しうまくいかない場合は、代わりに [flex] を使用してください。[max] は、プロンプトの有効性を確認し、最終品質の向上が必要な場合にのみ使用してください。

完全なプロンプト：

Premium studio product photograph of one reusable aluminum water bottle, centered slightly below frame with generous clean space above. Bottle body strictly color #0B3D2E, cap strictly color #F2C94C, small white wordmark "MOSS" printed horizontally on the front. The large headline "MOVE LIGHT" appears above the bottle in bold condensed sans-serif, color #0B3D2E, exact spelling and two words on one line. Warm off-white seamless background color #E9E3D5. Soft diffused key light from upper left, subtle grounded shadow to lower right, crisp product edges, realistic brushed aluminum, 85mm studio product photography, straight-on camera, no perspective distortion.

完全なリクエストと取得のパターン：

import hashlib, json, os, time, requests
from datetime import datetime, timezone
from pathlib import Path

PROMPT = """Premium studio product photograph of one reusable aluminum water
bottle, centered slightly below frame with generous clean space above. Bottle
body strictly color #0B3D2E, cap strictly color #F2C94C, small white wordmark
"MOSS" printed horizontally on the front. The large headline "MOVE LIGHT"
appears above the bottle in bold condensed sans-serif, color #0B3D2E, exact
spelling and two words on one line. Warm off-white seamless background color
#E9E3D5. Soft diffused key light from upper left, subtle grounded shadow to
lower right, crisp product edges, realistic brushed aluminum, 85mm studio
product photography, straight-on camera, no perspective distortion."""

headers = {
    "x-key": os.environ["BFL_API_KEY"],
    "Content-Type": "application/json",
    "accept": "application/json",
}
payload = {
    "prompt": PROMPT,
    "disable_pup": True,
    "width": 1280,
    "height": 1600,
    "seed": 240709,
    "safety_tolerance": 2,
    "output_format": "png",
}
job = requests.post(
    "https://api.bfl.ai/v1/flux-2-pro", headers=headers, json=payload, timeout=60
)
job.raise_for_status()
meta = job.json()
manifest = {
    "submitted_at": datetime.now(timezone.utc).isoformat(),
    "endpoint": "https://api.bfl.ai/v1/flux-2-pro",
    "request": payload,
    "submission_response": meta,
}
Path("moss-key-visual.manifest.json").write_text(
    json.dumps(manifest, indent=2), encoding="utf-8"
)

deadline = time.monotonic() + 300
while time.monotonic() < deadline:
    result = requests.get(meta["polling_url"], headers=headers, timeout=30)
    result.raise_for_status()
    body = result.json()
    if body.get("status") == "Ready":
        download = requests.get(body["result"]["sample"], timeout=60)
        download.raise_for_status()
        output_path = Path("moss-key-visual.png")
        output_path.write_bytes(download.content)
        manifest.update({
            "completed_at": datetime.now(timezone.utc).isoformat(),
            "retrieval_response": body,
            "output_sha256": hashlib.sha256(download.content).hexdigest(),
            "output_path": str(output_path),
        })
        Path("moss-key-visual.manifest.json").write_text(
            json.dumps(manifest, indent=2), encoding="utf-8"
        )
        break
    if body.get("status") in {"Error", "Request Moderated", "Content Moderated", "Task not found"}:
        raise RuntimeError(body)
    time.sleep(0.75)
else:
    raise TimeoutError(meta["id"])

理由： エンドポイントを固定することで回帰レビューが可能になります。コピーやレイアウトを保護するためアップサンプリングは無効にし、すべてのカラーコードをコンポーネントに割り当てています。寸法は納品時の縦横比に合わせています。

期待される結果： ボトルが 1 本、各コンポーネントの色が正確で、十分な余白があり、短い見出しが読みやすく、製品を引き立てる照明になっています。

想定される失敗と対処法： 見出しの字形がうまく生成されない場合は、同じプロンプトを使用し、guidance: 4.5 と steps: 40 を指定して [flex] に切り替えます。それでも不完全な場合は、後処理で組版してください。色が合わない場合は、書き出した PNG を確認し、カラーマネジメントされた工程で修正してください。

バリエーション： 見出しの指示を削除し、後続工程でタイポグラフィを確実に配置できるよう、文字のないクリーンプレートを生成します。

例 2 — 複数の参照画像を使ったキャンペーン用コンポジット

**意図：**既知の製品と人物を新しいシーンに配置し、スタイルの色調補正のみを取り入れます。

**入力：**画像 1 はベースとなる部屋、画像 2 は承認済みボトルのパックショット、画像 3 は同意を得た人物、画像 4 はポーズ、画像 5 は色調補正の参照画像です。来歴とハッシュを記録してください。

**選択とパラメーター：**BFL 直接接続の flux-2-flex、1280×1600、prompt_upsampling: false、guidance: 4.5、steps: 40、固定シード、PNG。

完全なプロンプト：

Use image 1 as the base room and preserve its camera position, architecture, furniture, and window light. Place the exact bottle from image 2 upright on the front-right table; preserve its silhouette, cap, label geometry, wordmark, and brushed-aluminum material. Use the exact adult person from image 3 in the body pose from image 4, standing behind the table; preserve facial structure, hair, skin details, and body proportions. Apply only the muted olive-and-amber color grade and fine film grain from image 5; do not import its objects or composition. The person looks toward the bottle with a relaxed expression. Maintain realistic scale, contact shadows, reflections, occlusion, and a coherent 50mm photographic perspective. Keep all existing room objects unchanged.

ペイロード固有のマッピング：input_image=画像 1、input_image_2=画像 2、以降 input_image_5=画像 5 です。実際の役割が異なる場合、メタデータでこれらを「スタイル画像」と呼ばないでください。

**期待される結果：**部屋と人物のアイデンティティが保たれ、製品の形状とロゴが識別可能なままになり、他の物体が入り込まずにポーズと色調補正が反映されます。

**よくある失敗と対処法：**ポーズ参照画像とアイデンティティが混ざる場合は、画像 4 を顔のないシルエットにトリミングするか、個人を特定できないポーズガイドに置き換えてください。製品の文字が変わる場合は、製品なしでシーンを作成して承認済みのパックショットを合成するか、単一参照画像を使った対象限定の修正を行ってください。

**バリエーション：**高速プレビューには、色調補正の参照画像を取り除き、色調をテキストで指定して、最大 4 枚の参照画像で [klein] を試してください。プレビューでの受け入れ結果が最終的な [flex] の忠実度を予測するとは限りません。

例 3 — マスク操作の選択

**意図：**マイクを取り除いて壁を再構築し、別バージョンでは小さな額入りのプリントを配置します。

除去する場合：POST /v1/flux-tools/erase-v1 を使用します。写真と、同じサイズのバイナリ PNG マスクを base64 で指定します。白でマイク、ケーブル、接触影、壁への反射を覆い、黒でそれ以外すべてを保持します。まず dilate_pixels: 10、output_format: "png" を指定します。プロンプトは送信しません。

**プロンプトを使ったインペイントの場合：**額入りプリントのバージョンに限り、レガシーの POST /v1/flux-pro-1.0-fill を使用します。同じマスク規則を使い、次のプロンプトを指定します。

A small thin black metal picture frame centered on this wall region, containing a simple cream paper print with one dark green circle, matching the existing wall perspective and warm side lighting, realistic contact shadow, preserve all unmasked pixels.

steps: 40、guidance: 35、prompt_upsampling: false、固定シード、PNG を設定します。これらのパラメーターは FLUX.1 Fill 用です。FLUX.2 [flex] にコピーしないでください。

**期待される結果：**Erase バージョンでは壁の質感が自然に保たれ、Fill バージョンでは遠近感の正しい額縁が 1 つ配置され、マスクされていないコンテンツは安定したままになります。

**よくある失敗と対処法：**ハローが現れる場合は、マスクまたはディレーションでエッジをカバーできていません。質感に継ぎ目がある場合は、移行部分のコンテキストを増やす必要があります。額縁が正しくない場合は Fill のプロンプトまたはマスクに問題があります。Erase に意味的なテキストを送る理由にはなりません。

参照元

以下の変動する参照先の確認は、すべて 2026-07-09 に実施しました。

• D1 — BFL モデルの範囲と選定： FLUX.2 の概要、BFL モデルカタログ、リリースノート。
• D2 — 直接 API のスキーマ： FLUX.2 max、pro、flex、klein 4B。
• D3 — プロンプトの構成： プロンプト作成の基本、良いプロンプトの作り方。
• D4 — パラメーターと肯定的なプロンプト： 技術パラメーター、プロンプトリファレンス。
• D5 — タイポグラフィ、色、単一参照画像の編集： スタイル、美的要素、テキスト、単一参照画像の編集、FLUX.2 プロンプトガイド。
• D6 — 複数参照画像の制限と手法： 画像編集の概要、複数参照画像の編集。
• D7 — マスクおよびキャンバスツール： FLUX Erase、FLUX Outpainting、FLUX.1 Fill API、FLUX.1 Fill dev モデルカード。
• D8 — アーキテクチャと研究の背景： FLUX.2 公式推論リポジトリ、FLUX.2 表現研究インデックス。
• D9 — API のライフサイクル： FLUX.2 テキストから画像への生成、FLUX.2 画像編集、結果取得のスキーマ。
• D10 — 重みとライセンス： FLUX.2 klein 4B モデルカード、klein 9B モデルカード、FLUX.2 dev モデルカード、FLUX 非商用利用規約、商用重みのライセンス、FLUX.1 公式リポジトリ／モデル一覧。
• D11 — 権利と安全性： BFL 利用ポリシー、FLUX API サービス規約、ウェブサイトおよび FLUX の利用規約、知的財産ポリシー。
• D12 — エンドポイントの変動： BFL リリースノート。
• D13 — 前世代の背景： FLUX.1 Kontext の概要、Kontext 編集ガイド、FLUX.1 Kontext 論文。