> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bfl.ml/llms.txt
> Use this file to discover all available pages before exploring further.

# FLUX 3 Text to Image

> Send your first FLUX 3 Image request, write a text-to-image prompt, and read the result.

FLUX 3 Image

# FLUX 3 Text to Image

Generate an image from a prompt with one request.

## Quickstart

Send a prompt to generate an image. This one produces a risograph illustration of a rabbit riding a pumpkin:

![A two-color risograph illustration of a green rabbit riding a large orange pumpkin down a winding path through rolling hills.](https://cdn.sanity.io/images/2gpum2i6/production/14589d6c575bd8da3d7a6572334283a98d84da63-1800x1011.webp)

Set `BFL_API_KEY` to a key from the [BFL dashboard](https://dashboard.bfl.ai), then submit:

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.bfl.ai/v1/flux-3-image",
    headers={"x-key": os.environ["BFL_API_KEY"]},
    json={
        "prompt": "A two-color risograph narrative illustration with porous ink, soft misregistration, and cheerful simple shapes: a rabbit rides a pumpkin along a winding path through three layers of rolling hills. No text.",
        "aspect_ratio": "16:9",
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```bash cURL theme={null}
curl --fail-with-body https://api.bfl.ai/v1/flux-3-image \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A two-color risograph narrative illustration with porous ink, soft misregistration, and cheerful simple shapes: a rabbit rides a pumpkin along a winding path through three layers of rolling hills. No text.",
    "aspect_ratio": "16:9"
  }'
```

Poll the returned `polling_url` until `status` is `Ready`:

```bash cURL theme={null}
curl "$POLLING_URL" -H "x-key: $BFL_API_KEY"
```

When `status` is `Ready`, download the image from `result.sample`.

> [!WARNING]
>
> The signed URL in `result.sample` expires after **1 hour**. Download the
> image right away rather than storing the URL, and don't send your `x-key`
> header to it.

> [accordion] Complete clients: submit, poll, and save
>
> Each client submits the Quickstart prompt, polls until the task finishes, and
> saves the image. The Python `generate()` function is used in the examples
> below. The cURL client requires `jq`.
>
> ```python Python theme={null}
> import os
> import time
>
> import requests
>
> API_KEY = os.environ["BFL_API_KEY"]
>
>
> def generate(payload, name="flux3_image"):
>     submit = requests.post("https://api.bfl.ai/v1/flux-3-image",
>                            headers={"x-key": API_KEY}, json=payload, timeout=60)
>     submit.raise_for_status()
>     polling_url = submit.json()["polling_url"]
>
>     while True:
>         time.sleep(1.5)
>         result = requests.get(polling_url, headers={"x-key": API_KEY}, timeout=60).json()
>         if result["status"] not in ("Pending", "Reasoning", "Generating"):
>             break
>     if result["status"] != "Ready":
>         raise RuntimeError(result)
>
>     image = requests.get(result["result"]["sample"], timeout=120)
>     with open(name + ".png", "wb") as f:
>         f.write(image.content)
>     return name + ".png"
>
>
> generate({
>     "prompt": "A two-color risograph narrative illustration with porous ink, soft misregistration, and cheerful simple shapes: a rabbit rides a pumpkin along a winding path through three layers of rolling hills. No text.",
>     "aspect_ratio": "16:9",
> })
> ```
>
> ```javascript JavaScript theme={null}
> // Node.js 18+
> import { writeFile } from "node:fs/promises";
>
> const headers = { "x-key": process.env.BFL_API_KEY, "Content-Type": "application/json" };
>
> const submit = await fetch("https://api.bfl.ai/v1/flux-3-image", {
>   method: "POST",
>   headers,
>   body: JSON.stringify({
>     prompt: "A two-color risograph narrative illustration with porous ink, soft misregistration, and cheerful simple shapes: a rabbit rides a pumpkin along a winding path through three layers of rolling hills. No text.",
>     aspect_ratio: "16:9",
>   }),
> });
> if (!submit.ok) throw new Error(await submit.text());
> const { polling_url } = await submit.json();
>
> let result;
> do {
>   await new Promise((resolve) => setTimeout(resolve, 1500));
>   result = await (await fetch(polling_url, { headers })).json();
> } while (["Pending", "Reasoning", "Generating"].includes(result.status));
> if (result.status !== "Ready") throw new Error(JSON.stringify(result));
>
> const image = await fetch(result.result.sample);
> await writeFile("flux3_image.png", Buffer.from(await image.arrayBuffer()));
> ```
>
> ```bash cURL theme={null}
> POLLING_URL=$(curl -s --fail-with-body https://api.bfl.ai/v1/flux-3-image \
>   -H "x-key: $BFL_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"prompt": "A two-color risograph narrative illustration with porous ink, soft misregistration, and cheerful simple shapes: a rabbit rides a pumpkin along a winding path through three layers of rolling hills. No text.", "aspect_ratio": "16:9"}' | jq -r .polling_url)
>
> while true; do
>   RESULT=$(curl -s "$POLLING_URL" -H "x-key: $BFL_API_KEY")
>   STATUS=$(echo "$RESULT" | jq -r .status)
>   [[ "$STATUS" =~ ^(Pending|Reasoning|Generating)$ ]] || break
>   sleep 1.5
> done
>
> if [ "$STATUS" = "Ready" ]; then
>   curl -s -o flux3_image.png "$(echo "$RESULT" | jq -r .result.sample)"
> else
>   echo "$RESULT"
> fi
> ```

Send only `prompt` to generate a new image. When you add `images`, describe how to use them in `prompt`. There is no `mode` field.

| What you want | What to send | Example |
| - | - | - |
| A new image from a description | `prompt` | [Text to image](#text-to-image) |
| A change to one image, such as a detail or its style | `prompt` + that image | [Edit with an instruction](https://docs.bfl.ml/flux_3/flux3_image_layout.md#edit-with-an-instruction) |
| A restyle or new composition from several images | `prompt` + 2 to 10 images | [Multi reference](https://docs.bfl.ml/flux_3/flux3_image_layout.md#multi-reference) |

The endpoint rejects unknown fields with HTTP `422`, so fields from other BFL
endpoints, such as `seed` and `input_image`, don't work here. The
[API reference](https://docs.bfl.ml/api-reference/utility/generate-an-image-with-flux-3.md) lists
every accepted field.

## Text to image

Describe the subject, setting, light, and framing in `prompt`.

![Two red pandas resting on bamboo beams among green leaves, one alert and one asleep.](https://cdn.sanity.io/images/2gpum2i6/production/eef1a577855ea42fef99bf437c725c8323d0f1c8-1800x1013.webp)

Two red pandas resting on bamboo beams, one looking relaxed and the other asleep. Their reddish-brown fur and white facial markings stand out against the soft, blurred natural background, suggesting a peaceful, sunny environment.

```python theme={null}
generate({
    "prompt": (
        "Two red pandas resting on bamboo beams, one looking relaxed and the other asleep. "
        "Their reddish-brown fur and white facial markings stand out against the soft, "
        "blurred natural background, suggesting a peaceful, sunny environment."
    ),
    "aspect_ratio": "16:9",
    "resolution": "4k",
}, name="red_pandas")
```

To put text in the image, quote it exactly and say where it goes, for example
`a paper poster on the wall that reads "OPEN LATE"`. To choose where each
element appears, add [bounding boxes](https://docs.bfl.ml/flux_3/flux3_image_layout.md) to the end
of the prompt. The [prompting guide](https://docs.bfl.ml/guides/prompting_summary.md) covers
structure, style, lighting, and typography in depth.

## Examples

Each image below was generated with FLUX 3 Image. Copy its prompt to start from it.

### Photorealistic

Previous clip

Next clip

### Typography & Design

Previous clip

Next clip

### Infographics

Previous clip

Next clip

### Illustration

Previous clip

Next clip

## Results and errors

The submit response returns immediately with `id`, `polling_url`, `cost`,
`input_mp`, and `output_mp`. Always poll the returned `polling_url`. It points
at the region that holds your task, so don't build the URL yourself.

| Status | Meaning | What to do |
| - | - | - |
| `Pending`, `Reasoning`, `Generating` | In progress | Keep polling |
| `Ready` | Done. The image URL is in `result.sample` | Download it within 1 hour |
| `Request Moderated` | The prompt or an input image was blocked | Change the input; retrying unchanged fails again |
| `Content Moderated` | The generated image was blocked | Adjust the prompt and resubmit |
| `Error` | The task failed | Inspect the body; resubmit if the error was transient |
| `Task not found` | The id is unknown or has expired | Submit a new request |

A `Ready` result also includes `result.prompt`, the expanded prompt the model
used, and `result.duration`, the generation time in seconds. Read
`result.prompt` to see how FLUX 3 interpreted a short prompt or an edit.

A failed task can come back as HTTP `503` with a normal JSON body. Read
`status` from the body before treating a `503` as a retryable outage.
Submission errors specific to this endpoint:

| HTTP | Cause | Fix |
| - | - | - |
| `400` | A reference image is larger than 16 megapixels | Downscale it to 16 megapixels or less |
| `422` | Unknown field, blank prompt, invalid value, or an image smaller than 256 × 256 | The response `detail` names the field |

For `402` (out of credits), `429` (rate limited), and other codes shared by
every endpoint, see [Errors](https://docs.bfl.ml/api_integration/errors.md). To run many requests in
production, see the [integration guidelines](https://docs.bfl.ml/api_integration/integration_guidelines.md).

## Keep exploring

> [card] [Try in Playground](https://playground.bfl.ai)
>
> Try FLUX 3 Image in your browser, with no code.

> [card] [Prompting guide](https://docs.bfl.ml/guides/prompting_summary.md)
>
> Structure, style, lighting, text, and editing prompts for FLUX 3.

> [card] [API reference](https://docs.bfl.ml/api-reference/utility/generate-an-image-with-flux-3.md)
>
> The full request schema, limits, and response codes.

> [card] [Bounding boxes](https://docs.bfl.ml/flux_3/flux3_image_bounding_boxes.md)
>
> Place each element with a box, then edit box by box.

> [card] [FLUX 3 Image overview](https://docs.bfl.ml/flux_3/flux3_image_overview.md)
>
> Sample images and what the model can do.

> [card] [FLUX 3 Image Editing](https://docs.bfl.ml/flux_3/flux3_image_layout.md)
>
> Place elements and target edits with bounding boxes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.