bfl-api

BFL API 統合ガイド

画像の生成、編集、処理を行うアプリケーションに BFL FLUX API を統合する際に、このスキルを使用してください。

最初に：API キーを確認する

画像を生成する前に、API キーが設定されていることを確認してください：

echo $BFL_API_KEY

空の場合、または「Not authenticated」エラーが表示される場合は、以下のAPI キーの設定を参照してください。

重要：画像 URL の有効期限は 10 分です

API から返される結果 URL は一時的なものです。生成が完了したら、すぐに画像をダウンロードしてください。URL 自体を保存したり、キャッシュしたりしないでください。

使用する場面

• BFL API クライアントのセットアップ
• 非同期ポーリングパターンの実装
• レート制限とエラーへの対応
• 本番環境向けのウェブフック設定
• リージョン別エンドポイントの選択
• 本番環境で利用できる統合の構築

クイックリファレンス

ベースエンドポイント

リージョン	エンドポイント	用途
Global	https://api.bfl.ai	デフォルト、自動フェイルオーバー
EU	https://api.eu.bfl.ai	GDPR への準拠
US	https://api.us.bfl.ai	米国でのデータ保存

モデルのエンドポイントと料金

クレジット料金： 1 クレジット = $0.01 USD。FLUX.2 はメガピクセル単位の料金体系です（解像度に応じてコストが変わります）。

FLUX.2 モデル

モデル	パス	最初の MP	+MP	1MP T2I	1MP I2I	最適な用途
FLUX.2 [klein] 4B	/v1/flux-2-klein-4b	1.4c	0.1c	$0.014	$0.015	リアルタイム、大量処理
FLUX.2 [klein] 9B	/v1/flux-2-klein-9b	1.5c	0.2c	$0.015	$0.017	品質と速度のバランス
FLUX.2 [pro]	/v1/flux-2-pro	3c	1.5c	$0.03	$0.045	本番環境、短い処理時間
FLUX.2 [max]	/v1/flux-2-max	7c	3c	$0.07	$0.10	最高品質
FLUX.2 [flex]	/v1/flux-2-flex	5c	5c	$0.05	$0.10	タイポグラフィ、調整可能な制御
FLUX.2 [dev]	-	-	-	無料	無料	ローカル開発（非商用）

料金の計算式： (firstMP + (outputMP-1) * mpPrice) + (inputMP * mpPrice) セント

FLUX.1 モデル

モデル	パス	画像あたりの料金	最適な用途
FLUX.1 Kontext [pro]	/v1/flux-kontext	$0.04	コンテキストを踏まえた画像編集
FLUX.1 Kontext [max]	/v1/flux-kontext-max	$0.08	最高品質の画像編集
FLUX1.1 [pro]	/v1/flux-pro-1.1	$0.04	標準的な T2I、高速で信頼性の高い処理
FLUX1.1 [pro] Ultra	/v1/flux-pro-1.1-ultra	$0.06	超高解像度
FLUX1.1 [pro] Raw	/v1/flux-pro-1.1-raw	$0.06	自然なスナップ写真の雰囲気
FLUX.1 Fill [pro]	/v1/flux-pro-1.0-fill	$0.05	インペインティング

ヒント： すべての FLUX.2 モデルは input_image パラメーターによる画像編集に対応しているため、専用の編集エンドポイントは必要ありません。さまざまな解像度での正確な料金は、bfl.ai/pricing の計算ツールをご利用ください。

編集用の画像入力

推奨：URL を直接使用してください。Base64 よりも簡単で便利です。

単一画像の編集：

curl -X POST "https://api.bfl.ai/v1/flux-2-pro" \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Change the background to a sunset",
    "input_image": "https://example.com/photo.jpg"
  }'

複数の参照画像を使った編集：

curl -X POST "https://api.bfl.ai/v1/flux-2-pro" \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The person from image 1 in the environment from image 2",
    "input_image": "https://example.com/person.jpg",
    "input_image_2": "https://example.com/background.jpg"
  }'

API が URL を自動的に取得します。URL と Base64 のどちらも使用できますが、利用可能な場合は URL を推奨します。

マルチリファレンス I2I

FLUX.2 モデルは、要素の組み合わせ、スタイル転送、キャラクターの一貫性の維持のために、複数の入力画像をサポートしています。

モデル	最大参照数
FLUX.2 [klein]	4 枚
FLUX.2 [pro/max/flex]	8 枚

パラメーター： input_image、input_image_2、input_image_3、... input_image_8

プロンプトのパターン： プロンプト内で画像を番号で指定します。

• 「画像 1 の被写体を、画像 2 の環境に配置する」
• 「画像 1 のシーンに、画像 2 のスタイルを適用する」
• 「画像 1 の人物に、画像 2 の服装を着せ、画像 3 のポーズをとらせる」

マルチリファレンスのパターン（キャラクターの一貫性、スタイル転送、ポーズのガイダンス）の詳細については、flux-best-practices/rules/multi-reference-editing.md を参照してください。

レート制限

ティア	同時リクエスト数
標準（ほとんどのエンドポイント）	24

ポーリングと Webhook

方法	使用する場面
ポーリング	スクリプト、CLI ツール、ローカル開発、単一リクエスト、シンプルな統合
Webhook	本番アプリ、大量処理、サーバー間通信、即時通知が必要な場合

まずはポーリングから始めてください。よりシンプルで、あらゆる環境で動作します。規模を拡大したい場合や、イベント駆動型のアーキテクチャが必要になった場合は、Webhook に切り替えてください。

主な動作

• ポーリング：非同期の結果を取得するための polling_url がレスポンスに含まれます
• URL の有効期限：結果 URL の有効期限は 10 分です
• Webhook のサポート：本番ワークロードでは webhook_url を設定してください

API キーの設定

必須：API を使用する前に、BFL_API_KEY 環境変数を設定してください。

簡易確認

echo $BFL_API_KEY

未設定の場合

1. キーを取得：https://dashboard.bfl.ai/get-started にアクセス → 「Create Key」 をクリック → 組織を選択
2. .env に保存（永続化する場合に推奨）：

   echo 'BFL_API_KEY=bfl_your_key_here' >> .env
   echo '.env' >> .gitignore  # Don't commit secrets
   

詳しい設定手順については、references/api-key-setup.md を参照してください。

認証

x-key: YOUR_API_KEY

基本的なリクエストフロー

1. POST request to model endpoint
   └─> Response: { "polling_url": "..." }

2. GET polling_url (repeat until complete)
   └─> Response: { "status": "Pending" | "Ready" | "Error", ... }

3. When Ready, download result URL
   └─> URL expires in 10 minutes - download immediately

関連情報

• プロンプト作成のベストプラクティス（T2I、I2I、タイポグラフィ、色）：flux-best-practices スキルを参照してください
• マルチリファレンスのパターン（キャラクターの一貫性、スタイル転送、ポーズのガイダンス）：flux-best-practices/rules/multi-reference-editing.md を参照してください

参考資料

• references/api-key-setup.md - API キーの作成と設定
• references/endpoints.md - エンドポイントの完全なドキュメント
• references/polling-patterns.md - 非同期ポーリングの実装
• references/rate-limiting.md - レート制限への対処方法
• references/error-handling.md - エラーコードと復旧方法
• references/webhook-integration.md - Webhook の設定とセキュリティ

コード例

注： Python や Node.js が不要で、あらゆる環境で動作するため、通常は cURL の例を推奨します。本番アプリケーションを開発する場合は、言語固有のクライアントを使用してください。

• references/code-examples/curl-examples.sh - cURL の例（推奨）
• references/code-examples/python-client.py - Python クライアント
• references/code-examples/typescript-client.ts - TypeScript クライアント

クイックスタートの例

1. 生成リクエストを送信

curl -s -X POST "https://api.bfl.ai/v1/flux-2-pro" \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A serene mountain landscape at sunset", "width": 1024, "height": 1024}'

レスポンス：

{ "id": "abc123", "polling_url": "https://api.bfl.ai/v1/get_result?id=abc123" }

2. 結果をポーリング

curl -s "POLLING_URL" -H "x-key: $BFL_API_KEY"

準備ができた場合のレスポンス：

{ "status": "Ready", "result": { "sample": "https://...", "seed": 1234 } }

3. 画像をダウンロード

curl -s -o output.png "IMAGE_URL"

ヒント： 結果 URL の有効期限は 10 分です。ステータスが Ready になったら、すぐにダウンロードしてください。

4. 複数画像参照の例

複数の画像の要素を組み合わせます。

curl -s -X POST "https://api.bfl.ai/v1/flux-2-pro" \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The cat from image 1 sitting in the cozy room from image 2",
    "input_image": "https://example.com/cat.jpg",
    "input_image_2": "https://example.com/room.jpg",
    "width": 1024,
    "height": 1024
  }'

プロンプト内で番号を使って画像を参照します。制限とパターンについては、複数画像参照 I2I をご覧ください。