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 集成到应用程序中以进行图像生成、编辑和处理时,请使用此 skill。

First: Check API Key

首先:检查 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 below.
生成图像前,请确认已设置 API Key:
bash
echo $BFL_API_KEY
如果为空或出现 "Not authenticated" 错误,请参阅下方的 API Key 设置。

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

基础端点

RegionEndpointUse 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).
Credit 定价: 1 credit = $0.01 USD。FLUX.2 采用基于百万像素的定价(成本随分辨率缩放)。

FLUX.2 Models

FLUX.2 模型

ModelPath1st MP+MP1MP T2I1MP I2IBest For
FLUX.2 [klein] 4B
/v1/flux-2-klein-4b
1.4c0.1c$0.014$0.015Real-time, high volume
FLUX.2 [klein] 9B
/v1/flux-2-klein-9b
1.5c0.2c$0.015$0.017Balanced quality/speed
FLUX.2 [pro]
/v1/flux-2-pro
3c1.5c$0.03$0.045Production, fast turnaround
FLUX.2 [max]
/v1/flux-2-max
7c3c$0.07$0.10Maximum quality
FLUX.2 [flex]
/v1/flux-2-flex
5c5c$0.05$0.10Typography, adjustable controls
FLUX.2 [dev]---FreeFreeLocal development (non-commercial)
Pricing formula:
(firstMP + (outputMP-1) * mpPrice) + (inputMP * mpPrice)
in cents
模型路径首个 MP+MP1MP T2I1MP I2I最适用场景
FLUX.2 [klein] 4B
/v1/flux-2-klein-4b
1.4c0.1c$0.014$0.015实时、高吞吐量
FLUX.2 [klein] 9B
/v1/flux-2-klein-9b
1.5c0.2c$0.015$0.017质量与速度平衡
FLUX.2 [pro]
/v1/flux-2-pro
3c1.5c$0.03$0.045生产环境、快速交付
FLUX.2 [max]
/v1/flux-2-max
7c3c$0.07$0.10最高质量
FLUX.2 [flex]
/v1/flux-2-flex
5c5c$0.05$0.10排版、可调控制项
FLUX.2 [dev]---免费免费本地开发(非商业用途)
定价公式:
(firstMP + (outputMP-1) * mpPrice) + (inputMP * mpPrice)
,单位为美分

FLUX.1 Models

FLUX.1 模型

ModelPathPrice/ImageBest For
FLUX.1 Kontext [pro]
/v1/flux-kontext
$0.04Image editing with context
FLUX.1 Kontext [max]
/v1/flux-kontext-max
$0.08Max quality editing
FLUX1.1 [pro]
/v1/flux-pro-1.1
$0.04Standard T2I, fast & reliable
FLUX1.1 [pro] Ultra
/v1/flux-pro-1.1-ultra
$0.06Ultra high-resolution
FLUX1.1 [pro] Raw
/v1/flux-pro-1.1-raw
$0.06Candid photography feel
FLUX.1 Fill [pro]
/v1/flux-pro-1.0-fill
$0.05Inpainting
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标准 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图像修复(Inpainting)
提示: 所有 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": "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:
ModelMax 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

速率限制

TierConcurrent Requests
Standard (most endpoints)24
层级并发请求数
标准(大多数端点)24

Polling vs Webhooks

轮询与 Webhook

ApproachUse When
PollingScripts, CLI tools, local development, single requests, simple integrations
WebhooksProduction 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 Key 设置

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

如果未设置

  1. Get a key: Go to https://dashboard.bfl.ai/get-started → Click "Create Key" → Select organization
  2. 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.
  1. 获取 Key:访问 https://dashboard.bfl.ai/get-started → 点击 "Create Key" → 选择组织
  2. 保存到
    .env
    (推荐用于持久保存):
    bash
    echo '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_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 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

Related

相关内容

  • 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。