Bfl ApiSAFE

World's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: bfl-api
description: BFL FLUX API integration guide covering endpoints, async polling patterns, rate limiting, error handling, webhooks, and regional endpoints with Python and TypeScript code examples.
metadata:
  author: Black Forest Labs
  version: "1.0.0"
  tags: flux, bfl, api, integration, webhooks, rate-limiting
---

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

```bash
echo $BFL_API_KEY
```

If empty or you see "Not authenticated" errors, see [API Key Setup](#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

| Region | Endpoint                | Use Case                    |
| ------ | ----------------------- | --------------------------- |
| Global | `https://api.bfl.ai`    | Default, automatic failover |
| EU     | `https://api.eu.bfl.ai` | GDPR compliance             |
| US     | `https://api.us.bfl.ai` | US data residency           |

### Model Endpoints & Pricing

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

#### FLUX.2 Models

| Model             | Path                  | 1st MP | +MP  | 1MP T2I | 1MP I2I | Best For                           |
| ----------------- | --------------------- | ------ | ---- | ------- | ------- | ---------------------------------- |
| FLUX.2 [klein] 4B | `/v1/flux-2-klein-4b` | 1.4c   | 0.1c | $0.014  | $0.015  | Real-time, high volume             |
| FLUX.2 [klein] 9B | `/v1/flux-2-klein-9b` | 1.5c   | 0.2c | $0.015  | $0.017  | Balanced quality/speed             |
| FLUX.2 [pro]      | `/v1/flux-2-pro`      | 3c     | 1.5c | $0.03   | $0.045  | Production, fast turnaround        |
| FLUX.2 [max]      | `/v1/flux-2-max`      | 7c     | 3c   | $0.07   | $0.10   | Maximum quality                    |
| FLUX.2 [flex]     | `/v1/flux-2-flex`     | 5c     | 5c   | $0.05   | $0.10   | Typography, adjustable controls    |
| FLUX.2 [dev]      | -                     | -      | -    | Free    | Free    | Local development (non-commercial) |

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

#### FLUX.1 Models

| 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](https://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:**

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

```bash
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 p

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

declared (7 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Bfl Api](https://modelsatlas.com/skills/calesthio/bfl-api/badge.svg)](https://modelsatlas.com/skills/calesthio/bfl-api/)

Not your listing, or something out of date? Claim or update your listing.