Flux 2 by Black Forest Labs is one of the most capable text-to-image models available today, and calling it from your own code takes only a few lines. Whether you are building a product feature, automating creative assets, or experimenting with AI-generated visuals, this guide covers the exact cURL and Python snippets you need to get started with three popular API providers.

What You Need Before Starting

Before running any of the examples below, prepare the following:

• An API key from at least one provider: Black Forest Labs (BFL), fal.ai, or Together AI. Sign up on their dashboards to generate one.
• Python 3.8 or later if you want to use the Python examples. Install the requests library with pip install requests if it is not already available.
• cURL installed in your terminal. It ships with macOS and most Linux distributions by default. On Windows, it comes bundled with Git Bash or can be installed via winget.

Flux 2 comes in several variants that suit different needs. Flux 2 Pro is the general-purpose option with the best balance of quality and speed. Flux 2 Max produces higher-detail outputs at higher cost. Flux 2 Flash is faster and cheaper, suited for previews or draft iterations. All three are available through the providers covered in this guide, and you can find detailed breakdowns of each variant in the Flux 1.1 Pro overview.

Option 1: Black Forest Labs Official API

The official BFL API gives you direct access to Flux 2 Pro without a middleman. Authentication uses an x-key header, and the response pattern is asynchronous: you submit a job and poll for the result.

cURL

curl -X POST https://api.bfl.ai/v1/flux-2-pro \
  -H "Content-Type: application/json" \
  -H "x-key: $BFL_API_KEY" \
  -d '{
    "prompt": "A futuristic city at sunset with glass towers reflecting golden light",
    "width": 1024,
    "height": 768,
    "safety_tolerance": 2
  }'

The response returns a task ID. Poll https://api.bfl.ai/v1/get_result?id=TASK_ID until the status field reads Ready, then grab the image URL from the result object. This async pattern is common across AI image generation APIs and keeps request timeouts short even for complex prompts.

Python

The same request in Python uses the requests library and a simple polling loop:

import requests, time, os
BFL_API_KEY = os.environ["BFL_API_KEY"]
headers = {"Content-Type": "application/json", "x-key": BFL_API_KEY}
response = requests.post(
    "https://api.bfl.ai/v1/flux-2-pro",
    headers=headers,
    json={
        "prompt": "A futuristic city at sunset with glass towers reflecting golden light",
        "width": 1024,
        "height": 768,
    },
)
task_id = response.json()["id"]
while True:
    result = requests.get(
        f"https://api.bfl.ai/v1/get_result?id={task_id}",
        headers=headers,
    ).json()
    if result["status"] == "Ready":
        print(result["result"]["sample"])
        break
    time.sleep(1)

The BFL API charges per image with no subscription required. You can also pass a seed parameter for reproducible outputs, which is useful when you need consistent results across automated image pipelines. The Recraft V3 comparison shows how Flux 2 stacks up against other models when quality and prompt fidelity are your primary concerns.

Option 2: fal.ai

fal.ai wraps Flux 2 in a synchronous endpoint, so you get the image back in a single request without polling. The trade-off is slightly higher latency per call, but the simpler integration often makes it worth it for prototyping and smaller projects. If you are new to the Flux model family, read the Flux Krea overview for context on how different variants compare.

cURL

curl -X POST https://fal.run/fal-ai/flux-2-pro \
  -H "Authorization: Key $FAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city at sunset with glass towers reflecting golden light",
    "image_size": "landscape_16_9"
  }'

Python

import requests
import os

response = requests.post(
    "https://fal.run/fal-ai/flux-2-pro",
    headers={
        "Authorization": f"Key {os.environ['FAL_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "prompt": "A futuristic city at sunset with glass towers reflecting golden light",
        "image_size": "landscape_16_9",
    },
)
print(response.json()["images"][0]["url"])

fal.ai also provides a dedicated Python SDK (pip install fal-client) that adds queue-based submission and webhook callbacks. The SDK handles retries and backpressure automatically, which is helpful when you need to chain Flux 2 with post-processing steps like upscaling or background removal. For a full AI image editing suite that connects Flux 2 to other models in a visual canvas, look at platforms that offer node-based workflow builders with REST API access.

Option 3: Together AI

Together AI offers Flux 2 through an OpenAI-compatible images endpoint. If your application already uses the OpenAI SDK, switching to Flux 2 requires changing only the model string and base URL. For background on how different prompt strategies affect output quality, experiment with the prompt generator before writing production code.

cURL

curl -X POST https://api.together.xyz/v1/images/generations \
  -H "Authorization: Bearer $TOGETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs/FLUX.2-pro",
    "prompt": "A futuristic city at sunset with glass towers reflecting golden light",
    "width": 1024,
    "height": 768,
    "steps": 28,
    "n": 1,
    "response_format": "url"
  }'

Python

from together import Together
import os

client = Together(api_key=os.environ["TOGETHER_API_KEY"])
response = client.images.generate(
    model="black-forest-labs/FLUX.2-pro",
    prompt="A futuristic city at sunset with glass towers reflecting golden light",
    width=1024,
    height=768,
    steps=28,
    n=1,
)
print(response.data[0].url)

Install the SDK with pip install together. The OpenAI-compatible interface makes it easy to A/B test different image generation models by swapping a single string in your configuration.

Comparing the Three Providers

Feature	BFL (Official)	fal.ai	Together AI
Auth method	x-key header	Key bearer	Bearer token
Response style	Async (poll)	Synchronous	Synchronous
Python SDK	No official SDK	fal-client	together
OpenAI compatible	No	No	Yes
Image size control	Width/height pixels	Named presets	Width/height pixels
Pricing model	Per-image	Per-image	Per-image
Flux 2 variants	Pro, Max, Flash	Pro, Flash	Pro, Flex, Max

Choose BFL when you want the latest model versions first. Choose fal.ai for the simplest single-call integration. Choose Together AI when your codebase already uses OpenAI-compatible endpoints and you want a drop-in replacement.

Tips for Production Use

Building a reliable Flux 2 integration takes more than copy-pasting the examples above. Here are practical patterns that apply regardless of provider.

1. Set timeouts generously. Image generation can take 5 to 30 seconds depending on model variant and server load. Set your HTTP client timeout to at least 60 seconds for synchronous endpoints. The same timeout logic applies whether you are calling Flux 2 directly or through a no-code workflow builder.

1. Cache by prompt hash. If users submit the same prompt repeatedly, hash the prompt plus parameters and serve the cached result. This saves cost and improves response time.

1. Use webhooks for async flows. Both fal.ai and BFL support webhook callbacks. Instead of polling, provide a callback URL and let the provider push the result to your server. This is the same pattern used by workflow-based platforms that orchestrate multi-step AI pipelines.

1. Store images in your own bucket. Provider-hosted URLs expire after hours or days. Download the generated image and upload it to your own S3 or R2 bucket immediately after generation. Tools like PageSection’s web page translator can help localize alt text for international audiences once images are stored permanently.

1. Pin the model version. Some providers update default model versions without notice. Specify the exact model ID (e.g., black-forest-labs/FLUX.2-pro) rather than relying on aliases. Read the Flux model family overview for a full list of available model IDs and their capabilities.

1. Handle rate limits gracefully. Implement exponential backoff with jitter. Most providers return 429 when you exceed your plan limits.

Frequently Asked Questions

What is Flux 2 and how does it differ from Flux 1?

Flux 2 is the second-generation text-to-image model from Black Forest Labs. It improves on Flux 1 with better prompt adherence, higher detail in complex scenes, and more consistent text rendering inside images. The API interface is similar, so migrating existing Flux 1 code requires changing only the model ID and endpoint.

Is Flux 2 free to use via API?

No provider offers unlimited free access. BFL, fal.ai, and Together AI each charge per image. Some offer free trial credits for new accounts. Check each provider’s pricing page for current rates, or see the free AI image generator guide for options with generous free tiers.

Which Flux 2 variant should I choose?

Flux 2 Pro is the best general-purpose option for most applications. Flux 2 Max produces the highest-quality outputs at roughly double the cost. Flux 2 Flash is optimized for speed, producing acceptable results in under 2 seconds per image. You can compare outputs across variants using the Flux image generator.

Can I generate multiple images in one API call?

Together AI supports the n parameter to request multiple images per call. BFL and fal.ai require separate requests for each image, though you can fire them concurrently using async patterns or thread pools to build batch generation pipelines.

How do I handle content filtering?

BFL uses a safety_tolerance parameter ranging from 0 (strictest) to 6 (most permissive). fal.ai and Together AI have their own filtering controls. Review each provider’s acceptable use policy before deploying to production. The Flux Realtime guide covers how filtering differs across speed-optimized model variants.

What image dimensions does Flux 2 support?

BFL and Together AI accept arbitrary width and height values in multiples of 64, up to provider-specific maximums. fal.ai uses named presets like landscape_16_9, square_hd, and portrait_16_9. Check the headless workflow platform guide for tips on setting dimensions dynamically in automated pipelines.

Can I use Flux 2 for image-to-image tasks?

Yes. Both BFL and fal.ai accept an optional image input alongside the text prompt. Pass an image field with a base64-encoded or URL-referenced source image to guide the generation. This enables style transfer, inpainting, and visual editing workflows.

Conclusion

Calling Flux 2 from your own code is straightforward once you pick a provider and follow their authentication pattern. The BFL official API gives you the freshest model versions, fal.ai keeps integration simple with synchronous responses, and Together AI slots into existing OpenAI-compatible toolchains. For teams that want to combine Flux 2 with upscaling, background removal, or other AI models in a single pipeline, wireflow.ai provides both a visual canvas for building multi-step workflows and a REST API for executing them programmatically.