bfl-api

BFL API 集成指南

在应用中集成 BFL FLUX API 以生成、编辑和处理图像时，请使用本指南。

首先：检查 API 密钥

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

echo $BFL_API_KEY

如果为空或出现“Not authenticated”错误，请参阅下文的 API 密钥设置。

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

API 返回的结果 URL 是临时的。生成完成后，请立即下载图像，不要存储或缓存 URL 本身。

适用场景

• 设置 BFL API 客户端
• 实现异步轮询模式
• 处理速率限制和错误
• 为生产环境配置 Webhook
• 选择区域端点
• 构建可用于生产环境的集成

快速参考

基础端点

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

模型端点和定价

点数定价： 1 点数 = $0.01 USD。FLUX.2 按百万像素定价（费用随分辨率变化）。

FLUX.2 模型

模型	路径	首个 MP	+MP	1MP T2I	1MP I2I	适用场景
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]	-	-	-	免费	免费	本地开发（非商业用途）

定价公式： (firstMP + (outputMP-1) * mpPrice) + (inputMP * mpPrice)，单位为美分。

FLUX.1 模型

模型	路径	每张价格	适用场景
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	标准 T2I，快速且可靠
FLUX1.1 [pro] Ultra	/v1/flux-pro-1.1-ultra	$0.06	超高分辨率
FLUX1.1 [pro] Raw	/v1/flux-pro-1.1-raw	$0.06	自然随性的摄影风格
FLUX.1 Fill [pro]	/v1/flux-pro-1.0-fill	$0.05	图像修补

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

编辑时的图像输入

推荐：直接使用 URL，比 base64 更简单方便。

单图编辑：

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"
  }'

多参考图编辑：

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，建议优先使用。

多参考图 I2I

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

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

参数： input_image、input_image_2、input_image_3、... input_image_8

提示词模式： 在提示词中按编号引用图像：

• “使用图像 2 中的环境，呈现图像 1 中的主体”
• “将图像 2 的风格应用到图像 1 的场景中”
• “图像 1 中的人物穿着图像 2 中的服装，摆出图像 3 中的姿势”

如需了解详细的多参考图模式（角色一致性、风格迁移、姿势指导），请参阅 flux-best-practices/rules/multi-reference-editing.md

速率限制

层级	并发请求数
标准（大多数端点）	24

轮询与 Webhook

方式	适用场景
轮询	脚本、CLI 工具、本地开发、单次请求、简单集成
Webhook	生产应用、高请求量、服务端到服务端通信，以及需要即时通知时

建议从轮询开始——它更简单且适用范围广。需要扩展或采用事件驱动架构时，再切换到 Webhook。

关键行为

• 轮询：响应中包含异步结果的 polling_url
• URL 过期时间：结果 URL 会在 10 分钟后过期
• Webhook 支持：为生产工作负载配置 webhook_url

API 密钥设置

必需： 使用 API 前，必须设置 BFL_API_KEY 环境变量。

快速检查

echo $BFL_API_KEY

如果尚未设置

1. 获取密钥：前往 https://dashboard.bfl.ai/get-started → 点击 "Create Key" → 选择组织
2. 保存到 .env（推荐，便于持久保存）：

   echo 'BFL_API_KEY=bfl_your_key_here' >> .env
   echo '.env' >> .gitignore  # Don't commit secrets
   

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

身份验证

x-key: YOUR_API_KEY

基本请求流程

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

相关内容

• 提示词编写最佳实践（T2I、I2I、排版、颜色）：请参阅 flux-best-practices 技能
• 多参考图模式（角色一致性、风格迁移、姿势指导）：请参阅 flux-best-practices/rules/multi-reference-editing.md

参考资料

• 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 设置和安全性

代码示例

注意： 默认优先使用 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 客户端

快速入门示例

1. 提交生成请求

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}'

响应：

{ "id": "abc123", "polling_url": "https://api.bfl.ai/v1/get_result?id=abc123" }

2. 轮询结果

curl -s "POLLING_URL" -H "x-key: $BFL_API_KEY"

就绪时的响应：

{ "status": "Ready", "result": { "sample": "https://...", "seed": 1234 } }

3. 下载图像

curl -s -o output.png "IMAGE_URL"

提示： 结果 URL 会在 10 分钟后过期。状态变为 Ready 后，请立即下载。

4. 多参考图示例

组合多张图像中的元素：

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
  }'

在提示词中按编号引用图像。有关限制和模式，请参阅 多参考图生图。