## Quickstart
Send a prompt to generate an image. This one produces a risograph illustration of a rabbit riding a pumpkin:
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`.
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.
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](/flux_3/flux3_image_layout#edit-with-an-instruction) |
| A restyle or new composition from several images | `prompt` + 2 to 10 images | [Multi reference](/flux_3/flux3_image_layout#multi-reference) |
The endpoint rejects unknown fields with HTTP `422`, so fields from other BFL
endpoints, such as `seed`, `width`, and `input_image`, don't work here. The
[API reference](/api-reference/utility/generate-an-image-with-flux-3) lists
every accepted field.
## Text to image
Describe the subject, setting, light, and framing in `prompt`.
```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](/flux_3/flux3_image_layout) to the end
of the prompt. The [prompting guide](/guides/prompting_summary) 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
### Typography & Design
### Infographics
### Illustration
## 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](/api_integration/errors). To run many requests in
production, see the [integration guidelines](/api_integration/integration_guidelines).
## Keep exploring
Try FLUX 3 Image in your browser, with no code.
Structure, style, lighting, text, and editing prompts for FLUX 3.
The full request schema, limits, and response codes.
Place each element with a box, then edit box by box.
Sample images and what the model can do.
Place elements and target edits with bounding boxes.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
Set `BFL_API_KEY` to a key from the [BFL dashboard](https://dashboard.bfl.ai), then submit:
