Black Forest Labs Image Generation Service

A TypeScript/Node.js wrapper for the Black Forest Labs API that provides easy access to FLUX and Kontext image generation models. Generate stunning AI images with professional quality through a simple command-line interface.

This service follows the data-collection architecture pattern with organized data storage, automatic polling, retry logic, comprehensive logging, and CLI orchestration.

Quick Demo

📺 Watch 3-minute CLI demo - Batch processing, auto-retry, and organized output in action.

Quick Start

CLI Usage

# Install globally
npm install -g bfl-api

export BFL_API_KEY="my-bfl-api-key"

# Generate an image
bfl --flux-dev --prompt "a serene mountain landscape"

Programmatic Usage

import { BflAPI } from 'bfl-api';

const api = new BflAPI();

// Generate and wait for image
const task = await api.generateFluxDev({
  prompt: 'a serene mountain landscape',
  width: 1024,
  height: 768
});

const result = await api.waitForResult(task.id);
console.log('Image URL:', result.result.sample);

Full TypeScript support with exported types for all parameters and responses.

Table of Contents

• Overview
• Models
• Authentication Setup
• Installation
• TypeScript Support
• Quick Start
• CLI Usage
• API Methods
• Examples
• Data Organization
• Security Features
• Error Handling
• Troubleshooting

Overview

The Black Forest Labs API provides access to state-of-the-art image generation models. This Node.js service implements:

• 10 Generation Models - FLUX.1 [dev], FLUX 1.1 [pro], FLUX Ultra, FLUX.1 Fill [pro], FLUX.1 Fill [pro] Finetune, FLUX.1 Expand [pro], FLUX.2 [PRO], FLUX.2 [FLEX], Kontext Pro, Kontext Max
• Production Security - API key redaction, error sanitization, HTTPS enforcement, comprehensive SSRF protection (including IPv4-mapped IPv6 bypass prevention)
• DoS Prevention - Request timeouts (30s API, 60s downloads), file size limits (50MB), redirect limits
• Parameter Validation - Pre-flight validation catches invalid parameters before API calls
• API Key Authentication - Multiple configuration methods with secure handling
• Auto-polling with Spinner - Automatic result polling with animated progress indicator
• Batch Processing - Generate multiple images sequentially from multiple prompts
• Retry Logic - Exponential backoff for transient errors
• Image Input Support - Convert local files or URLs to base64 with validation
• Organized Storage - Structured directories with timestamped files and metadata
• CLI Orchestration - Command-line tool for easy batch generation
• Full TypeScript Support - Complete type definitions for all API methods, parameters, and responses
• Comprehensive Testing - 271 tests with 89.58% coverage (api.ts: 94.76%, utils.ts: 82.71%, config.ts: 95.87%)

Models

FLUX.1 [dev]

Full control text-to-image generation with adjustable steps and guidance.

Best for: Experimentation, fine-tuning parameters, development

Parameters:

• width, height - Image dimensions (256-1440, divisible by 32)
• steps - Inference steps (1-50)
• guidance - Prompt adherence strength (1.5-5)

FLUX 1.1 [pro]

Professional quality generation with Redux image prompting.

Best for: Production use, high-quality images, image-to-image with Redux

Parameters:

• width, height - Image dimensions (256-1440, divisible by 32)
• image_prompt - Optional Redux image guidance (base64 or URL)

FLUX 1.1 [pro] Ultra

Maximum quality with aspect ratio control and raw mode.

Best for: Cinematic outputs, specific aspect ratios, natural/raw aesthetics

Parameters:

• aspect_ratio - Image proportions (21:9, 16:9, 4:3, 1:1, 3:4, 9:16, 9:21)
• raw - Enable raw/natural aesthetic mode (boolean)
• image_prompt - Optional image remixing (base64 or URL)

FLUX.1 Fill [pro]

Professional inpainting with mask-based editing for precise modifications.

Best for: Inpainting, object removal/replacement, selective editing with masks

Parameters:

• image - Input image to edit (required, base64 or URL)
• mask - Mask defining edit region (required for JPG/JPEG, base64 or URL)
• steps - Inference steps (15-50)
• guidance - Prompt adherence strength (1.5-100)
• safety_tolerance - Content moderation strictness (0-6)

Note: Requires either a separate mask image OR a PNG with an alpha channel (transparency) defining the edit region.

FLUX.1 Fill [pro] Finetune

Inpainting with custom fine-tuned models for specialized styles and subjects.

Best for: Applying custom trained models to inpainting tasks, consistent style application, specialized subject matter

Parameters:

• finetune_id - ID of your fine-tuned model (required)
• image - Input image to edit (required, base64 or URL)
• prompt - Description of desired changes (optional, default: '')
• mask - Mask defining edit region (required for JPG/JPEG, base64 or URL)
• finetune_strength - Model influence strength (0-2, API default: 1.1)
• steps - Inference steps (15-50)
• guidance - Prompt adherence strength (1.5-100)
• safety_tolerance - Content moderation strictness (0-6)

Note: Requires a fine-tuned model ID from your BFL account. Same masking rules as regular Fill apply.

FLUX.1 Expand [pro]

Professional image expansion/outpainting that extends images beyond original boundaries.

Best for: Image expansion, outpainting, adding context around images, extending canvases

Parameters:

• image - Input image to expand (required, base64 or URL)
• top - Pixels to expand at top (0-2048, default: 0)
• bottom - Pixels to expand at bottom (0-2048, default: 0)
• left - Pixels to expand on left (0-2048, default: 0)
• right - Pixels to expand on right (0-2048, default: 0)
• prompt - Description of desired expansion (optional)
• steps - Inference steps (15-50, default: 50)
• guidance - Prompt adherence strength (1.5-100, default: 60)
• safety_tolerance - Content moderation strictness (0-6)
• output_format - Output format: 'jpeg' or 'png'
• prompt_upsampling - AI-powered prompt enhancement (boolean)

Note: Specify at least one expansion direction (top, bottom, left, or right) with a value greater than 0.

Kontext Pro

Multi-reference image editing with context preservation.

Best for: Image editing, multi-reference composition, context-aware modifications

Parameters:

• input_image - Base image to edit (required, base64 or URL)
• reference_image_1, reference_image_2, reference_image_3 - Optional context images (base64 or URL)

Kontext Max

Maximum quality multi-reference image editing.

Best for: High-end image editing, professional retouching

Parameters:

• input_image - Base image to edit (required, base64 or URL)
• reference_image_1, reference_image_2, reference_image_3 - Optional context images (base64 or URL)

FLUX.2 [PRO]

Next-generation model with multi-image input support for contextual generation and editing.

Best for: Advanced multi-image editing, contextual generation, combining multiple references

Parameters:

• width, height - Image dimensions (64-2048, divisible by 16)
• input_image through input_image_8 - Up to 8 input images for multi-reference (base64 or URL)
• prompt_upsampling - AI prompt enhancement (default: true)
• safety_tolerance - Content moderation level (0-5, default: 2)
• output_format - Output format: 'jpeg' or 'png'

FLUX.2 [FLEX]

Flexible next-generation model with experimental multi-reference support.

Best for: Experimental multi-image workflows, flexible generation styles

Parameters:

• width, height - Image dimensions (64-2048, divisible by 16)
• input_image through input_image_8 - Up to 8 input images for experimental multiref (base64 or URL)
• prompt_upsampling - AI prompt enhancement (default: true)
• safety_tolerance - Content moderation level (0-5, default: 2)
• output_format - Output format: 'jpeg' or 'png'

Authentication Setup

1. Get Your API Key

1. Visit https://docs.bfl.ml/quick_start/introduction
2. Create an account or sign in
3. Generate your API key from the dashboard
4. Copy your API key

2. Configure Your API Key

You can provide your API key in multiple ways (listed in priority order):

Option A: CLI Flag (Highest Priority)

Pass the API key directly when running commands:

bfl --api-key YOUR_API_KEY --flux-dev --prompt "a cat"

This is useful for one-off commands or testing.

Option B: Environment Variable

Set the BFL_API_KEY environment variable in your shell:

# Add to your ~/.bashrc, ~/.zshrc, or equivalent
export BFL_API_KEY=your_actual_api_key_here

# Or use it for a single command
BFL_API_KEY=your_key bfl --flux-dev --prompt "a cat"

This is ideal for CI/CD pipelines and server environments.

Option C: Local .env File (Project-Specific)

Create a .env file in your project directory:

# In your project directory
echo "BFL_API_KEY=your_actual_api_key_here" > .env

This is best for project-specific configurations and when working on multiple projects.

Option D: Global Config (For Global npm Installs)

Create a global config file at ~/.bfl/.env:

# Create config directory
mkdir -p ~/.bfl

# Add your API key
echo "BFL_API_KEY=your_actual_api_key_here" > ~/.bfl/.env

This is perfect for global npm installations (npm install -g bfl-api) where you want the API key available everywhere.

Security Note: Never commit .env files or expose your API key publicly. The .env file is automatically ignored by git.

Installation

Option 1: Install from npm

# Install globally for CLI usage
npm install -g bfl-api

# Or install locally in your project
npm install bfl-api

Option 2: Install from source

# Clone the repository
git clone https://github.com/aself101/bfl-api.git
cd bfl-api

# Install dependencies
npm install

Dependencies:

• axios - HTTP client for API calls
• commander - CLI argument parsing
• dotenv - Environment variable management
• winston - Logging framework

TypeScript Support

This package is written in TypeScript and includes full type definitions. All API methods, parameters, and responses are fully typed.

Exported Types

import {
  BflAPI,
  // Parameter types
  FluxDevParams,
  FluxProParams,
  FluxProUltraParams,
  FluxProFillParams,
  FluxProExpandParams,
  KontextProParams,
  KontextMaxParams,
  Flux2Params,
  // Response types
  TaskResult,
  CreditsResult,
  // Config types
  BflApiOptions
} from 'bfl-api';

// Types are automatically inferred
const api = new BflAPI();
const task = await api.generateFluxDev({
  prompt: 'a cat',  // TypeScript will validate all parameters
  width: 1024,
  height: 768
});

Type-Safe Parameters

All generation methods have strict parameter typing:

// TypeScript will catch invalid parameters at compile time
const task = await api.generateFluxDev({
  prompt: 'a landscape',
  width: 1024,
  height: 768,
  steps: 28,        // number (1-50)
  guidance: 3,      // number (1.5-5)
  seed: 42,         // optional number
  output_format: 'png'  // 'jpeg' | 'png'
});

Building from Source

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Output is in dist/
ls dist/
# api.js, api.d.ts, cli.js, cli.d.ts, config.js, config.d.ts, utils.js, utils.d.ts

Quick Start

Using the CLI

The CLI command depends on how you installed the package:

If installed globally (npm install -g bfl-api):

bfl --examples                    # Show 15+ usage examples
bfl --flux-dev --prompt "a cat"   # Generate with FLUX.1 [dev]
bfl --credits                     # Check account credits

If installed locally in a project:

npx bfl --examples                    # Show 15+ usage examples
npx bfl --flux-dev --prompt "a cat"   # Generate with FLUX.1 [dev]
npx bfl --credits                     # Check account credits

If working from source (cloned repository):

npm run bfl:examples              # Show 15+ usage examples
npm run bfl -- --flux-dev --prompt "a cat"   # Generate
npm run bfl:credits               # Check credits

Example Commands

# Show examples (15+ usage examples)
bfl --examples

# Generate with FLUX.1 [dev]
bfl --flux-dev --prompt "a serene mountain landscape"

# Generate with FLUX 1.1 [pro] Ultra
bfl --flux-ultra --prompt "cinematic sunset" --aspect-ratio "21:9" --raw

# Edit image with Kontext Pro
bfl --kontext-pro --prompt "make it winter" --input-image ./photo.jpg

# Batch generation
bfl --flux-dev \
  --prompt "a cat" \
  --prompt "a dog" \
  --prompt "a bird"

# Check credits
bfl --credits

Note: Examples below use bfl directly (global install). If using local install, prefix with npx: npx bfl --flux-dev ...

Using the API Class Directly

// If installed via npm
import { BflAPI } from 'bfl-api';

// If running from source
import { BflAPI } from './src/api.js';

// Initialize the API
const api = new BflAPI();

// Generate with FLUX.1 [dev]
const task = await api.generateFluxDev({
  prompt: 'a beautiful sunset',
  width: 1024,
  height: 768,
  steps: 28,
  guidance: 3
});

// Wait for result
const result = await api.waitForResult(task.id);
console.log('Image URL:', result.result.sample);

CLI Usage

Basic Command Structure

# Global install
bfl [model] [options]

# Local install (use npx)
npx bfl [model] [options]

# From source (development)
npm run bfl -- [model] [options]

Model Selection (Required)

Choose one model:

--flux-dev               # FLUX.1 [dev] - Full control
--flux-pro               # FLUX 1.1 [pro] - Professional quality
--flux-ultra             # FLUX 1.1 [pro] Ultra - Maximum quality
--flux-fill              # FLUX.1 Fill [pro] - Inpainting/mask editing
--flux-fill-finetuned    # FLUX.1 Fill [pro] Finetune - Custom model inpainting
--flux-expand            # FLUX.1 Expand [pro] - Image expansion/outpainting
--flux-2-pro             # FLUX.2 [PRO] - Multi-image generation/editing
--flux-2-flex            # FLUX.2 [FLEX] - Experimental multi-reference
--kontext-pro            # Kontext Pro - Image editing
--kontext-max            # Kontext Max - Premium editing

Common Options

--prompt <text>               # Prompt (can specify multiple for batch)
--seed <number>               # Random seed for reproducibility
--safety-tolerance <0-6>      # Content moderation level (default: 2)
--output-format <jpeg|png>    # Output format (default: jpeg)
--timeout <seconds>           # Max wait time (default: 300)
--output-dir <path>           # Custom output directory
--log-level <level>           # DEBUG, INFO, WARNING, ERROR
--dry-run                     # Preview without generating

Note: All parameters are validated before making API calls. Invalid values (e.g., width not divisible by 32, steps > 50) will produce clear error messages, saving API credits.

FLUX.1 [dev] Specific

--width <number>              # 256-1440, multiple of 32 (default: 1024)
--height <number>             # 256-1440, multiple of 32 (default: 768)
--steps <number>              # 1-50 (default: 28)
--guidance <number>           # 1.5-5 (default: 3)
--prompt-upsampling           # Enable AI prompt enhancement

FLUX 1.1 [pro] Specific

--width <number>              # 256-1440, multiple of 32
--height <number>             # 256-1440, multiple of 32
--image-prompt <path>         # Input image for Redux (file or URL)
--prompt-upsampling           # Enable AI prompt enhancement

FLUX Ultra Specific

--aspect-ratio <ratio>        # e.g., 16:9, 21:9, 1:1 (default: 16:9)
--raw                         # Enable raw/natural mode
--image-prompt <path>         # Input image for remixing (file or URL)
--image-prompt-strength <0-1> # Remix strength (default: 0.1)

FLUX.1 Fill [pro] Specific

--image <path>                # Input image to edit (required, file or URL)
--mask <path>                 # Mask image defining edit region (required for JPG/JPEG)
--steps <number>              # 15-50 (default: 28)
--guidance <number>           # 1.5-100 (default: 3)
--prompt-upsampling           # Enable AI prompt enhancement

Note: Either --mask is required, OR --image must be a PNG with an alpha channel (transparency). JPG/JPEG images require an explicit --mask parameter.

FLUX.1 Fill [pro] Finetune Specific

--finetune-id <id>            # Fine-tuned model ID (required)
--image <path>                # Input image to edit (required, file or URL)
--mask <path>                 # Mask image defining edit region (required for JPG/JPEG)
--finetune-strength <number>  # Model influence 0-2 (default: 1.1)
--steps <number>              # 15-50 (default: 50)
--guidance <number>           # 1.5-100 (default: 60)
--prompt-upsampling           # Enable AI prompt enhancement

Note: Requires a fine-tuned model ID from your BFL account. Same masking rules as regular Fill apply.

FLUX.1 Expand [pro] Specific

--image <path>                # Input image to expand (required, file or URL)
--top <pixels>                # Pixels to expand at top (0-2048, default: 0)
--bottom <pixels>             # Pixels to expand at bottom (0-2048, default: 0)
--left <pixels>               # Pixels to expand on left (0-2048, default: 0)
--right <pixels>              # Pixels to expand on right (0-2048, default: 0)
--steps <number>              # 15-50 (default: 50)
--guidance <number>           # 1.5-100 (default: 60)
--prompt-upsampling           # Enable AI prompt enhancement

Note: Specify at least one direction (top, bottom, left, or right) with a value greater than 0. Use --prompt to describe the content that should fill the expanded areas.

Kontext Models Specific

--input-image <path>          # Primary input (required, file or URL)
--input-image-2 <path>        # Additional reference (optional)
--input-image-3 <path>        # Additional reference (optional)
--input-image-4 <path>        # Additional reference (optional)

FLUX.2 Models Specific

--width <number>              # 64-2048, multiple of 16 (auto by default)
--height <number>             # 64-2048, multiple of 16 (auto by default)
--input-image <path>          # Primary input image (optional, file or URL)
--input-image-2 <path>        # Additional reference (optional)
--input-image-3 <path>        # Additional reference (optional)
--input-image-4 <path>        # Additional reference (optional)
--input-image-5 <path>        # Additional reference (experimental multiref)
--input-image-6 <path>        # Additional reference (experimental multiref)
--input-image-7 <path>        # Additional reference (experimental multiref)
--input-image-8 <path>        # Additional reference (experimental multiref)
--prompt-upsampling           # AI prompt enhancement (enabled by default for FLUX.2)
--safety-tolerance <0-5>      # Content moderation level (default: 2)

Note: FLUX.2 models support up to 8 input images for advanced multi-reference generation. Dimensions must be divisible by 16 (not 32 like FLUX.1 models).

Utility Commands

--examples                    # Show 15+ usage examples with tips
--credits                     # Check account credits balance
--get-result <task_id>        # Poll specific task ID

API Methods

Core Generation Methods

generateFluxDev(params)

Generate image using FLUX.1 [dev].

const task = await api.generateFluxDev({
  prompt: 'a beautiful landscape',
  width: 1024,
  height: 768,
  steps: 28,
  guidance: 3,
  seed: 42,
  output_format: 'png'
});

generateFluxPro(params)

Generate image using FLUX 1.1 [pro].

const task = await api.generateFluxPro({
  prompt: 'professional portrait',
  width: 1024,
  height: 1024,
  image_prompt: 'base64_or_url',  // Optional Redux
  seed: 42
});

generateFluxProUltra(params)

Generate image using FLUX 1.1 [pro] Ultra.

const task = await api.generateFluxProUltra({
  prompt: 'cinematic landscape',
  aspect_ratio: '21:9',
  raw: true,
  image_prompt: 'base64_or_url',  // Optional remix
  image_prompt_strength: 0.3
});

generateFluxProFill(params)

Inpainting with FLUX.1 Fill [pro] using masks.

const task = await api.generateFluxProFill({
  prompt: 'replace with lush green grass',
  image: 'base64_encoded_image',        // Required
  mask: 'base64_encoded_mask',          // Required (or use PNG with alpha)
  steps: 30,
  guidance: 5,
  safety_tolerance: 3,
  output_format: 'png'
});

Note: The image parameter is required. Either provide a mask parameter, or use a PNG image with an alpha channel (transparency) defining the edit region.

generateFluxProFillFinetuned(params)

Inpainting with fine-tuned FLUX.1 Fill [pro] model.

const task = await api.generateFluxProFillFinetuned({
  finetune_id: 'my-custom-model',       // Required
  prompt: 'apply custom style',         // Optional (default: '')
  image: 'base64_encoded_image',        // Required
  mask: 'base64_encoded_mask',          // Required (or use PNG with alpha)
  finetune_strength: 1.2,               // Optional (default: 1.1, range: 0-2)
  steps: 35,
  guidance: 60,
  safety_tolerance: 2,
  output_format: 'png'
});

Note: Requires finetune_id from your BFL account. Same masking rules as regular Fill apply.

generateFluxProExpand(params)

Expand/outpaint images with FLUX.1 Expand [pro].

const task = await api.generateFluxProExpand({
  prompt: 'extend with dramatic sky and clouds',
  image: 'base64_encoded_image',        // Required
  top: 512,                              // Pixels to expand at top (0-2048)
  bottom: 256,                           // Pixels to expand at bottom (0-2048)
  left: 256,                             // Pixels to expand on left (0-2048)
  right: 256,                            // Pixels to expand on right (0-2048)
  steps: 30,                             // 15-50 (default: 50)
  guidance: 60,                          // 1.5-100 (default: 60)
  safety_tolerance: 2,                   // 0-6 (default: 2)
  output_format: 'png',                  // 'jpeg' or 'png'
  prompt_upsampling: true                // Enable AI prompt enhancement
});

Note: The image parameter is required. Specify at least one expansion direction (top, bottom, left, or right) with a value greater than 0.

generateKontextPro(params)

Edit image using Kontext Pro.

const task = await api.generateKontextPro({
  prompt: 'make it look like winter',
  input_image: 'base64_or_url',      // Required
  input_image_2: 'base64_or_url'     // Optional
});

generateKontextMax(params)

Edit image using Kontext Max.

const task = await api.generateKontextMax({
  prompt: 'enhance colors and details',
  input_image: 'base64_or_url',      // Required
  input_image_2: 'base64_or_url'     // Optional
});

generateFlux2Pro(params)

Generate or edit image using FLUX.2 [PRO] with multi-image support.

// Text-to-image generation
const task = await api.generateFlux2Pro({
  prompt: 'A majestic castle on a cliff',
  width: 1024,
  height: 1024
});

// Image editing with context
const task = await api.generateFlux2Pro({
  prompt: 'Add a dragon flying above',
  input_image: 'base64_or_url',
  input_image_2: 'base64_or_url'  // Optional additional context
});

generateFlux2Flex(params)

Generate or edit image using FLUX.2 [FLEX] with experimental multi-reference.

// Text-to-image generation
const task = await api.generateFlux2Flex({
  prompt: 'A serene Japanese garden',
  width: 1024,
  height: 768
});

// Multi-reference generation (up to 8 images)
const task = await api.generateFlux2Flex({
  prompt: 'Combine all elements',
  input_image: 'base64_or_url',
  input_image_2: 'base64_or_url',
  input_image_3: 'base64_or_url'
});

Utility Methods

getResult(taskId)

Poll task once for current status.

const result = await api.getResult('abc123');
if (result.status === 'Ready') {
  console.log('Image:', result.result.sample);
}

waitForResult(taskId, options)

Auto-poll until complete with spinner and retry logic.

const result = await api.waitForResult('abc123', {
  timeout: 300,      // 5 minutes
  pollInterval: 2,   // 2 seconds
  maxRetries: 3,     // retry on transient errors
  showSpinner: true  // animated spinner
});

getUserCredits()

Check account credits balance.

const credits = await api.getUserCredits();
console.log('Credits:', credits.credits);

getMyFinetunes()

Get list of all fine-tuned models created by the user.

const { finetunes } = await api.getMyFinetunes();
console.log('Your finetunes:', finetunes);
// Example output: ['model-id-1', 'model-id-2', 'custom-style-abc']

// Use a finetune in generation
if (finetunes.length > 0) {
  const task = await api.generateFluxProFillFinetuned({
    finetune_id: finetunes[0],
    image: 'base64_encoded_image',
    prompt: 'apply custom style'
  });
}

Examples

Note: Examples use bfl command (global install). For local install, use npx bfl instead.

Example 1: Basic Text-to-Image

bfl --flux-dev \
  --prompt "a serene mountain landscape at sunset" \
  --width 1024 \
  --height 768 \
  --steps 28 \
  --guidance 3

Example 2: High-Quality Cinematic Output

bfl --flux-ultra \
  --prompt "cinematic wide shot of a futuristic city" \
  --aspect-ratio "21:9" \
  --raw

Example 3: Image Editing with Kontext

bfl --kontext-pro \
  --prompt "transform into a watercolor painting" \
  --input-image ./photos/landscape.jpg

Example 4: Batch Generation

bfl --flux-dev \
  --prompt "a red apple" \
  --prompt "a green pear" \
  --prompt "a yellow banana" \
  --seed 42

Example 5: Redux Image-to-Image

bfl --flux-pro \
  --prompt "same style but at night" \
  --image-prompt ./reference.jpg \
  --width 1024 \
  --height 1024

Example 6: Inpainting with FLUX.1 Fill [pro]

# Using explicit mask (works with any image format)
bfl --flux-fill \
  --prompt "fill with lush green grass and flowers" \
  --image ./photos/landscape.jpg \
  --mask ./photos/landscape_mask.png \
  --steps 30 \
  --guidance 5

# Using PNG with alpha channel (no mask needed)
bfl --flux-fill \
  --prompt "remove object and fill background" \
  --image ./photos/image_with_transparency.png \
  --steps 28

Note: JPG/JPEG images require --mask parameter. PNG images can use alpha channel (transparency) as the mask.

Example 7: Image Expansion with FLUX.1 Expand [pro]

# Expand image on all sides
bfl --flux-expand \
  --prompt "extend with dramatic clouds and mountain vista" \
  --image ./photos/landscape.jpg \
  --top 512 --bottom 256 --left 256 --right 256 \
  --steps 30 \
  --guidance 60

# Vertical expansion only (portrait extension)
bfl --flux-expand \
  --prompt "add sky with clouds above and ground below" \
  --image ./photos/portrait.jpg \
  --top 1024 --bottom 512 \
  --steps 40

# Horizontal expansion with PNG output
bfl --flux-expand \
  --prompt "expand cityscape to the sides" \
  --image ./photos/city.jpg \
  --left 640 --right 640 \
  --output-format png \
  --prompt-upsampling

Note: Specify at least one direction (top, bottom, left, right) to expand. Use --prompt to guide what content should fill the expanded areas.

Example 8: Using API Class in Code

// If installed via npm
import { BflAPI } from 'bfl-api';
import { imageToBase64 } from 'bfl-api/utils';

// If running from source
import { BflAPI } from './src/api.js';
import { imageToBase64 } from './src/utils.js';

const api = new BflAPI();

// Convert local image to base64
const inputImage = await imageToBase64('./photo.jpg');

// Edit with Kontext Pro
const task = await api.generateKontextPro({
  prompt: 'make it look like a vintage photograph',
  input_image: inputImage
});

// Wait for result with auto-polling
const result = await api.waitForResult(task.id, {
  timeout: 300,
  showSpinner: true
});

console.log('Generated image:', result.result.sample);

Example 9: FLUX.2 [PRO] Text-to-Image

bfl --flux-2-pro \
  --prompt "a majestic castle on a cliff at sunset" \
  --width 1024 --height 1024

Example 10: FLUX.2 [PRO] Image Editing

bfl --flux-2-pro \
  --prompt "add a dragon flying in the sky" \
  --input-image ./castle.jpg \
  --width 1024 --height 1024

Example 11: FLUX.2 [FLEX] Multi-Reference

bfl --flux-2-flex \
  --prompt "combine the subject and style" \
  --input-image ./subject.jpg \
  --input-image-2 ./style_reference.jpg

Example 12: FLUX.2 [FLEX] Experimental Multiref (Up to 8 Images)

bfl --flux-2-flex \
  --prompt "create a scene combining all elements" \
  --input-image ./img1.jpg \
  --input-image-2 ./img2.jpg \
  --input-image-3 ./img3.jpg \
  --input-image-4 ./img4.jpg \
  --input-image-5 ./img5.jpg

Data Organization

Generated images and metadata are organized by model:

datasets/
└── bfl/
    ├── flux-dev/
    │   ├── 2025-01-13_14-30-22_mountain_landscape.jpg
    │   ├── 2025-01-13_14-30-22_mountain_landscape_metadata.json
    │   └── ...
    ├── flux-pro/
    │   └── ...
    ├── flux-ultra/
    │   └── ...
    ├── flux-pro-fill/
    │   └── ...
    ├── flux-2-pro/
    │   └── ...
    ├── flux-2-flex/
    │   └── ...
    ├── kontext-pro/
    │   └── ...
    └── kontext-max/
        └── ...

Metadata Format:

{
  "task_id": "abc123",
  "model": "flux-dev",
  "timestamp": "2025-01-13T14:30:22Z",
  "parameters": {
    "prompt": "a serene mountain landscape",
    "width": 1024,
    "height": 768,
    "steps": 28,
    "guidance": 3,
    "seed": 42
  },
  "result": {
    "status": "Ready",
    "image_url": "https://...",
    "image_path": "datasets/bfl/flux-dev/..."
  }
}

Security Features

This service implements production-ready security measures to protect your API keys and prevent common vulnerabilities:

API Key Protection

• Redacted Logging: API keys are never logged in full. Logs show only the last 4 characters (e.g., xxx...abc1234)
• Secure Storage: API keys read from environment variables or .env files (never committed to version control)
• Multiple Sources: Supports CLI flags, environment variables, local .env, and global config

Error Message Sanitization

• Production Mode: Set NODE_ENV=production to enable generic error messages
• Development Mode: Detailed error messages for debugging (default)
• Information Disclosure Prevention: Production errors don't reveal internal system details

# Enable production mode for sanitized errors
export NODE_ENV=production
bfl --flux-dev --prompt "a cat"

SSRF Protection (Server-Side Request Forgery)

When processing image URLs (for --image-prompt or --input-image), the service validates and blocks:

• Localhost Access: 127.0.0.1, ::1, localhost
• Private IP Ranges: 10.x.x.x, 192.168.x.x, 172.16-31.x.x
• Link-Local Addresses: 169.254.x.x (AWS/Azure metadata endpoints)
• Cloud Metadata: metadata.google.internal, 169.254.169.254
• IPv4-Mapped IPv6 Bypass Prevention: Detects and blocks [::ffff:127.0.0.1], [::ffff:10.0.0.1], etc.
• DNS Rebinding Prevention: Performs DNS resolution to block domains that resolve to internal/private IPs (prevents TOCTOU attacks via wildcard DNS services like nip.io)
• HTTP URLs: Only HTTPS URLs are accepted

This prevents attackers from using the service to access internal network resources, including sophisticated bypass attempts using IPv4-mapped IPv6 addresses and DNS rebinding attacks.

Image File Validation

• Magic Byte Checking: Validates PNG, JPEG, WebP, and GIF formats by actual file headers (not just extensions)
• File Size Limits: 50MB maximum for downloaded images (prevents memory exhaustion)
• Format Verification: Rejects non-image files masquerading as images
• Download Timeouts: 60-second timeout for image downloads (prevents slowloris attacks)

HTTPS Enforcement

• All API base URLs must use HTTPS protocol
• Constructor throws an error if HTTP URL is provided
• Prevents man-in-the-middle attacks

Request Timeout & Size Protection

• API Request Timeout: 30-second timeout for all API calls
• Download Timeout: 60-second timeout for image downloads
• Maximum File Size: 50MB limit for downloaded images
• Redirect Limits: Maximum 5 redirects to prevent redirect loops
• DoS Prevention: Prevents resource exhaustion and slowloris-style attacks

Parameter Validation

• Pre-flight validation using validateModelParams() before API calls
• Catches invalid parameters early (saves API credits)
• Validates:
  • Width/height (256-1440, divisible by 32)
  • Steps (1-50 for FLUX.1 [dev], 15-50 for FLUX.1 Fill [pro])
  • Guidance (1.5-5 for FLUX.1 [dev], 1.5-100 for FLUX.1 Fill [pro])
  • Aspect ratios (valid ratios like "16:9", "21:9")
  • Prompt length (max 10,000 characters)
  • Mask requirement (JPG/JPEG requires --mask parameter)

Error Handling

The service includes comprehensive error handling with retry logic:

Automatic Retries

Transient errors (network, 502, 503) are automatically retried with exponential backoff:

• Retry 1: 2 seconds
• Retry 2: 4 seconds
• Retry 3: 8 seconds

Non-Retriable Errors

• Content Moderation: Prompt flagged by safety filters
• Authentication (401): Invalid API key
• Validation (422): Invalid parameters
• Rate Limit (429): Too many requests

Polling with Spinner

The CLI shows an animated spinner during generation:

⠋ Generating... Pending (12s elapsed, ~288s remaining)

On completion:

✓ Generation complete! (45.2s)

Troubleshooting

API Key Not Found

Error: BFL_API_KEY not found in environment variables

Solution: Create .env file with your API key:

BFL_API_KEY=your_api_key_here

Content Moderated

Error: Content was moderated. Please revise your prompt.

Solution: Your prompt was flagged by safety filters. Try:

• Revising your prompt to be more appropriate
• Lowering --safety-tolerance (0-6, lower is stricter)

Authentication Failed

Error: Authentication failed. Please check your API key.

Solution:

1. Verify your API key is correct in .env
2. Check your account is active at https://docs.bfl.ml/quick_start/introduction
3. Generate a new API key if needed

Timeout

Error: Timeout after 300 seconds

Solution:

• Increase timeout: --timeout 600
• Complex generations may take longer
• Check API status at https://status.bfl.ml/

Module Not Found

Error: Cannot find module 'axios'

Solution: Install dependencies:

cd bfl-api
npm install

Development Scripts

Note: These npm scripts are only available when working from the source repository (cloned from GitHub). They are not available after installing via npm.

If you're using the installed package, use bfl (global) or npx bfl (local) instead.

For Source Development

npm run bfl              # Run CLI
npm run bfl:help         # Show help
npm run bfl:examples     # Show 15+ usage examples
npm run bfl:credits      # Check credits
npm run bfl:dev          # Use FLUX.1 [dev]
npm run bfl:pro          # Use FLUX 1.1 [pro]
npm run bfl:ultra        # Use FLUX Ultra
npm run bfl:kontext-pro  # Use Kontext Pro
npm run bfl:kontext-max  # Use Kontext Max

Pass additional flags with --:

npm run bfl:dev -- --prompt "a cat" --width 512 --height 512

Testing Commands

npm test                 # Run all 271 tests with Vitest
npm run test:watch       # Watch mode for development
npm run test:ui          # Interactive UI in browser
npm run test:coverage    # Generate coverage report (89.58% overall)

Test Coverage:

• Overall: 89.58% lines, 90.19% branches
• api.ts: 94.76% lines (all generation methods, polling, retries)
• utils.ts: 82.71% lines (file I/O, image conversion, validation)
• config.ts: 95.87% lines (parameter validation, configuration)

Tests validate actual behavior including:

• All 10 generation methods with proper request/response handling
• Comprehensive polling logic with timeout, retry, and exponential backoff
• Image conversion pipeline (file → base64, URL → base64)
• File I/O operations (read, write, directories)
• Security features (SSRF protection, API key redaction, error sanitization)
• Parameter validation (pre-flight checks to save API credits)

Rate Limits

BFL API rate limits vary by account tier. The service automatically:

• Polls every 2 seconds (configurable)
• Retries with exponential backoff on 429 errors
• Handles transient errors gracefully

Additional Resources

• BFL API Documentation
• BFL Website
• FLUX Models Overview
• API Status Page

Related Packages

This package is part of the img-gen ecosystem. Check out these other AI generation services:

• ideogram-api - Ideogram API wrapper for image generation, editing, remixing, and manipulation
• stability-ai-api - Stability AI API wrapper for Stable Diffusion 3.5 and image upscaling
• google-genai-api - Google Generative AI (Imagen) wrapper
• openai-api - OpenAI API wrapper for DALL-E and GPT Image generation

Disclaimer: This project is an independent community wrapper and is not affiliated with Black Forest Labs.

License

This project is licensed under the MIT License (with Extra Silliness) - see the LICENSE file for details.

By using this software, you agree to generate at least one image of a cat wearing sunglasses (optional but encouraged).

Note: This service implements image generation endpoints. Fine-tuning endpoints can be added as needed following the same patterns established in the API class.