FLUX API: Endpoints, Limits and Pricing

The FLUX API has one design decision that trips up almost every first integration: it is asynchronous. You do not POST a prompt and get an image back. You POST a prompt, get a job ID and a polling URL, then poll until the status flips to Ready — and the URL you finally receive expires in ten minutes.

Get that wrong and you will build a synchronous wrapper that times out. Get it right and the rest is straightforward.

Sourcing note: every endpoint, limit, status code, and price below comes from Black Forest Labs' own API documentation and pricing page. Code patterns follow the shapes in BFL's official quick-start. Nothing is reconstructed from third-party wrappers or hosting resellers. Last verified July 29, 2026.

What this guide solves

The pain point: most FLUX API write-ups are reseller marketing. They show you a one-line SDK call on someone else's platform and skip the parts that actually break in production — the polling contract, the 24-task ceiling, the ten-minute URL, and the missing CORS headers.

The differentiator: this is the direct-to-BFL integration, including the operational details that only show up when your first job queue backs up: what a 429 means, what a 402 means, and why you should never serve BFL's delivery URLs straight to your users.

The request pattern

Two steps, always.

1. Submit

POST https://api.bfl.ai/v1/<endpoint> with your key in an x-key header and a JSON body containing at minimum a prompt, plus optional width and height.

The response is a JSON object with an id and a polling_url. Keep the polling URL — when you use the global or regional endpoints, BFL's docs state you must poll the returned URL rather than constructing your own.

2. Poll

GET the polling_url with the same x-key header, on a short interval (BFL's own example sleeps 0.5s between polls). Read status:

The ten-minute rule: result.sample is a signed URL and BFL states it is valid for only 10 minutes. Download the bytes inside that window. If your pipeline hands the URL to a frontend that renders it an hour later, you will ship broken images.

Endpoints

Global endpoint: api.bfl.ai. Regional: api.eu.bfl.ai and api.us.bfl.ai. BFL recommends the global or regional hosts for inference.

The image-generation endpoints currently documented:

Preview vs pinned is a real decision, not a naming quirk. Preview endpoints track BFL's latest improvements — good for quality, bad for regression testing. If you have golden-image tests or a client contract about consistency, pin to the snapshot endpoints.

Limits you will actually hit

• 24 active tasks. Exceed it and you get 429; you must wait for a task to finish. This is a concurrency ceiling, not a requests-per-second quota — your queue design should cap in-flight jobs at 24, not throttle by rate.
• 6 active tasks for flux-kontext-max, which BFL attributes to capacity. If you route to Kontext Max, give it its own smaller semaphore.
• 402 means out of credits, not a bad request. Sign in at api.bfl.ai and top up. Worth alerting on separately from 4xx validation errors — the fix is billing, not code.
• Higher volume goes through BFL directly at their published contact address rather than a self-serve tier bump.

Delivery URLs: the mistake to avoid

Results are served from region-specific hosts under delivery.*.bfl.ai. Three things follow from BFL's documentation:

1. Whitelist the wildcard, not individual regions — BFL says region identifiers change as clusters are added or removed.
2. CORS is not enabled on delivery URLs. Browser-side fetches will fail.
3. Do not serve them to users. BFL explicitly recommends downloading the image and re-serving from your own infrastructure. Combined with the 10-minute expiry, this makes "download to your own object storage on completion" the only sane pipeline.

---

Prototyping the prompt side before you write the integration? Flux 3 AI is a browser workspace for exactly that — iterate on prompts and reference images, find the ones that work, then hard-code those into your API calls. Open the image generator.

---

What it costs

BFL bills per megapixel, and the billing rules matter more than the headline number:

The rules that change your bill:

• 1 MP = 1024×1024 px.
• Resolution rounds up to the next MP, separately for the output and each reference image.
• Every reference image counts as at least 1 MP. A pro-tier edit with four references costs the generation plus four reference charges — not the sticker price.
• Images above 4MP are resized to 4MP, so paying for more does not get you more.

If you are budgeting a multi-reference product-photography pipeline, model the reference charges first. They usually dominate.

The MCP route

BFL now ships an official FLUX MCP server, documented as a way to generate and edit images inside Claude, Cursor, Codex, and similar agent tooling. If your use case is "let an agent make images during a task" rather than "generate images in a product," that is a lower-friction path than wiring the REST API yourself.

A minimal integration checklist

• Key in x-key header, never in a query string or client bundle
• Store polling_url from the submit response — do not construct it
• Poll on a sub-second interval; handle Ready, Error, Failed, and "still running" separately
• Download result.sample within 10 minutes, then re-serve from your own storage
• Cap in-flight jobs at 24 (6 for Kontext Max)
• Treat 429 as backpressure, 402 as a billing alert
• Pin to snapshot endpoints if you need reproducibility
• Budget reference images as separate megapixel charges

FAQ

Is the FLUX API synchronous? No. Submit returns a job ID and polling URL; you poll for the result.

How do I authenticate? An x-key header carrying your API key.

What is the rate limit? 24 active tasks, or 6 for flux-kontext-max. Over the limit returns 429.

How long are result URLs valid? 10 minutes, per BFL's documentation. Download within that window.

Which endpoint should I start with? BFL points new integrations at flux-2-pro-preview as the latest and most capable, with flux-2-klein-4b as the cheapest.

What is the cheapest FLUX API call? FLUX.2 [klein] 4B at $0.014 for the first megapixel.

Can I call the API from the browser? Not for delivery URLs — CORS is not enabled on delivery.*.bfl.ai, and your key should not be in client code anyway. Proxy through your backend.

Is there a FLUX 3 API? Not publicly. FLUX 3 is in request-gated early access with no published pricing or endpoints.

Bottom line

The FLUX API is small and predictable once you accept the async contract: submit, poll, download fast, re-serve yourself. The two things that bite teams in week one are the 24-task ceiling and the ten-minute URL — design for both on day one and the integration is a couple of hundred lines.

If you are still figuring out what to generate rather than how to call it, prototype the prompts in the Flux 3 AI workspace first — cheaper than debugging your queue with unfinished prompts.

Sources

1. Image generation quick start (BFL API documentation) — async pattern, endpoints, polling, signed-URL expiry, rate limits, 402/429 behaviour, delivery-host guidance
2. BFL documentation overview — model family, MCP, playground and self-hosting routes
3. BFL API pricing — per-megapixel prices and billing rules
4. FLUX.2 pro / flex model page — multi-reference behaviour that drives reference-image billing
5. FLUX.2 max model page — top-tier capabilities
6. FLUX.2 klein model page — low-latency variants exposed via API
7. Official FLUX.2 prompting guide — prompt structure to encode in your calls
8. FLUX.2: Frontier Visual Intelligence (BFL, November 25, 2025) — model family the API exposes
9. black-forest-labs/flux on GitHub — reference inference code for self-hosted alternatives
10. FLUX open weights licensing — when self-hosting replaces API calls

Scope note: endpoints, limits and prices as of July 29, 2026 — check docs.bfl.ai before committing to a design. Flux 3 AI is an independent creator workspace, not affiliated with Black Forest Labs and not a FLUX API reseller.