FLUX image API

Purpose

Generate images with the FLUX.2 family via Black Forest Labs' official API: flux-2-pro for general text-to-image and native image editing, flux-2-flex for typography and text-heavy images. The quality bar for custom imagery in the catalog. Regional hosts exist for GDPR (api.eu.bfl.ai) and US (api.us.bfl.ai).

Tooling

All commands go through bin/black-forest-labs.py:

bin/black-forest-labs.py auth                                             # verify credential setup (no spend)
bin/black-forest-labs.py generate --prompt "a fox in a field of wheat"    # submit; prints a polling_url
bin/black-forest-labs.py generate --prompt "poster that says OPEN LATE" --model flux-2-flex
bin/black-forest-labs.py generate --prompt "..." --region https://api.eu.bfl.ai
bin/black-forest-labs.py status --polling-url 'https://api.bfl.ai/v1/get_result?id=...'   # poll until Ready
bin/black-forest-labs.py result --polling-url 'https://api.bfl.ai/v1/get_result?id=...'  # fetch the result

generate returns a polling_url. Poll status with backoff; when status is Ready, the response carries the sample download URL. --json merges extra fields (width, height, seed, input images for editing) into the request.

Auth

• Provider id: black-forest-labs (credential is collected as custom.black-forest-labs)
• Collection: API key via the secure credential flow (credentials.request_api_access); created at dashboard.bfl.ai
• Allowed hosts: api.bfl.ai, api.eu.bfl.ai, api.us.bfl.ai
• Status check: bin/black-forest-labs.py auth (must return "ok": true). The key is sent verbatim as the x-key header. Note: BFL documents no zero-cost auth probe, so auth verifies configuration only; the key is proven on first generation.