> ## 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.2 Image Generation

> Submit asynchronous FLUX.2 text-to-image or reference-image generation tasks. The API returns a task ID; poll the task endpoint for the generated image.

<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-2-pro",
      "prompt": "A blue cat sitting on the grass",
      "resolution": "2MP",
      "size": "16:9",
      "output_format": "jpeg"
    }'
  ```

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "flux-2-pro",
      "prompt": "A blue cat sitting on the grass",
      "resolution": "2MP",
      "size": "16:9",
      "output_format": "jpeg"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "flux-2-pro",
    prompt: "A blue cat sitting on the grass",
    resolution: "2MP",
    size: "16:9",
    output_format: "jpeg"
  };

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  });

  console.log(await response.json());
  ```
</RequestExample>

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

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed, please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient balance, please top up",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## Supported Models

| Model         | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| `flux-2-flex` | Fine-grained generation with adjustable sampling steps and guidance. |
| `flux-2-pro`  | Balanced quality and speed for general-purpose production workflows. |
| `flux-2-max`  | Highest-quality FLUX.2 model for maximum detail.                     |

All three models support text-to-image generation and reference-image generation.

## Authorizations

<ParamField header="Authorization" type="string" required>
  All endpoints require Bearer Token authentication.

  Get an API key from [API Key Management](https://apimart.ai/keys), then add it to the request header:

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Model name:

  * `flux-2-flex`
  * `flux-2-pro`
  * `flux-2-max`
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description of the image to generate or the edit to apply to the reference images.
</ParamField>

<ParamField body="resolution" type="string" default="2MP">
  Output resolution preset. Supported values:

  * `1MP`
  * `2MP` (default)
  * `3MP`
  * `4MP`

  Here, `1MP` equals 1,048,576 pixels.

  Legacy aliases remain accepted: `512` / `512P` / `1M` map to `1MP`, `1K` / `1024` map to `2MP`, `2K` / `2048` map to `3MP`, and `4K` maps to `4MP`. Any other value causes the task to fail.

  The preset determines the output dimensions when `size` is an aspect ratio.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Output aspect ratio or pixel dimensions.

  `size` also supports `auto`: when `image_urls` is provided, the output follows the reference image aspect ratio while keeping the current `resolution` tier; without a reference image, it uses the default `1:1`.

  Supported size options:

  * `1:1` (default)
  * `4:3`
  * `3:4`
  * `16:9`
  * `9:16`
  * `3:2`
  * `2:3`
  * `21:9`
  * `9:21`
  * `auto` - Follow the reference image aspect ratio

  You may also provide a pixel string such as `1024x1536`. Exact pixel dimensions are subject to the same pixel limits as `width` and `height` and take priority over `resolution` and an aspect ratio.
</ParamField>

<ParamField body="width" type="integer">
  Exact output width in pixels. It must be provided together with `height`, and each dimension must be at least 64 pixels. Supplying only one dimension causes the task to fail.

  A complete `width` and `height` pair has the highest priority and overrides `resolution` and `size`.
</ParamField>

<ParamField body="height" type="integer">
  Exact output height in pixels. It must be provided together with `width`, and each dimension must be at least 64 pixels. Supplying only one dimension causes the task to fail.

  The output must not exceed 4 MP (`width × height ≤ 4,194,304`), and the output plus all reference images must not exceed 9 MP in total.
</ParamField>

<ParamField body="image_urls" type="array">
  Reference images for image-to-image generation. Publicly accessible image URLs and Base64 input are supported.

  * Maximum: 8 images
  * The output plus all reference images must not exceed 9 MP in total
</ParamField>

<ParamField body="output_format" type="string" default="jpeg">
  Output image encoding. Supported values: `jpeg`, `png`, and `webp`.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Number of images generated per task. The only supported value is `1`; submit multiple tasks concurrently if you need multiple images.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed. Reuse the same seed and parameters for reproducible output; omit it to use a random seed.
</ParamField>

<ParamField body="prompt_upsampling" type="boolean" default="false">
  Whether to enhance and rewrite the prompt before generation. The default is `false`. Pass `false` explicitly to disable prompt rewriting.
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  Safety tolerance from `0` to `5`. Higher values are more permissive.
</ParamField>

<ParamField body="steps" type="integer" default="50">
  Sampling steps from `1` to `50`. Higher values can improve detail but take longer.

  This parameter is supported only by `flux-2-flex`. Do not send it with `flux-2-pro` or `flux-2-max`.
</ParamField>

<ParamField body="guidance" type="number" default="5.0">
  Prompt guidance from `1.5` to `10`. Higher values follow the prompt more closely.

  This parameter is supported only by `flux-2-flex`. Do not send it with `flux-2-pro` or `flux-2-max`.
</ParamField>

## Resolution Reference Table

| Aspect ratio |     `1MP` | `2MP` (default) |     `3MP` |     `4MP` |
| ------------ | --------: | --------------: | --------: | --------: |
| `1:1`        | 1024×1024 |       1440×1440 | 1536×1536 | 2048×2048 |
| `4:3`        |  1152×864 |       1664×1248 | 1824×1360 | 2336×1760 |
| `3:4`        |  864×1152 |       1248×1664 | 1360×1824 | 1760×2336 |
| `16:9`       |  1344×752 |       1920×1072 | 2048×1152 | 2720×1536 |
| `9:16`       |  752×1344 |       1072×1920 | 1152×2048 | 1536×2720 |
| `3:2`        |  1248×832 |       1728×1152 | 1872×1248 | 2496×1664 |
| `2:3`        |  832×1248 |       1152×1728 | 1248×1872 | 1664×2496 |
| `21:9`       |  1504×640 |        2176×928 |  2304×992 | 3072×1312 |
| `9:21`       |  640×1504 |        928×2176 |  992×2304 | 1312×3072 |

Dimension priority is: paired `width` + `height` → a pixel-string `size` → `resolution` + aspect-ratio `size` → the default `2MP` + `1:1`.

## Usage Examples

### Text-to-image

```json theme={null}
{
  "model": "flux-2-pro",
  "prompt": "A cinematic city at night with neon reflections on wet streets",
  "resolution": "1MP",
  "size": "16:9"
}
```

### Reference-image generation

```json theme={null}
{
  "model": "flux-2-pro",
  "prompt": "Place the person from the first image in the scene from the second image and match the lighting",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/scene.jpg"
  ],
  "resolution": "2MP",
  "output_format": "webp"
}
```

### Exact output dimensions

```json theme={null}
{
  "model": "flux-2-max",
  "prompt": "A highly detailed botanical illustration",
  "width": 1024,
  "height": 1536
}
```

### FLUX.2 Flex controls

```json theme={null}
{
  "model": "flux-2-flex",
  "prompt": "A minimalist poster with the headline SUMMER SALE and the subheading 50% OFF",
  "resolution": "3MP",
  "size": "3:4",
  "steps": 50,
  "guidance": 6.5
}
```

## Response

<ResponseField name="code" type="integer">
  Response status code.
</ResponseField>

<ResponseField name="data" type="array">
  Submission result array.

  <Expandable title="Properties">
    <ResponseField name="status" type="string">
      Submission status. A successfully accepted task returns `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Unique task identifier. Use it to poll the task endpoint.
    </ResponseField>
  </Expandable>
</ResponseField>

## Retrieve the Result

Poll `GET /v1/tasks/{task_id}` until the task reaches `completed` or `failed`. See the [Task Status API](/en/api-reference/tasks/status) for the complete response schema.

Task statuses:

| Status                  | Meaning                                                                   |
| ----------------------- | ------------------------------------------------------------------------- |
| `submitted` / `pending` | Accepted or queued; continue polling.                                     |
| `processing`            | Image generation is in progress; continue polling.                        |
| `completed`             | Generation succeeded; the image is available in `result.images`.          |
| `failed`                | Generation failed; read `data.error.message`. The task is fully refunded. |

A completed task includes one generated image:

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://upload.apimart.ai/f/image/xxxxxxxx-flux-2.jpeg"],
          "expires_at": 1785220083
        }
      ]
    }
  }
}
```

The image URL is `data.result.images[0].url[0]`. Its expiration is defined by the Unix timestamp in `data.result.images[0].expires_at`; download the image before that time.

### Invalid parameters and failed tasks

Invalid model parameters do not produce a synchronous 4xx response. The submission still returns HTTP 200 with a `task_id`; keep polling until the task becomes `failed`, then read the specific reason from `data.error.message`. Failed tasks are fully refunded.

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "`steps` must be between 1 and 50 (got 0)"
    }
  }
}
```

`error.code` is always `task_failed`; the specific reason is in `error.message`.

## Notes

1. Tasks are processed asynchronously. The submission response returns a `task_id` for polling.
2. `n` defaults to `1`, which is the only supported value.
3. Reference images may use publicly accessible image URLs or Base64 input.
4. Up to 8 reference images are supported, subject to the 9 MP combined input-and-output limit.
5. Exact output dimensions can be set with a pixel-string `size`, or with paired `width` and `height`. When used, both dimensions must be at least 64 pixels; output is limited to 4 MP.
6. Result URL expiration is determined by the `expires_at` value returned in the task response.
7. Invalid model parameters are returned asynchronously: poll until `failed` and read `data.error.message`.