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

# FLUX 3 Image API: Text-to-Image & Image Editing

> Generate one image from text or edit up to 10 reference images with 1K, 2K, or 4K output

## Overview

FLUX 3 Image generates images from text and edits or combines reference images. Each task returns one image. Choose a resolution and output format, submit a task, then poll for the result or receive a webhook callback.

| Capability | Value |
| - | - |
| Model ID | `flux-3-image` |
| Modes | `text-to-image`, `image-to-image` |
| Reference images | 1-10 URLs for image-to-image |
| Reference dimensions | Each image must be at least 256 pixels wide and high, and at most 4,000,000 pixels in total |
| Resolution tiers | `1k`, `2k`, `4k` |
| Output formats | `jpeg`, `png` |
| Output | Exactly 1 image URL in the parsed `resultJson.resultUrls` array |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/generateTask/flux-3-image` | Submit an image generation or editing task |
| `GET` | `/statusTask/flux-3-image?taskId={taskId}` | Query task status and retrieve the result |

Include your APIXO API key in every request:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require `Content-Type: application/json`.

## Copy-paste async quickstart

Submit a text-to-image task:

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/flux-3-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "A white ceramic coffee cup on a wooden table, soft natural daylight",
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "output_format": "png"
    }
  }'
```

Successful submission:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

Save `data.taskId` and query the status endpoint. A successful submission means the task was accepted; check `data.state` to determine the final outcome.

## Poll for result

```bash theme={null}
curl "https://api.apixo.ai/api/v1/statusTask/flux-3-image?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

While the task is running, `data.state` is `processing`. Continue polling until it becomes `success` or `failed`.

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://example.com/result.png\"]}",
    "createTime": 1791479211790,
    "completeTime": 1791479234710,
    "costTime": 22920
  }
}
```

`resultJson` is a JSON **string**. Parse it before reading the image URL:

```javascript theme={null}
const imageUrl = JSON.parse(response.data.resultJson).resultUrls[0];
```

Failure response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "UnmappedUpstreamError",
    "failMsg": "The provider rejected the request. Please check your inputs and try again.",
    "createTime": 1791478394190,
    "completeTime": 1791478396181,
    "costTime": 1991
  }
}
```

A status response with `code: 200` can still describe a failed task. Use `data.state`, `failCode`, and `failMsg` to handle task failures.

## Image-to-image request

Provide 1-10 reference images in `image_urls`. Their order is preserved, so refer to them as image 1, image 2, and so on in the prompt.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/flux-3-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "image-to-image",
      "prompt": "Place the product from image 1 into the scene in image 2",
      "image_urls": [
        "https://example.com/product.png",
        "https://example.com/scene.png"
      ],
      "resolution": "1k",
      "output_format": "png"
    }
  }'
```

Replace the example URLs with public, directly fetchable image URLs. Each reference image must be at least 256 pixels on both sides and contain no more than 4,000,000 pixels (`width * height`).

When `aspect_ratio` is omitted or blank in image-to-image mode, the output follows the first reference image's aspect ratio.

## Parameters

<ParamField body="request_type" type="string" default="async">
  Result delivery mode. Supported values: `async`, `callback`. Use `async` for status polling or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Provide a public HTTPS endpoint that accepts POST requests. See [Webhooks](/docs/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  FLUX 3 Image input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" required>
      Generation mode. Supported values: `text-to-image`, `image-to-image`. This field is required; there is no default mode.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Non-empty text describing the desired image or edit. Whitespace-only prompts are invalid. For multiple reference images, describe the role of image 1, image 2, and so on. No fixed maximum character count is specified.
    </ParamField>

    <ParamField body="image_urls" type="string[]">
      Required for `image-to-image`. Provide 1-10 public, directly fetchable, non-empty image URLs in reference order. Each image must be at least 256 pixels wide and high, and contain at most 4,000,000 pixels. Use this field only for image-to-image requests.
    </ParamField>

    <ParamField body="aspect_ratio" type="string">
      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`. When omitted or blank, text-to-image defaults to `1:1`; image-to-image follows the first reference image's ratio.
    </ParamField>

    <ParamField body="resolution" type="string" default="1k">
      Output resolution tier. Supported values: `1k`, `2k`, `4k`. Values are case-insensitive. The selected tier determines the price per image.
    </ParamField>

    <ParamField body="output_format" type="string" default="jpeg">
      Output image format. Supported values: `jpeg`, `png`. Values are case-insensitive.
    </ParamField>

    <ParamField body="enable_prompt_expansion" type="boolean" default="false">
      Expand the prompt while preserving its intent. Must be a JSON boolean when provided.
    </ParamField>
  </Expandable>
</ParamField>

## Status response fields

All fields below are inside `data`.

| Field | Type | Description |
| - | - | - |
| `taskId` | string | Task ID returned by the creation request |
| `state` | string | `processing`, `success`, or `failed` |
| `resultJson` | string | Present on success; parse it to read `resultUrls`, an array with exactly one image URL |
| `createTime` | integer | Creation timestamp in Unix milliseconds |
| `completeTime` | integer | Completion timestamp in Unix milliseconds, returned for terminal tasks |
| `costTime` | integer | Task duration in milliseconds, returned for terminal tasks |
| `failCode` | string | Failure code when `state` is `failed` |
| `failMsg` | string | Failure explanation when `state` is `failed` |

## Webhook callback mode

Set `request_type` to `callback` and provide `callback_url`:

```json theme={null}
{
  "request_type": "callback",
  "callback_url": "https://your-server.com/webhooks/apixo",
  "input": {
    "mode": "text-to-image",
    "prompt": "A minimal coffee shop poster with the title Morning Coffee",
    "resolution": "1k"
  }
}
```

See [Webhooks](/docs/api-reference/webhooks) for receiver setup and delivery handling.

## Billing

Both modes generate one image per task and use the same resolution-based prices. The number of reference images does not add a separate charge.

| Resolution | APIXO price |
| - | - |
| `1k` | `$0.05 / image` |
| `2k` | `$0.12 / image` |
| `4k` | `$0.65 / image` |

See [Pricing](https://apixo.ai/pricing) for current prices.

## Latency and polling

Generation time varies with resolution, prompt complexity, reference images, and queue load. A 4K task can take several minutes.

| Stage | Guidance |
| - | - |
| First poll | Wait 10-20 seconds after task creation |
| Poll interval | Poll every 3-5 seconds while the task is processing |
| Completion | Stop polling at success or failed; parse resultJson only on success |
| Production delivery | Use callback mode for high-concurrency workloads and long-running tasks |

If a request is rate-limited, reduce concurrency and retry with backoff. Keep the original `taskId` when querying an accepted task.

## Errors and troubleshooting

* Check that `mode` and a non-empty `prompt` are present.
* For image-to-image, provide 1-10 valid reference URLs and respect the per-image dimension and pixel limits.
* Use one of the documented aspect ratios, resolution tiers, and output formats.
* Inspect `data.state` even when the status endpoint returns `code: 200`.
* When a task fails, use `failCode` and `failMsg` to decide whether to change the input before submitting another task.

See [Error Codes](/docs/api-reference/errors) for authentication, balance, rate-limit, and task failure handling.

## Related links

* [Image Models](/docs/models/image)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Flux 2](/docs/models/image/flux-2)
* [Flux Kontext](/docs/models/image/flux-kontext)
* [Pricing](https://apixo.ai/pricing)


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