---
title: "Generate an image with FLUX 3."
method: POST
path: "/v1/flux-3-image"
tags: ["Models"]
---

# Generate an image with FLUX 3.

`POST /v1/flux-3-image`

## Request

- Base URL: `https://api.bfl.ai`
- URL: `https://api.bfl.ai/v1/flux-3-image`
- Auth: API key in header `x-key`
- TypeScript: <https://skmtc.dev/bfl/apis/bfl-api/docs/v1/flux-3-image/post.ts> (a function with typed inputs; its response is checked against the schema)

Submits an image generation task with FLUX 3.

## Request body

- Flux3ImageInputs
  - `user` string, nullable: Opaque identifier for the end user supplied by the calling platform.
  - `prompt` string, required: Free-form prompt describing the image.
  - `images` union: Optional reference image(s) the prompt edits or draws from; each is an http(s) URL or base64, one to 10 total.
    - string
    - string[]
  - `aspect_ratio` union: Output aspect ratio. Under `auto` a ratio the prompt asks for wins, otherwise the output keeps the first reference image's framing; without references the prompt decides, else 1:1.
    - '21:9' | '2:1' | '16:9' | '3:2' | '7:5' | '4:3' | '5:4' | '1:1' | '4:5' | '3:4' | '5:7' | '2:3' | '9:16' | '1:2' | '9:21'
    - 'auto'
  - `resolution` '768sq' | '1k' | '1.5k' | '2k' | '4k' | 'match_input': Image resolution class, an equal-pixel-area tier: `768sq`, `1k` (default), `1.5k`, `2k`, or `4k`. Exact dimensions vary with the aspect ratio. `match_input` (edits only): the output keeps the first reference's own size (shrunk to 4 MP when larger), or its nearest tier when aspect_ratio is set. Ignored when width and height are set.
  - `width` integer, nullable: Exact output width in pixels, [256, 6256]; set together with height. Overrides resolution and aspect_ratio.
  - `height` integer, nullable: Exact output height in pixels, [256, 6256]; width x height at most 16822272 pixels, and at most 4194304 with reference images.
  - `safety_tolerance` integer: Harm moderation tolerance from 0 to 7, with 0 the strictest. The route and organization determine the approved maximum and per-category ceilings. Unapproved levels return 422 with approved levels.
  - `grounding` boolean: When true (default) the prompt may be grounded in external research: web search and image search. When false, both are off.
  - `version` 'latest': Endpoint version. `latest` (default) serves the current release; dated pinnable release tags are added here as they are published.

## Response `200`

Successful Response

- AsyncResponse
  - `id` string, required
  - `polling_url` string, required
  - `cost` number, nullable: Cost in credits for this request
  - `input_mp` number, nullable: Input megapixels (2 decimal places)
  - `output_mp` number, nullable: Output megapixels (2 decimal places)

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-22** `ea458c661ef8`: 3 info
  - added the new optional request property `height`
  - added the new optional request property `width`
  - added the new `match_input` enum value to the request property `resolution`
- **2026-10-21** `ab75e0a84610`: 1 info
  - added the new optional request property `user`
- **2026-10-12** `50c3640d9e08`: 1 info
  - the `safety_tolerance` request property's max was increased from `4.00` to `7.00`
- **2026-10-01** `f16a6c6836ea`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bfl/apis/bfl-api/changes/v1/flux-3-image/post.md)

---

[API](https://skmtc.dev/bfl/apis/bfl-api.md) - [All operations](https://skmtc.dev/bfl/apis/bfl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bfl/apis/bfl-api/revisions/ea458c661ef8?raw)