bfl-api
BFL FLUX API integration guide covering endpoints, async polling patterns, rate limiting, error handling, webhooks, and regional endpoints with Python and TypeScript code examples.
calesthio · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add calesthio/OpenMontage --skill bfl-api技能说明
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:
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
| 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_imageparameter - 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 p
阅读完整来源 ↗