Quickstart Guide

Last updated: April 2, 2026

Quickstart Guide

Before You Begin

To get started, you need:

  • A Black Forest Labs account (dashboard.bfl.ai)

  • A positive credit balance

  • Your API key (available in your account dashboard)

Generate an Image with FLUX.2

FLUX.2 is our latest generation of image models. Here's how to generate your first image:

# Install requests: pip install requests
import os
import requests
import time

API_KEY = os.environ.get("BFL_API_KEY")

# Submit a generation request
response = requests.post(
    "https://api.bfl.ai/v1/flux-2-pro",
    headers={
        "accept": "application/json",
        "x-key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "prompt": "A serene mountain lake at sunset, golden light reflecting off the water",
        "width": 1024,
        "height": 1024
    },
).json()

polling_url = response["polling_url"]
print(f"Polling URL: {polling_url}")

# Poll for the result
while True:
    result = requests.get(polling_url).json()
    if result["status"] == "Ready":
        print(f"Image URL: {result['result']['sample']}")
        break
    elif result["status"] in ["Error", "Failed", "Request Moderated", "Content Moderated"]:
        print(f"Generation failed: {result['status']}")
        break
    time.sleep(0.5)

How the API Works

The BFL API uses an asynchronous pattern:

  1. Submit a request — you get back a polling_url

  2. Poll the URL until the status is Ready

  3. Download the image from the result URL (valid for 10 minutes)

Always use the polling_url returned in the response — don't reconstruct it manually.

Next Steps