bfl-api Checked

| Model | Path | Price/Image | Best For |

| -------------------- | ------------------------ | ----------- | ----------------------------- |

| FLUX.1 Kontext [pro] | /v1/flux-kontext | $0.04 | Image editing with context |

| FLUX.1 Kontext [max] | /v1/flux-kontext-max | $0.08 | Max quality editing |

| FLUX1.1 [pro] | /v1/flux-pro-1.1 | $0.04 | Standard T2I, fast & reliable |

| FLUX1.1 [pro] Ultra | /v1/flux-pro-1.1-ultra | $0.06 | Ultra high-resolution |

| FLUX1.1 [pro] Raw | /v1/flux-pro-1.1-raw | $0.06 | Candid photography feel |

| FLUX.1 Fill [pro] | /v1/flux-pro-1.0-fill | $0.05 | Inpainting |

> **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:

| Model | Max References |

| --------------------- | -------------- |

| FLUX.2 [klein] | 4 images |

| FLUX.2 [pro/max/flex] | 8 images |

**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

| Tier | Concurrent Requests |

| ------------------------- | ------------------- |

| Standard (most endpoints) | 24 |

### Polling vs Webhooks

| Approach | Use When |

| ------------ | ------------------------------------------------------------------------------------ |

| **Polling** | Scripts, CLI tools, local development, single requests, simple integrations |

| **Webhooks** | Production apps, high volume, server-to-server, when you need immediate notification |

**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 (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 (references/api-key-setup.md) - **API key creation and configuration**
• references/endpoints.md (references/endpoints.md) - Complete endpoint documentation
• references/polling-patterns.md (references/polling-patterns.md) - Async polling implementation
• references/rate-limiting.md (references/rate-limiting.md) - Rate limit handling strategies
• references/error-handling.md (references/error-handling.md) - Error codes and recovery
• references/webhook-integration.md (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-ex