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

# FLUX 3 Image Generation

> Text-to-image, single-image editing, and up to 10 reference images, with multiple aspect ratios and resolution up to 4k.

<Info>
  This endpoint is asynchronous. A successful submission returns a `task_id`. Use [task queries](/en/api-reference/tasks/status) to retrieve status and images. Stop polling when the status is `completed` or `failed`. Generating at `4k` may take several minutes; a total wait timeout of 10 minutes is recommended.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "flux-3-image",
      "prompt": "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
      "aspect_ratio": "21:9",
      "resolution": "2k"
    }'
  ```

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

  response = requests.post(
      "https://api.apimart.ai/v1/images/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "flux-3-image",
          "prompt": "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
          "aspect_ratio": "21:9",
          "resolution": "2k"
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "flux-3-image",
      prompt: "Ultra-wide cinematic shot of a fog-drenched coastal highway at dawn, a single vintage car with headlights on",
      aspect_ratio: "21:9",
      resolution: "2k"
    })
  });
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer authentication in the format `Bearer <token>`, where `<token>` is your APIMart API Key.
</ParamField>

## Request parameters

<ParamField body="model" type="string" required>
  Must be `flux-3-image`.
</ParamField>

<ParamField body="prompt" type="string" required>
  A scene description for text-to-image, or image editing instructions. Negative prompts are not supported; describe what you want to see instead.

  Use tags and bbox JSON within `prompt` to specify layouts or local editing regions. See the examples below.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Reference image list, up to 10 images. Supports publicly accessible HTTP(S) URLs or Base64 input.

  Omit for text-to-image. Provide one image for single-image editing or multiple images for multi-image reference.
</ParamField>

<ParamField body="aspect_ratio" type="string" default="auto">
  Output aspect ratio. Supported values:

  `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`, or `auto`.

  Ratio formats such as `16x9` are also accepted. With `auto`:

  * Editing or multiple reference images: follows the aspect ratio of the first reference image.
  * Text-to-image: determined by the prompt; falls back to `1:1` if no aspect ratio is determined.
</ParamField>

<ParamField body="size" type="string">
  Compatibility parameter for the aspect ratio. Can replace `aspect_ratio` and accepts the same values. Use only one of these fields.

  Pixel dimensions such as `1024x1024` are not supported and return HTTP 400. Use `resolution` to select the output resolution.
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  Output resolution tier. Supports `768sq`, `1k`, `1.5k`, `2k`, and `4k`, case-insensitively. `768` is equivalent to `768sq`.

  This parameter determines the billing tier. If omitted, generation and billing use `1k`. Unsupported values such as `3k` return HTTP 400.
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  Content safety tolerance, from 0–4. 0 is the strictest.
</ParamField>

<ParamField body="grounding" type="boolean" default="true">
  Whether to allow web or image searches before generation. Set to `false` to disable.

  Must be a boolean, not the strings `"false"` or `"true"`.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Each request generates 1 image; only `1` is supported. Submit separate tasks for multiple images. Values above 1 return HTTP 400.
</ParamField>

## Unsupported parameters

The following parameters return HTTP 400 when provided; they are not silently ignored:

* `width`, `height`
* Pixel dimensions in `size`, such as `1024x1024`
* `seed`, `steps`, `guidance`
* `output_format`, `negative_prompt`, `prompt_upsampling`, `mask_url`

Use `resolution` for higher resolution and `aspect_ratio` for a specific aspect ratio.

## Edit a reference image

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "Make the car in the image red while preserving the original road, background, and lighting",
  "image_urls": ["https://example.com/car.jpg"],
  "aspect_ratio": "auto",
  "resolution": "2k"
}
```

Replace the example URL with a publicly accessible image URL. For multiple references, provide multiple URLs in `image_urls`, up to 10 images in total.

## Multiple reference images

Editing, local editing, and layout use the same endpoint and model on this page, billed by `resolution`. References are numbered in order: `ref_image_0` for the first, `ref_image_1` for the second. You can also use `Image 1` / `Image 2` in the prompt.

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "Turn Image 1 into the style of Image 2.",
  "image_urls": [
    "https://example.com/subject.jpg",
    "https://example.com/style.jpg"
  ],
  "aspect_ratio": "auto"
}
```

## Local editing (bounding box)

Start `prompt` with natural-language editing instructions and refer to elements using `<tags>`, such as `<car_1>`. Append a JSON array within the same string, with one object per box. The bbox is not a separate request parameter.

| Field | Description |
| - | - |
| `id` | Matches the element tag in the prompt, without angle brackets. |
| `from` | Source of the element, such as `ref_image_0`; use `null` for newly drawn or redrawn elements. |
| `src_bbox` | Box in the source image; must also be `null` when `from` is `null`. |
| `tgt_bbox` | Box in the output image; matching `src_bbox` keeps the element in place, while a different box moves it. |
| `desc` | Describes how to change the element or what to preserve. |

All box fields (`src_bbox`, `tgt_bbox`, `bbox`) use `[top, left, bottom, right]`, that is, `[y1, x1, y2, x2]`, on a **0–1000 normalized grid**: top-left is `[0,0]` and bottom-right is `[1000,1000]`. These are not pixel coordinates.

This example turns the boxed car red and describes the background to preserve. The URL and box positions are illustrative; replace them to match your image.

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "In <ref_image_0>, make the car <car_1> red and preserve the background <background_1>. [{\"id\":\"car_1\",\"from\":null,\"src_bbox\":null,\"tgt_bbox\":[250,300,750,800],\"desc\":\"A red car, preserving its original shape and orientation.\"},{\"id\":\"background_1\",\"from\":\"ref_image_0\",\"src_bbox\":[0,0,1000,1000],\"tgt_bbox\":[0,0,1000,1000],\"desc\":\"Preserve the original road, background, and lighting.\"}]",
  "image_urls": [
    "https://example.com/car.jpg"
  ],
  "aspect_ratio": "auto",
  "resolution": "2k"
}
```

### Move an element

Place the following object in the bbox array at the end of the prompt. `from` identifies the source image, `src_bbox` the original position, and `tgt_bbox` the new position. Also use the matching `<knight_1>` tag in the natural-language instruction.

```json theme={null}
{
  "id": "knight_1",
  "from": "ref_image_0",
  "src_bbox": [
    500,
    150,
    850,
    350
  ],
  "tgt_bbox": [
    194,
    55,
    544,
    255
  ],
  "desc": "A miniature grey amigurumi knight figure."
}
```

## Text-to-image layout

Layouts also work without reference images. Each box uses `id`, `bbox`, and `desc`. Set `aspect_ratio` explicitly because the coordinate grid stretches with the aspect ratio.

```json theme={null}
{
  "model": "flux-3-image",
  "aspect_ratio": "1:1",
  "prompt": "Minimalist illustration of a black running silhouette <silhouette_1> against a solid chartreuse background <background_1>. [{\"id\":\"background_1\",\"bbox\":[0,0,1000,1000],\"desc\":\"A neon yellow-green background with subtle paper texture.\"},{\"id\":\"silhouette_1\",\"bbox\":[150,150,850,850],\"desc\":\"A black running silhouette with a stippled texture.\"}]"
}
```

### Usage notes

* The bbox JSON is part of the `prompt` string. When writing request JSON manually, escape its internal double quotes as `\"`. SDKs or JSON serialization methods can handle this automatically.

* Also list regions that should remain unchanged and describe what to preserve in `desc`.

* Element tags in the prompt must match JSON `id` values one-to-one. Reference identifiers such as `<ref_image_0>` point to input images.

* This model has no `mask` parameter and does not support `mask_url`; providing `mask_url` returns HTTP 400. Bbox editing does not use a mask upload parameter.

## Submission response

<ResponseField name="code" type="integer">
  Response status code. `200` indicates success.
</ResponseField>

<ResponseField name="data" type="array">
  Task submission result.

  <Expandable title="Show task fields">
    <ResponseField name="status" type="string">
      `submitted` indicates successful submission, not completed generation.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Task ID used to query task status and results.
    </ResponseField>
  </Expandable>
</ResponseField>

## Query task results

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

Example success response (the image URL is a placeholder):

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.jpg"]
        }
      ]
    }
  }
}
```

Read image links from the `data.result.images[0].url` array. If the task status is `failed`, inspect the returned error message instead of continuing to wait for an image.

## Resolution and billing

Billed per image. The unit price depends only on `resolution`, not the aspect ratio or number of reference images. Reference images incur no extra charge.

| Resolution tier | Approximate output size |
| - | - |
| `768sq` | About 768×768 |
| `1k` (default) | About 1MP |
| `1.5k` | About 2MP |
| `2k` | About 4MP |
| `4k` | About 16MP |

Output sizes are approximate; actual pixel dimensions depend on the returned image. Refer to [model pricing](https://apimart.ai/pricing) for each tier.

Tasks that fail or are blocked by content moderation receive a full refund.

## Common parameter errors

| Request | Result and action |
| - | - |
| `resolution: "3k"` | HTTP 400; use one of the 5 supported tiers |
| `size: "1024x1024"` | HTTP 400; use an aspect ratio and select resolution with `resolution` |
| `n: 2` | HTTP 400; only 1 image is generated per request |
| 11 reference images | HTTP 400; provide at most 10 |
| `grounding: "false"` | HTTP 400; use the boolean `false` |


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