bfl-api
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBFL API Integration Guide
BFL API 集成指南
Use this skill when integrating BFL FLUX APIs into applications for image generation, editing, and processing.
将 BFL FLUX API 集成到应用程序中以进行图像生成、编辑和处理时,请使用此 skill。
First: Check API Key
首先:检查 API Key
Before generating images, verify your API key is set:
bash
echo $BFL_API_KEYIf empty or you see "Not authenticated" errors, see API Key Setup below.
Important: Image URLs Expire in 10 Minutes
重要:图像 URL 会在 10 分钟后过期
Result URLs from the API are temporary. Download images immediately after generation completes - do not store or cache the URLs themselves.
API 返回的结果 URL 是临时的。生成完成后请立即下载图像——不要存储或缓存这些 URL 本身。
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
- 设置 BFL API 客户端
- 实现异步轮询模式
- 处理速率限制和错误
- 为生产环境配置 Webhook
- 选择区域端点
- 构建生产就绪的集成
Quick Reference
快速参考
Base Endpoints
基础端点
| Region | Endpoint | Use Case |
|---|---|---|
| Global | | Default, automatic failover |
| EU | | GDPR compliance |
| US | | US data residency |
| 区域 | 端点 | 使用场景 |
|---|---|---|
| 全球 | | 默认,自动故障转移 |
| 欧盟 | | GDPR 合规 |
| 美国 | | 美国数据驻留 |
Model Endpoints & Pricing
模型端点与定价
Credit pricing: 1 credit = $0.01 USD. FLUX.2 uses megapixel-based pricing (cost scales with resolution).
Credit 定价: 1 credit = $0.01 USD。FLUX.2 采用基于百万像素的定价(成本随分辨率缩放)。
FLUX.2 Models
FLUX.2 模型
| Model | Path | 1st MP | +MP | 1MP T2I | 1MP I2I | Best For |
|---|---|---|---|---|---|---|
| FLUX.2 [klein] 4B | | 1.4c | 0.1c | $0.014 | $0.015 | Real-time, high volume |
| FLUX.2 [klein] 9B | | 1.5c | 0.2c | $0.015 | $0.017 | Balanced quality/speed |
| FLUX.2 [pro] | | 3c | 1.5c | $0.03 | $0.045 | Production, fast turnaround |
| FLUX.2 [max] | | 7c | 3c | $0.07 | $0.10 | Maximum quality |
| FLUX.2 [flex] | | 5c | 5c | $0.05 | $0.10 | Typography, adjustable controls |
| FLUX.2 [dev] | - | - | - | Free | Free | Local development (non-commercial) |
Pricing formula:in cents(firstMP + (outputMP-1) * mpPrice) + (inputMP * mpPrice)
| 模型 | 路径 | 首个 MP | +MP | 1MP T2I | 1MP I2I | 最适用场景 |
|---|---|---|---|---|---|---|
| FLUX.2 [klein] 4B | | 1.4c | 0.1c | $0.014 | $0.015 | 实时、高吞吐量 |
| FLUX.2 [klein] 9B | | 1.5c | 0.2c | $0.015 | $0.017 | 质量与速度平衡 |
| FLUX.2 [pro] | | 3c | 1.5c | $0.03 | $0.045 | 生产环境、快速交付 |
| FLUX.2 [max] | | 7c | 3c | $0.07 | $0.10 | 最高质量 |
| FLUX.2 [flex] | | 5c | 5c | $0.05 | $0.10 | 排版、可调控制项 |
| FLUX.2 [dev] | - | - | - | 免费 | 免费 | 本地开发(非商业用途) |
定价公式:,单位为美分(firstMP + (outputMP-1) * mpPrice) + (inputMP * mpPrice)
FLUX.1 Models
FLUX.1 模型
| Model | Path | Price/Image | Best For |
|---|---|---|---|
| FLUX.1 Kontext [pro] | | $0.04 | Image editing with context |
| FLUX.1 Kontext [max] | | $0.08 | Max quality editing |
| FLUX1.1 [pro] | | $0.04 | Standard T2I, fast & reliable |
| FLUX1.1 [pro] Ultra | | $0.06 | Ultra high-resolution |
| FLUX1.1 [pro] Raw | | $0.06 | Candid photography feel |
| FLUX.1 Fill [pro] | | $0.05 | Inpainting |
Tip: All FLUX.2 models support image editing via theparameter - no separate editing endpoint needed. Use bfl.ai/pricing calculator for exact costs at different resolutions.input_image
| 模型 | 路径 | 单图价格 | 最适用场景 |
|---|---|---|---|
| FLUX.1 Kontext [pro] | | $0.04 | 基于上下文的图像编辑 |
| FLUX.1 Kontext [max] | | $0.08 | 最高质量编辑 |
| FLUX1.1 [pro] | | $0.04 | 标准 T2I,快速且可靠 |
| FLUX1.1 [pro] Ultra | | $0.06 | 超高分辨率 |
| FLUX1.1 [pro] Raw | | $0.06 | 自然纪实的摄影风格 |
| FLUX.1 Fill [pro] | | $0.05 | 图像修复(Inpainting) |
提示: 所有 FLUX.2 模型都支持通过参数进行图像编辑——无需单独的编辑端点。在不同分辨率下使用 bfl.ai/pricing 计算器计算准确费用。input_image
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.
推荐:直接使用 URL——比 base64 更简单、更方便。
单张图像编辑:
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"
}'多参考图编辑:
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"
}'API 会自动获取 URL。URL 和 base64 均可使用,但在条件允许时推荐使用 URL。
Multi-Reference I2I
多参考图 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_imageinput_image_2input_image_3input_image_8Prompt 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), seeflux-best-practices/rules/multi-reference-editing.md
FLUX.2 模型支持使用多张输入图像来组合元素、进行风格迁移并保持角色一致性:
| 模型 | 最大参考图数量 |
|---|---|
| FLUX.2 [klein] | 4 张图像 |
| FLUX.2 [pro/max/flex] | 8 张图像 |
参数: 、、……
input_imageinput_image_2input_image_3input_image_8提示词模式: 在提示词中按编号引用图像:
- “将图像 1 中的主体置于图像 2 的环境中”
- “将图像 2 的风格应用到图像 1 的场景中”
- “让图像 1 中的人物穿着图像 2 的服装,并采用图像 3 的姿势”
有关详细的多参考图模式(角色一致性、风格迁移、姿势引导),请参阅flux-best-practices/rules/multi-reference-editing.md
Rate Limits
速率限制
| Tier | Concurrent Requests |
|---|---|
| Standard (most endpoints) | 24 |
| 层级 | 并发请求数 |
|---|---|
| 标准(大多数端点) | 24 |
Polling vs Webhooks
轮询与 Webhook
| 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.
| 方式 | 适用场景 |
|---|---|
| 轮询 | 脚本、CLI 工具、本地开发、单次请求、简单集成 |
| Webhook | 生产应用、高吞吐量、服务器间通信、需要立即获得通知时 |
先使用轮询——它更简单,并且适用于任何环境。当需要扩展或采用事件驱动架构时,再切换到 Webhook。
Key Behaviors
关键行为
- Polling: Response includes for async results
polling_url - URL Expiration: Result URLs expire after 10 minutes
- Webhook Support: Configure for production workloads
webhook_url
- 轮询:响应中包含 ,用于获取异步结果
polling_url - URL 过期:结果 URL 会在 10 分钟后过期
- Webhook 支持:为生产工作负载配置
webhook_url
API Key Setup
API Key 设置
Required: The environment variable must be set before using the API.
BFL_API_KEY必需:使用 API 前必须设置 环境变量。
BFL_API_KEYQuick Check
快速检查
bash
echo $BFL_API_KEYbash
echo $BFL_API_KEYIf Not Set
如果未设置
- Get a key: Go to https://dashboard.bfl.ai/get-started → Click "Create Key" → Select organization
- Save to (recommended for persistence):
.envbashecho '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.
- 获取 Key:访问 https://dashboard.bfl.ai/get-started → 点击 "Create Key" → 选择组织
- 保存到 (推荐用于持久保存):
.envbashecho 'BFL_API_KEY=bfl_your_key_here' >> .env echo '.env' >> .gitignore # Don't commit secrets
有关详细设置说明,请参阅 references/api-key-setup.md。
Authentication
身份验证
bash
x-key: YOUR_API_KEYbash
x-key: YOUR_API_KEYBasic 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 immediately1. 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 immediatelyRelated
相关内容
- 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
- 提示词最佳实践(T2I、I2I、排版、颜色):请参阅 flux-best-practices skill
- 多参考图模式(角色一致性、风格迁移、姿势引导):请参阅
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
- references/api-key-setup.md - API Key 创建与配置
- references/endpoints.md - 完整的端点文档
- references/polling-patterns.md - 异步轮询实现
- references/rate-limiting.md - 速率限制处理策略
- references/error-handling.md - 错误代码与恢复机制
- references/webhook-integration.md - Webhook 设置与安全
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
注意: 默认推荐使用 cURL 示例,因为它们无需 Python 或 Node.js 即可通用使用。构建生产应用时,请使用特定语言的客户端。
- references/code-examples/curl-examples.sh - cURL 示例(推荐)
- references/code-examples/python-client.py - Python 客户端
- references/code-examples/typescript-client.ts - TypeScript 客户端
Quick Start Example
快速入门示例
1. Submit Generation Request
1. 提交生成请求
bash
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:
json
{ "id": "abc123", "polling_url": "https://api.bfl.ai/v1/get_result?id=abc123" }bash
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}'响应:
json
{ "id": "abc123", "polling_url": "https://api.bfl.ai/v1/get_result?id=abc123" }2. Poll for Result
2. 轮询结果
bash
curl -s "POLLING_URL" -H "x-key: $BFL_API_KEY"Response when ready:
json
{ "status": "Ready", "result": { "sample": "https://...", "seed": 1234 } }bash
curl -s "POLLING_URL" -H "x-key: $BFL_API_KEY"就绪时的响应:
json
{ "status": "Ready", "result": { "sample": "https://...", "seed": 1234 } }3. Download Image
3. 下载图像
bash
curl -s -o output.png "IMAGE_URL"Tip: Result URLs expire in 10 minutes. Download immediately after status becomes.Ready
bash
curl -s -o output.png "IMAGE_URL"提示: 结果 URL 会在 10 分钟后过期。状态变为后请立即下载。Ready
4. Multi-Reference Example
4. 多参考图示例
Combine elements from multiple images:
bash
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.
组合多张图像中的元素:
bash
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。