FLUXの公式APIをアプリへ組み込むときは、生成要求の受付、生成結果の取得、自社での画像保存を別の工程として扱います。要求を送って応答が返っただけで、画像を利用者へ表示できる状態になったとは限りません。
ここではBlack Forest Labs（BFL）の公式APIを対象に、受付IDとpolling_urlを保存し、状態を確認して画像を取得する設計を整理します。JSONは必要な項目だけを抜き出した説明用の架空例で、完全な応答スキーマや実際のAPI応答ではありません。APIへの送信、生成、ダウンロード、課金、保存、表示は実測していません。
目次
最初に、対象モデルとAPI契約を記録する
BFLのQuickstartは、アカウント、正のクレジット残高、APIキーを事前条件として案内しています。実装する前に、使用するモデルのエンドポイント、入力項目、寸法・形式、料金単位、利用条件を現行の資料で確認します。BFL公式：APIの始め方（新しいタブで開く）
モデルの画面上の名称から、APIのパスや入力上限を推測しないでください。例えば確認時のQuickstartには/v1/flux-2-proの送信例があり、生成ガイドはpreview版と固定版のエンドポイントも区別しています。実際に使うモデルと版を決め、そのモデルの参照資料へ戻ります。BFL公式：画像生成ガイド（新しいタブで開く）
APIキーはサーバー側の秘密設定から読み、ブラウザへ渡すデータや公開コードへ含めない構成にします。実装メモには設定名や管理場所を残し、キーの値そのものは原稿やログへ貼りません。自分のアプリから何回生成を試すかも決め、料金を確認せずに再送を繰り返す設計を避けます。
受付応答から、IDとpolling_urlを対応させる
BFLは非同期の生成APIとして、生成要求のあとに結果を照会する流れを説明しています。成功した受付応答にはidとpolling_urlが含まれ、結果確認には返されたpolling_urlを使う案内です。IDや既知のホスト名から自分で照会URLを組み立てません。
受付応答の形を説明する架空例です。example.invalidは実際のBFLエンドポイントではなく、このURLへアクセスするためのコード例でもありません。
{
"id": "example-task-001",
"polling_url": "https://example.invalid/poll/example-task-001"
}
自社のジョブIDと、この受付ID・照会URLを対応させます。例えば、利用者が同じ画面を再読込しても、自社のジョブIDから既存の受付情報を確認できるようにします。受付情報の保存を待たずに「完了」と返さないでください。
受付応答に必要な項目がない、JSONとして読めない、送信時に接続が切れた、といった場合は別に記録します。接続エラーだけから「生成は受理されていない」と決めつけて同じ要求を再送しません。すでに得たIDや照会先があるか、どこまで応答を受け取れたかを先に確認します。
生成状態と、自社の処理状態を分ける
確認時のGet Result参照のstatus欄には、Pending、Reasoning、Generating、Ready、Error、Request Moderated、Content Moderated、No Card Generated、Task not foundが列挙されています。この設計例ではPending・Reasoning・Generatingを待機側、Readyを結果確認側へ対応させ、ほかは理由を保持して確認へ戻します。BFL公式：Get Result（新しいタブで開く）
Quickstartのコード例にはFailedも分岐としてありますが、確認時のGet Resultの列挙とは一致していません。原文のstatusを保持し、Failedも確認側へ戻す設計にします。すべてのモデルが同じ状態を返すと決めず、対象モデルと現行の参照資料を照合してください。
自社の処理では、例えば次のような状態を定義できます。表の大文字の名称はこの記事独自の設計例で、BFLがそのまま返すstatusではありません。
表は横にスクロールできます
| 自社内の状態例 | 意味 | 次に進める条件 |
|---|---|---|
| WAITING | 受付情報を保存し、生成結果を待つ | 結果照会の応答を確認 |
| RESULT_AVAILABLE | Readyと画像の取得先を確認 | 画像取得と自社保存へ |
| STORED | 自社保存と参照情報の記録を確認 | 保存先を使う表示確認へ |
| NEEDS_REVIEW | 失敗、制限、未知の応答、保存失敗など | 理由に応じた確認へ |
例えばBFL側がReadyでも、自社側はRESULT_AVAILABLEであり、まだSTOREDではありません。逆に自社の待ち時間を超えても、BFL側で生成が失敗したと確定したことにはなりません。providerの状態、自社の状態、最後の確認時点を別の項目へ残します。
Readyの後も、画像URLと保存結果を確認する
画像取得先の形を説明する架空例です。実際のURLの署名や有効期限の表現を再現したものではありません。
{
"status": "Ready",
"result": {
"sample": "https://example.invalid/result/example-image.jpg"
}
}
Readyだけを見て成功扱いにせず、必要なresult.sampleがあるか、取得に成功したか、期待するファイルか、自社の保存と参照情報の記録ができたかを確認します。画像を受信したことと、自社の保存先から読めることも別です。
BFLの生成ガイドは、結果の署名付きURLの有効期間を10分と案内し、画像を取得して自分の基盤から提供する方法を勧めています。短期URLだけを長期の参照先として保存せず、必要な画像を取得し、自社の保存キーと生成ジョブを対応させます。期限や配信条件は利用時にも再確認してください。
自社保存に失敗した場合、生成そのものをやり直す前に、取得済みデータや有効な取得先から保存を再試行できるかを確認します。画像取得先が失効した場合も、再取得方法や生成側の状態を調べ、直ちに同じ生成要求を送る扱いにはしません。
まずは使ってみる
記事の文脈に合うToolへ進めます。報酬の有無で見た目は変えていません。
FLUX
状況ごとに、再確認と再生成を区別する
表は横にスクロールできます
| 観測したこと | 自社で残すこと | 次の判断 |
|---|---|---|
| 受付ID・照会URLを得た | ジョブとの対応、受付時点 | 同じ生成を送らず状態確認へ |
| Pending・Reasoning・Generating | 元のstatusと確認時点 | 回数・期限の範囲内で照会を継続 |
| 状態照会の通信が失敗 | 最後に確認できた状態、時点 | 既存ジョブの照会を再確認 |
| Readyだが取得先がない | 応答の不足箇所 | 成功表示せず、応答の確認へ |
| ErrorまたはFailed | 元のstatusと必要なエラー情報 | 原因と再試行条件を確認 |
| Request ModeratedまたはContent Moderated | 制限状態と利用者への案内 | 同じ要求の無条件再送をしない |
| Task not foundまたはNo Card Generated | 元のstatusと受付情報 | 成功・無課金と決めず、原因を確認 |
| 未知のstatus | 元の値と確認時点 | 成功・失敗へ推測で変換しない |
| 画像取得・自社保存が失敗 | どの工程まで成功したか | 取得・保存の再確認と生成を分ける |
状態確認には回数や経過時間の上限を設けます。未知の状態をすべて「まだ待つ」として無限に照会したり、待ち時間の上限を生成失敗へ読み替えたりしないでください。停止後も、既存のジョブと最後の状態を運用側から確認できるようにします。
利用者が同じボタンを押した場合に、既存のジョブを表示するのか、新しい生成として受け付けるのかも自社で決めます。自社の追跡IDを付けたことは、BFL側で同じ要求の重複生成を防ぐ仕組みが保証されたことを意味しません。
保存記録と、画面へ返す情報を整理する
自社側の記録例です。内部ジョブIDとproviderの受付IDを区別し、画像を保存していない段階では保存キーをnullとします。これはBFLのAPIへ送るrequest schemaではありません。
{
"app_job_id": "job-example-001",
"provider_request_id": "example-task-001",
"app_state": "WAITING",
"storage_key": null
}
実装では、利用者とジョブの対応、対象モデル、最後に確認したproviderの状態、自社保存状態、失敗した工程なども必要に応じて残します。認証キー、署名付きURL、入力全文を、すべての利用者へ返す画面データや一般ログへ混ぜないようにします。
表示側では、「生成中」「結果取得中」「保存を確認中」「確認が必要」など、自社の工程に合う案内を用意します。画像の保存キーが記録されただけで、利用者の画面から実際に開けることまで確認したとは扱いません。
AIへは、状態遷移と失敗例を一緒に渡す
BFL公式APIを使う画像生成アプリの設計案を整理してください。
実際のAPI呼出、画像生成、ダウンロード、課金は行わないでください。
対象モデルと公式資料：［確認したモデル・URL・確認日］。
受付IDとpolling_urlを自社ジョブへ対応させ、返された照会URLを使う流れにしてください。
BFLが返すstatusと自社内の状態名を別にしてください。
Ready、画像取得、自社保存、利用者画面での表示を別の確認にしてください。
受付応答が不明、照会失敗、ReadyだがURLなし、制限、未知のstatus、保存失敗を例にしてください。
待ち時間超過だけで、生成失敗や再生成可能と決めないでください。
出力：状態表／必要な記録／成功・失敗例の期待状態／未確認事項。
公式資料にないidempotencyや再取得保証、料金条件を補わないでください。
設計後は、入力と応答の架空例で、どの状態へ進むかを確認します。その確認が通っても、実際のモデル、認証、生成品質、料金消費、画像配信が検証済みになったわけではありません。実行する段階では、承認された対象と費用条件の下で、実APIから画面までを別に確認します。
FLUX全体の位置付けは、FLUXの特徴と選び方で確認できます。商用利用や配布形態の条件は、FLUXの商用利用で確認することと適用される最新の規約へ戻し、APIを使うだけであらゆる用途が認められるとは扱いません。
参考資料
- BFL：How do I get started with the API?（新しいタブで開く）
- BFL：Image Generation with Text Prompts（新しいタブで開く）
- BFL：Get Result（新しいタブで開く）
公式資料の確認日：2026年10月20日。JSONと自社の状態名は架空の設計例です。API呼出、生成、料金消費、取得・保存、配信・表示は実測していません。