> ## 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 3 Image Klein Generation

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

> [!NOTE]
>
> This endpoint is asynchronous. A successful submission returns a `task_id`. Use [task queries](https://gccai.heqingsong.uk/en/api-reference/tasks/status.md) 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.

```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-3-image-klein",
    "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://gccai.heqingsong.uk/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "flux-3-image-klein",
        "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://gccai.heqingsong.uk/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "flux-3-image-klein",
    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());
```

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

## Request headers

**Authorization** `string` *required*

Bearer authentication in the format `Bearer <token>`, where `<token>` is your GccAi API Key.

## Request parameters

**model** `string` *required*

Must be `flux-3-image-klein`.

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

**image\_urls** `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.

**aspect\_ratio** `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.

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

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

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

Content safety tolerance, from 0–4. 0 is the strictest.

**seed** `integer`

Random seed, from 0 to 4294967295.

**steps** `integer` (default: 16)

Generation steps, from 1 to 16; default: 16. Fewer steps can speed up generation but may reduce image quality. Steps do not affect pricing.

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

Image file format: `jpeg` (default) or `png`; `jpg` is equivalent to `jpeg`. `webp` is not supported and returns HTTP 400.

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

Each request generates 1 image; only `1` is supported. Submit separate tasks for multiple images. Values above 1 return HTTP 400.

## Unsupported parameters

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

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

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

## Specify seed, steps, and image format

```json theme={null}
{
  "model": "flux-3-image-klein",
  "prompt": "A red fox in fresh snow, golden hour, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2k",
  "seed": 42,
  "steps": 16,
  "output_format": "png"
}
```

## Edit a reference image

```json theme={null}
{
  "model": "flux-3-image-klein",
  "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-klein",
  "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-klein",
  "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-klein",
  "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

**code** `integer`

Response status code. `200` indicates success.

**data** `array`

Task submission result.

**Show task fields**

**status** `string`

`submitted` indicates successful submission, not completed generation.

**task\_id** `string`

Task ID used to query task status and results.

## Query task results

```bash theme={null}
curl --request GET \
  --url https://gccai.heqingsong.uk/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.
Pricing is unaffected by `steps`, `seed`, or `output_format`. Text-to-image and editing have the same price.

| 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://gccai.heqingsong.uk/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` | HTTP 400; this model does not support web or image search parameters |
| `output_format: "webp"` | HTTP 400; use `jpeg` or `png` (`jpg` is equivalent to `jpeg`) |


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