> ## 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 Kontext

> Black Forest Labs context-aware image generation API for text-to-image and image-to-image workflows

## Overview

Flux Kontext is a Black Forest Labs image model for prompt-based image generation and reference-guided image editing. Use this page when you are ready to call the API after trying the model in the APIXO playground.

| Capability       | Value                                       |
| ---------------- | ------------------------------------------- |
| Model ID         | `flux-kontext`                              |
| Modes            | `pro`, `max`                                |
| Workflows        | `text-to-image`, `image-to-image`           |
| Prompt length    | 1-10000 characters                          |
| Reference images | Optional, 1 image URL                       |
| Aspect ratios    | `1:1`, `4:3`, `3:4`, `9:16`, `16:9`, `21:9` |
| Output formats   | `jpeg`, `png`                               |

## Endpoint and authentication

Base URL:

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

| Method | Endpoint                                   | Purpose                               |
| ------ | ------------------------------------------ | ------------------------------------- |
| `POST` | `/generateTask/flux-kontext`               | Submit a generation task              |
| `GET`  | `/statusTask/flux-kontext?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

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

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

This minimal request submits a text-to-image task and returns a `taskId`.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/flux-kontext" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "pro",
      "prompt": "a castle on a quiet hill at sunset",
      "aspect_ratio": "16:9",
      "output_format": "jpeg"
    }
  }'
```

Successful response:

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

Save the `taskId`; you need it to poll for the final result.

## Poll for result

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

Processing response:

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

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/xxx.png\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965652317,
    "costTime": 41388
  }
}
```

Failed response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "SensitiveContent",
    "failMsg": "Content violates provider policy, please adjust the prompt",
    "createTime": 1767965610929,
    "completeTime": 1767965620132,
    "costTime": 9203
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```

## Request body

### Text-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "pro",
    "prompt": "a quiet greenhouse filled with bioluminescent plants",
    "aspect_ratio": "16:9",
    "output_format": "jpeg"
  }
}
```

### Image-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "max",
    "prompt": "turn this room into a warm mid-century interior",
    "aspect_ratio": "4:3",
    "image_urls": [
      "https://example.com/source.jpg"
    ],
    "output_format": "png",
    "promptUpsampling": false,
    "safetyTolerance": 2
  }
}
```

## Parameters

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

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  Flux Kontext input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" required>
      Model variant used for routing and billing. Supported values: `pro`, `max`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Text prompt describing the desired image or edit. Supports 1-10000 characters.
    </ParamField>

    <ParamField body="aspect_ratio" type="string" required>
      Output aspect ratio. Supported values: `1:1`, `4:3`, `3:4`, `9:16`, `16:9`, `21:9`.
    </ParamField>

    <ParamField body="image_urls" type="string[]">
      Reference image URLs for image-to-image generation. Optional. If provided, it must contain exactly 1 public, reachable image URL.
    </ParamField>

    <ParamField body="image_url" type="string">
      Legacy single-image field. Optional. If both `image_url` and `image_urls` are provided, `image_url` takes precedence.
    </ParamField>

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

    <ParamField body="promptUpsampling" type="boolean" default="false">
      Whether to enable provider-side prompt expansion before generation.
    </ParamField>

    <ParamField body="safetyTolerance" type="integer" default="2">
      Safety tolerance level. Supported values: `0`, `1`, `2`.
    </ParamField>

    <ParamField body="watermark" type="string">
      Optional custom watermark text. Defaults to an empty string.
    </ParamField>

    <ParamField body="enableTranslation" type="boolean" default="true">
      Whether to enable provider-side prompt translation.
    </ParamField>

    <ParamField body="uploadCn" type="boolean" default="false">
      Advanced provider upload routing flag. Leave it at the default unless APIXO support asks you to change it.
    </ParamField>
  </Expandable>
</ParamField>

## Response format

### Submit task response

`POST /generateTask/flux-kontext` returns a task ID when the task is accepted:

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `pending`, `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing the generated image URLs. Present when `state` is `success`.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds. Present after completion when available.
</ResponseField>

## Webhook callback mode

Use callback mode when your backend should receive the final result automatically instead of polling.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/flux-kontext" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "pro",
      "prompt": "a clean product photo of a ceramic lamp on soft stone",
      "aspect_ratio": "1:1",
      "output_format": "jpeg"
    }
  }'
```

See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior.

## Billing

Flux Kontext is billed per generated image. The selected `mode` determines the unit price.

| Mode  | APIXO price     | Market reference |
| ----- | --------------- | ---------------- |
| `pro` | `$0.03 / image` | `$0.04 / image`  |
| `max` | `$0.06 / image` | `$0.08 / image`  |

For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).

## Latency and polling

Actual latency may vary by prompt complexity, reference image accessibility, provider route, and current queue load.

| Mode  | Typical generation time | Recommended first poll  | Poll interval |
| ----- | ----------------------- | ----------------------- | ------------- |
| `pro` | Around 30s              | 20s after task creation | 3s-5s         |
| `max` | Around 30s or longer    | 20s after task creation | 3s-5s         |

<Tip>
  For high-concurrency production workloads, use callback mode to avoid frequent polling.
</Tip>

Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system).

## Errors and troubleshooting

### HTTP errors

| Code  | Meaning                                                                              | What to do                                       |
| ----- | ------------------------------------------------------------------------------------ | ------------------------------------------------ |
| `400` | Invalid request body, missing parameter, unsupported value, or unreachable image URL | Fix the request before retrying                  |
| `401` | Missing or invalid API key                                                           | Check the `Authorization` header                 |
| `402` | Insufficient balance or quota                                                        | Add balance or switch account/key                |
| `403` | Key or route cannot access the model                                                 | Check permissions and route strategy             |
| `429` | Rate limit or concurrency limit reached                                              | Retry with exponential backoff                   |
| `500` | Server error or unmapped provider failure                                            | Retry with backoff                               |
| `502` | Upstream provider error                                                              | Retry with backoff                               |
| `504` | Upstream timeout                                                                     | Retry or use callback mode for long-running jobs |

### Parameter validation

| Field                   | Requirement                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| `input.mode`            | Required. Must be `pro` or `max`.                                                        |
| `input.prompt`          | Required string. Must not be empty and cannot exceed 10000 characters.                   |
| `input.aspect_ratio`    | Required. Must be `1:1`, `4:3`, `3:4`, `9:16`, `16:9`, or `21:9`.                        |
| `input.image_urls`      | Optional array. If present, it cannot be empty and cannot contain more than 1 image URL. |
| `input.output_format`   | Optional. Must be `jpeg` or `png`.                                                       |
| `input.safetyTolerance` | Optional integer. Must be `0`, `1`, or `2`.                                              |

### Task failure codes

| Fail code          | Meaning                                                                    | What to do                                              |
| ------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------- |
| `ImageNotAccess`   | A reference image URL could not be fetched or was not a public HTTP(S) URL | Use a public, direct image URL                          |
| `PromptInvalid`    | Prompt was rejected or malformed                                           | Change the prompt and retry                             |
| `SensitiveContent` | Prompt or reference image failed provider safety checks                    | Change the prompt or input image                        |
| `RateLimited`      | Provider-side rate limit reached                                           | Retry with exponential backoff                          |
| `Timeout`          | Provider-side timeout                                                      | Retry, reduce input complexity, or use callback mode    |
| `Unknown error`    | Provider returned an unmapped failure                                      | Retry with backoff or contact support with the `taskId` |

See [Error Codes](/api-reference/errors) for the full error reference.

## Related links

* [Generation API Overview](/models)
* [Generate Task](/api-reference/generate-task)
* [Status Task](/api-reference/status-task)
* [Webhooks](/api-reference/webhooks)
* [Error Codes](/api-reference/errors)
* [Parameter Specification](/api-reference/parameters)
* [Routing Strategies](/concepts/routing-strategies)
* [Pricing](https://apixo.ai/pricing)