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

# FLUX Kontext Image Generation and Editing

> Submit asynchronous FLUX Kontext image generation or image editing tasks. The API returns a task ID; poll the task endpoint for the generated image.

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-pro",
    "prompt": "Change the hair color to blue",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "1:1",
    "output_format": "png"
  }'
```

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

url = "https://gccai.heqingsong.uk/v1/images/generations"

payload = {
    "model": "flux-kontext-pro",
    "prompt": "Change the hair color to blue",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "1:1",
    "output_format": "png"
}

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://gccai.heqingsong.uk/v1/images/generations";

const payload = {
  model: "flux-kontext-pro",
  prompt: "Change the hair color to blue",
  image_urls: ["https://example.com/portrait.jpg"],
  size: "1:1",
  output_format: "png"
};

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

console.log(await response.json());
```

```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"
  }
}
```

## Supported Models

| Model | Description |
| - | - |
| `flux-kontext-pro` | Context-aware image generation and editing for general-purpose workflows. |
| `flux-kontext-max` | Higher-quality context-aware image generation and editing. |

Both models support text-to-image generation without reference images and image editing with reference images.

## Authorizations

**Authorization** `string` *required*

All endpoints require Bearer Token authentication.

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

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

## Body

**model** `string` *required*

Model name:

* `flux-kontext-pro`
* `flux-kontext-max`

**nsfw\_check** `boolean` (default: false)

Whether to run content moderation before submitting the image task.

* `true`: use `omni-moderation-latest` to review prompts and input images
* `false` or omitted: do not send a moderation request, adding no moderation cost or latency (default)

**prompt** `string` *required*

Text description of the image to generate or the edit to apply to the reference images.

**image\_urls** `array`

Reference images for image editing. Publicly accessible image URLs and Base64 input are supported.

* Maximum: 4 images
* The output plus all reference images must not exceed 9 MP in total

If a reference URL cannot be accessed publicly, the task may return only `temporarily unavailable dependency`. When this happens, first check hotlink protection, access permissions, and expired signatures.

**size** `string` (default: 1:1)

Output aspect ratio. A pixel string such as `1024x1536` is also accepted, but Kontext maps it to the closest supported ratio rather than producing those exact pixel dimensions. Supported aspect ratios and automatic mode:

* `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

When `size` is set to `auto`, the output follows the reference image's aspect ratio if `image_urls` is provided. Without a reference image, it uses the default `1:1` ratio.

Kontext does not support `width` or `height`; supplying either field causes the task to fail. Use `size` to control the aspect ratio. `resolution` has no effect for Kontext, whose output remains approximately 1 MP.

**output\_format** `string` (default: png)

Output image encoding. Supported values: `png`, `jpeg`, and `webp`.

**response\_format** `string`

OpenAI-compatible response-shape field. It accepts only `url` or `b64_json` and does not change the image encoding. When both fields are supplied, `output_format` takes priority.

**n** `integer` (default: 1)

Number of images generated per task. The only supported value is `1`; submit multiple tasks concurrently if you need multiple images.

**seed** `integer`

Random seed. Reuse the same seed and parameters for reproducible output; omit it to use a random seed.

**prompt\_upsampling** `boolean` (default: false)

Whether to enhance and rewrite the prompt before generation.

Set this parameter explicitly to `false` to disable prompt rewriting.

**safety\_tolerance** `integer` (default: 2)

Safety tolerance from `0` to `6`. Higher values are more permissive.

## Supported Aspect Ratios

| Aspect ratio | Orientation |
| - | - |
| `1:1` | Square (default) |
| `4:3` | Landscape |
| `3:4` | Portrait |
| `16:9` | Widescreen landscape |
| `9:16` | Vertical portrait |
| `3:2` | Classic landscape |
| `2:3` | Classic portrait |
| `21:9` | Ultra-wide landscape |
| `9:21` | Ultra-tall portrait |

### Actual Output Dimensions

| Ratio | Actual output dimensions |
| - | - |
| `1:1` | 1024×1024 |
| `4:3` | 1184×880 |
| `3:4` | 880×1184 |
| `16:9` | 1392×752 |
| `9:16` | 752×1392 |
| `3:2` | 1248×832 |
| `2:3` | 832×1248 |
| `21:9` | 1568×672 |
| `9:21` | 672×1568 |

## Usage Examples

### Text-to-image generation

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "A cozy reading nook with warm lamplight",
  "size": "4:3"
}
```

### Image editing

```json theme={null}
{
  "model": "flux-kontext-max",
  "prompt": "Replace the background with a beach while preserving the person",
  "image_urls": ["https://example.com/portrait.jpg"],
  "size": "16:9",
  "output_format": "webp"
}
```

### Multiple reference images

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "Place the product from the first image into the room from the second image",
  "image_urls": [
    "https://example.com/product.jpg",
    "https://example.com/room.jpg"
  ],
  "size": "4:3"
}
```

## Response

**code** `integer`

Response status code.

**data** `array`

Submission result array.

**Properties**

**status** `string`

Submission status. A successfully accepted task returns `submitted`.

**task\_id** `string`

Unique task identifier. Use it to poll the task endpoint.

## Retrieve the Result

Poll `GET /v1/tasks/{task_id}` until the task reaches `completed` or `failed`. See the [Task Status API](https://gccai.heqingsong.uk/en/api-reference/tasks/status.md) 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.gccai.ai/f/image/xxxxxxxx-flux-kontext.png"],
          "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": "width/height are not supported by flux-kontext-pro"
    }
  }
}
```

`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 4 reference images are supported, subject to the 9 MP combined input-and-output limit.
5. Set `prompt_upsampling: false` explicitly to disable prompt rewriting.
6. Result URL expiration is determined by the `expires_at` value returned in the task response.
7. `width` and `height` cause the task to fail; `resolution` does not change the approximately 1 MP output; a pixel-string `size` maps to the closest supported ratio.
8. Invalid model parameters are returned asynchronously: poll until `failed` and read `data.error.message`.


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