Black Forest Labs FLUX Free code examples in Python and JavaScript

A plain REST API — requests is all it needs. The key header is x-key, not Authorization, which is the first thing to check on a 401.

pip install requests

export BFL_API_KEY="your-key"     # macOS / Linux
setx BFL_API_KEY "your-key"       # Windows, then open a new shell

THE ENDPOINT IS THE MODEL. There is no model field in the body — /flux-2-pro and /flux-2-flex are different URLs. The response is an id and a polling_url, not an image.

import os
import requests

submitted = requests.post(
    "https://api.bfl.ai/v1/flux-2-pro",
    headers={
        "accept": "application/json",
        "x-key": os.environ["BFL_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "prompt": "A studio photograph of a brass microphone on a dark desk",
        "width": 1024,
        "height": 1024,
    },
    timeout=30,
).json()

print(submitted["id"], submitted["polling_url"])

Poll the URL THEY RETURNED. Results are served from region-specific hosts, so a rebuilt URL asks the wrong region and never sees the job finish. And handle all four failure states, or a moderated prompt loops forever.

import time

TERMINAL_FAILURES = {"Error", "Failed", "Request Moderated", "Content Moderated"}

def wait_for(polling_url: str, timeout_seconds: int = 300) -> str:
    deadline = time.monotonic() + timeout_seconds

    while time.monotonic() < deadline:
        time.sleep(0.5)

        result = requests.get(
            polling_url,
            headers={
                "accept": "application/json",
                "x-key": os.environ["BFL_API_KEY"],
            },
            timeout=30,
        ).json()

        status = result["status"]

        if status == "Ready":
            return result["result"]["sample"]

        if status in TERMINAL_FAILURES:
            raise RuntimeError(f"FLUX returned {status}")

    raise TimeoutError("FLUX job did not finish in time")

TEN MINUTES. The signed URL expires, so fetch the bytes in the same breath as the poll. Persisting the URL instead of the image is the mistake that only shows up the next day.

sample_url = wait_for(submitted["polling_url"])

# Do this now, not later. The URL is signed and short-lived.
image = requests.get(sample_url, timeout=60)
image.raise_for_status()

with open("microphone.png", "wb") as handle:
    handle.write(image.content)

For anything running in production, ask BFL to call you. Polling a queue of jobs at two requests a second per job is how a worker pool ends up doing nothing else.

submitted = requests.post(
    "https://api.bfl.ai/v1/flux-2-pro",
    headers={
        "accept": "application/json",
        "x-key": os.environ["BFL_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "prompt": "A studio photograph of a brass microphone on a dark desk",
        "width": 1024,
        "height": 1024,
        "webhook_url": "https://example.com/hooks/flux",
    },
    timeout=30,
).json()

# The callback carries the same status values as the poll, so the
# TERMINAL_FAILURES check above applies unchanged. Download the
# sample inside the handler — the ten-minute clock starts when the
# job finishes, not when you get round to it.