bfl-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BFL API Integration Guide

BFL API集成指南

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

当你将BFL FLUX API集成到图像生成、编辑和处理应用中时，可以使用本指南。

First: Check API Key

第一步：检查API密钥

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 below.

生成图像前，请确认已设置API密钥：

bash

echo $BFL_API_KEY

如果为空或出现“未认证”错误，请查看下方的API密钥设置。

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	`https://api.bfl.ai`	Default, automatic failover
EU	`https://api.eu.bfl.ai`	GDPR compliance
US	`https://api.us.bfl.ai`	US data residency

区域	端点	使用场景
全球	`https://api.bfl.ai`	默认选项，自动故障转移
欧盟	`https://api.eu.bfl.ai`	符合GDPR合规要求
美国	`https://api.us.bfl.ai`	美国数据驻留

Model Endpoints & Pricing

模型端点与定价

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

信用定价： 1信用 = 0.01美元。FLUX.2采用基于百万像素的定价（成本随分辨率递增）。

FLUX.2 Models

FLUX.2模型

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

模型	路径	首百万像素	额外百万像素	1百万像素文生图	1百万像素图生图	最佳适用场景
FLUX.2 [klein] 4B	`/v1/flux-2-klein-4b`	1.4c	0.1c	$0.014	$0.015	实时处理、高吞吐量
FLUX.2 [klein] 9B	`/v1/flux-2-klein-9b`	1.5c	0.2c	$0.015	$0.017	质量与速度平衡
FLUX.2 [pro]	`/v1/flux-2-pro`	3c	1.5c	$0.03	$0.045	生产环境、快速交付
FLUX.2 [max]	`/v1/flux-2-max`	7c	3c	$0.07	$0.10	最高画质
FLUX.2 [flex]	`/v1/flux-2-flex`	5c	5c	$0.05	$0.10	文字排版、可调节控制项
FLUX.2 [dev]	-	-	-	免费	免费	本地开发（非商用）

定价公式：

(首百万像素费用 + (输出百万像素-1)*每百万像素额外费用) + (输入百万像素*每百万像素费用)

，单位为美分

FLUX.1 Models

FLUX.1模型

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.

模型	路径	单图价格	最佳适用场景
FLUX.1 Kontext [pro]	`/v1/flux-kontext`	$0.04	带上下文的图像编辑
FLUX.1 Kontext [max]	`/v1/flux-kontext-max`	$0.08	最高画质编辑
FLUX1.1 [pro]	`/v1/flux-pro-1.1`	$0.04	标准文生图、快速可靠
FLUX1.1 [pro] Ultra	`/v1/flux-pro-1.1-ultra`	$0.06	超高分辨率
FLUX1.1 [pro] Raw	`/v1/flux-pro-1.1-raw`	$0.06	candid摄影风格
FLUX.1 Fill [pro]	`/v1/flux-pro-1.0-fill`	$0.05	图像补全

提示： 所有FLUX.2模型均支持通过
input_image
参数进行图像编辑——无需单独的编辑端点。可使用bfl.ai/pricing计算器计算不同分辨率下的精确成本。

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": "将背景改为日落场景",
    "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": "把图1中的人物放到图2的环境里",
    "input_image": "https://example.com/person.jpg",
    "input_image_2": "https://example.com/background.jpg"
  }'

API会自动获取URL。URL和base64格式均支持，但优先推荐使用可用的URL。

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

FLUX.2模型支持多张输入图，用于元素组合、风格迁移和角色一致性：

模型	最大参考图数量
FLUX.2 [klein]	4张
FLUX.2 [pro/max/flex]	8张

参数：

input_image

input_image_2

input_image_3

, ...

input_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

轮询 vs 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
```
polling_url
```
for async results
URL Expiration: Result URLs expire after 10 minutes
Webhook Support: Configure
```
webhook_url
```
for production workloads

轮询： 响应包含
```
polling_url
```
用于获取异步结果
URL过期： 结果URL 10分钟后过期
Webhook支持： 为生产工作负载配置
```
webhook_url
```

API Key Setup

API密钥设置

Required: The

BFL_API_KEY

environment variable must be set before using the API.

必填项： 使用API前必须设置

BFL_API_KEY

环境变量。

Quick Check

快速检查

bash

echo $BFL_API_KEY

bash

echo $BFL_API_KEY

If Not Set

未设置时的操作

Get a key: Go to https://dashboard.bfl.ai/get-started → Click "Create Key" → Select organization

Save to
.env
(recommended for persistence):

bash

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.

获取密钥： 访问https://dashboard.bfl.ai/get-started → 点击**"Create Key"** → 选择组织

保存到
.env
（推荐用于持久化）：

bash

echo 'BFL_API_KEY=bfl_your_key_here' >> .env
echo '.env' >> .gitignore  # 不要提交机密信息

详细设置说明请查看references/api-key-setup.md。

Authentication

认证方式

bash

x-key: YOUR_API_KEY

bash

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

1. 向模型端点发送POST请求
   └─> 响应: { "polling_url": "..." }

2. 调用polling_url（重复调用直到完成）
   └─> 响应: { "status": "Pending" | "Ready" | "Error", ... }

3. 状态为Ready时，下载结果URL
   └─> URL 10分钟后过期——请立即下载

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密钥创建与配置
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": "日落时分宁静的山景", "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": "图1中的猫坐在图2的温馨房间里",
    "input_image": "https://example.com/cat.jpg",
    "input_image_2": "https://example.com/room.jpg",
    "width": 1024,
    "height": 1024
  }'

在提示词中按编号引用图像。详细限制与模式请查看多参考图图生图。

bfl-api

Original

Translation

BFL API Integration Guide

BFL API集成指南

First: Check API Key

第一步：检查API密钥

Important: Image URLs Expire in 10 Minutes

重要提示：图像URL 10分钟后过期

When to Use

适用场景

Quick Reference

快速参考

Base Endpoints

基础端点

Model Endpoints & Pricing

模型端点与定价

FLUX.2 Models

FLUX.2模型

FLUX.1 Models

FLUX.1模型

Image Input for Editing

编辑用图像输入

Multi-Reference I2I

多参考图图生图

Rate Limits

速率限制

Polling vs Webhooks

轮询 vs Webhook

Key Behaviors

核心特性

API Key Setup

API密钥设置

Quick Check

快速检查

If Not Set

未设置时的操作

Authentication

认证方式

Basic Request Flow

基础请求流程

Related

相关资源

References

参考文档

Code Examples

代码示例

Quick Start Example

快速开始示例

1. Submit Generation Request

1. 提交生成请求

2. Poll for Result

2. 轮询获取结果

3. Download Image

3. 下载图像

4. Multi-Reference Example

4. 多参考图示例