BFL API Integration Guide

Use this skill when integrating BFL FLUX APIs into applications for image generation, editing, and processing.

First: Check API Key

Before generating images, verify your API key is set:

echo $BFL_API_KEY

If empty or you see "Not authenticated" errors, see API Key Setup below.

Important: Image URLs Expire in 10 Minutes

Result URLs from the API are temporary. Download images immediately after generation completes - do not store or cache the URLs themselves.

When to Use

• Setting up BFL API client
• Implementing async polling patterns
• Handling rate limits and errors
• Configuring webhooks for production
• Selecting regional endpoints
• Building production-ready integrations

Quick Reference

Base Endpoints

Model Endpoints & Pricing

Credit pricing: 1 credit = $0.01 USD. FLUX.2 uses megapixel-based pricing (cost scales with resolution).

FLUX.2 Models

Pricing formula: (firstMP + (outputMP-1) * mpPrice) + (inputMP * mpPrice) in cents

FLUX.1 Models

Tip: All FLUX.2 models support image editing via the input_image parameter - no separate editing endpoint needed. Use bfl.ai/pricing calculator for exact costs at different resolutions.

Image Input for Editing

Preferred: Use URLs directly - simpler and more convenient than base64.

Single image editing:

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"
  }'

Multi-reference editing:

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"
  }'

The API fetches URLs automatically. Both URL and base64 work, but URLs are recommended when available.

Multi-Reference I2I

FLUX.2 models support multiple input images for combining elements, style transfer, and character consistency:

Parameters: input_image, input_image_2, input_image_3, ... input_image_8

Prompt pattern: Reference images by number in your prompt:

• "The subject from image 1 in the environment from image 2"
• "Apply the style of image 2 to the scene in image 1"
• "The person from image 1 wearing the outfit from image 2, in the pose from image 3"

For detailed multi-reference patterns (character consistency, style transfer, pose guidance), see flux-best-practices/rules/multi-reference-editing.md

Rate Limits

Polling vs Webhooks

Start with polling - it's simpler and works everywhere. Switch to webhooks when you need to scale or want event-driven architecture.

Key Behaviors

• Polling: Response includes polling_url for async results
• URL Expiration: Result URLs expire after 10 minutes
• Webhook Support: Configure webhook_url for production workloads

API Key Setup

Required: The BFL_API_KEY environment variable must be set before using the API.

Quick Check

echo $BFL_API_KEY

If Not Set

1. Get a key: Go to https://dashboard.bfl.ai/get-started → Click "Create Key" → Select organization
2. Save to .env (recommended for persistence):

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

See references/api-key-setup.md for detailed setup instructions.

Authentication

x-key: YOUR_API_KEY

Basic Request Flow

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

Related

• Prompting best practices (T2I, I2I, typography, colors): see the flux-best-practices skill
• Multi-reference patterns (character consistency, style transfer, pose guidance): see flux-best-practices/rules/multi-reference-editing.md

References

• references/api-key-setup.md - API key creation and configuration
• references/endpoints.md - Complete endpoint documentation
• references/polling-patterns.md - Async polling implementation
• references/rate-limiting.md - Rate limit handling strategies
• references/error-handling.md - Error codes and recovery
• references/webhook-integration.md - Webhook setup and security

Code Examples

Note: cURL examples are preferred by default as they work universally without requiring Python or Node.js. Use language-specific clients when building production applications.

• references/code-examples/curl-examples.sh - cURL examples (recommended)
• references/code-examples/python-client.py - Python client
• references/code-examples/typescript-client.ts - TypeScript client

Quick Start Example

1. Submit Generation Request

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}'

Response:

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

2. Poll for Result

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

Response when ready:

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

3. Download Image

curl -s -o output.png "IMAGE_URL"

Tip: Result URLs expire in 10 minutes. Download immediately after status becomes Ready.

4. Multi-Reference Example

Combine elements from multiple images:

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
  }'

Reference images by number in your prompt. See Multi-Reference I2I for limits and patterns.