FLUX API: Black Forest Labs Integration, Pricing, and Provider Differences

“FLUX API” can mean Black Forest Labs’ own API or a separate service that offers access to FLUX models. Their API keys, endpoints, prices, model identifiers, and terms are not interchangeable. This guide focuses on direct Black Forest Labs (BFL) access and its documented FLUX.2 Pro image-generation flow.

BFL’s API is asynchronous: submit a generation request, poll the polling_url returned in the response, then download the image from the result URL. BFL’s quick start shows x-key authentication. (BFL quick start) (help.bfl.ai)

Which FLUX API are you looking for?

• Black Forest Labs API: Choose this route to integrate directly with BFL. Its documentation covers BFL accounts, project-scoped API keys, image endpoints, and asynchronous result retrieval. (BFL API documentation)
• A third-party FLUX provider: Services such as FluxAPI.ai and AIMLAPI describe their own offerings. Use the selected provider’s credentials, API reference, pricing, and terms—not BFL’s instructions by default.
• The api.flux.ai key guide: This explains how to create a key through a Flux.ai account. The guide does not establish that this key is for BFL’s image-generation API.

The example below is for direct BFL access, not a third-party service.

Before you start

You need a BFL account, an API key, credits, and Python with the requests package installed. BFL’s quick start says to create a key under API → Keys in the relevant project. Store it securely and do not expose it in client-side code. (BFL API documentation)

Install the dependency and set the key in your shell:

pip install requests
export BFL_API_KEY='your_api_key_here'

Keep the key on a server or in a secrets manager—not in a browser, mobile app, or public repository.

Make a FLUX.2 Pro image-generation request

BFL documents a POST request to /v1/flux-2-pro with a prompt, width, and height. The response includes a polling_url; poll that returned URL rather than constructing one yourself. The sample adds a timeout and basic HTTP error handling. (BFL image-generation guide)

import os
import time
import requests

api_key = os.environ['BFL_API_KEY']
headers = {
    'accept': 'application/json',
    'x-key': api_key,
    'Content-Type': 'application/json',
}

# Submit the generation task.
response = requests.post(
    'https://api.bfl.ai/v1/flux-2-pro',
    headers=headers,
    json={
        'prompt': 'A serene mountain lake at sunset, golden light reflecting off the water',
        'width': 1024,
        'height': 1024,
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()
polling_url = task['polling_url']

# Poll the exact URL returned by BFL.
deadline = time.monotonic() + 300
while time.monotonic() < deadline:
    result_response = requests.get(
        polling_url,
        headers={'accept': 'application/json', 'x-key': api_key},
        timeout=30,
    )
    result_response.raise_for_status()
    result = result_response.json()
    status = result.get('status')

    if status == 'Ready':
        image_url = result['result']['sample']
        image_response = requests.get(image_url, timeout=60)
        image_response.raise_for_status()
        with open('flux-result.png', 'wb') as image_file:
            image_file.write(image_response.content)
        print('Saved flux-result.png')
        break

    if status in {'Error', 'Failed', 'Request Moderated', 'Content Moderated'}:
        raise RuntimeError(f'FLUX generation ended with status: {status}')

    time.sleep(0.5)
else:
    raise TimeoutError('FLUX generation did not finish within five minutes')

Result flow: BFL’s quick start shows the downloadable image URL in result.sample, lists Ready as the successful status, and identifies Error, Failed, Request Moderated, and Content Moderated as failure outcomes. It says the result URL is valid for 10 minutes, so download the image promptly. (help.bfl.ai)

The example calls raise_for_status() for HTTP errors but does not assign meanings to particular HTTP status codes. Check BFL’s current error documentation before adding provider-specific error handling or retry behavior.

Choose a model endpoint from BFL’s documentation

BFL distinguishes flux-2-pro, a fixed snapshot for workflows that require reproducibility, from flux-2-pro-preview, which reflects its latest advances. Confirm the current endpoint and request schema in BFL’s API documentation before deployment. (BFL image-generation guide)

BFL API pricing, limits, and terms

Pricing depends on model and output size. BFL’s cost information lists FLUX.2 Pro text-to-image generation from US$0.03 per megapixel and says resolution rounds up to the next megapixel. A 1024 × 1024 image is 1.048576 decimal megapixels, so it should not be treated as a confirmed one-megapixel bill. The available rate and rounding information do not establish the exact charge for this example; check BFL’s current pricing and request-cost details before budgeting. BFL’s pricing overview says one credit equals US$0.01 and API and Playground pricing are the same. (BFL cost information; pricing overview)

Plan for concurrency, not just requests per minute. BFL’s concurrency help page reports a default limit of 24 active requests and a separate limit of 6 active tasks for flux-kontext-max. Check the limit that applies to your account and selected model before sizing a high-volume deployment. (BFL concurrency limits)

Review the terms for your region and application. BFL’s API terms state that the captured terms apply outside the EU and direct EU residents to separate EU terms. They describe a license for integrations inside the developer’s own application, not permission under those terms to offer a general-purpose BFL endpoint for other developers’ products. They also describe BFL’s rights to use submitted Inputs and generated Outputs to operate and improve its services, including for model training. Review the applicable current terms and usage policy before sending sensitive inputs or launching a product. (BFL API terms)

Production checklist

Before release, confirm that:

1. Your account, API key, endpoint, and terms all belong to the same provider.
2. The model endpoint and request fields match that provider’s current API reference.
3. Your server keeps the API key secret and downloads generated results before their temporary URLs expire.
4. Your integration handles pending tasks, documented terminal statuses, HTTP errors, and concurrency limits.
5. Your cost estimate uses the selected model’s current rate and billing unit, including output-size differences.
6. Your region, intended application, and input/output handling comply with the terms that apply to your account.

Do not copy conflicting endpoint details from third-party tutorials into a BFL integration. A host, credential, model ID, or billing rate documented for one provider does not establish that it works for another.

Sources

How do I get started with the API? — Black Forest Labs Help Center

Quick Start — Black Forest Labs

Image Generation with Text Prompts — Black Forest Labs

What are the costs associated with using your models? — Black Forest Labs Help Center

Pricing Overview — Black Forest Labs

What is the concurrency limit for the API? — Black Forest Labs Help Center

FLUX API Service Terms — Black Forest Labs