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

# Flux Kontext Image Generation

> Generate and edit images using Flux Kontext model, supporting text-to-image and image editing

> [!NOTE]
>
> **Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.

* Flux Kontext image generation and editing model
* Choose `flux-kontext-pro` (Pro) or `flux-kontext-max` (Max, higher quality) via the model parameter
* Supports text-to-image and image editing modes
* With reference image = image editing; without = text-to-image
* Fixed billing per request
* Async task mode, returns `task_id` for querying results

> [!WARNING]
>
> **Important Change**: For better performance and cost control, we no longer support passing base64 image data directly in `image_urls`. Please use the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) first to upload images and get URLs, then call this endpoint.

## Authorization

**Authorization** `string` *required*

All endpoints require Bearer Token authentication

Get your API Key: Visit the [API Key Management Page](https://toapis.com/console/token) to get your API Key

Add to request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Request Parameters

**model** `string` *required*

Image generation model name

Options:

* `flux-kontext-pro` - Pro version
* `flux-kontext-max` - Max version, higher quality

**prompt** `string` *required*

Text description for image generation

**size** `string`

Image aspect ratio

Default:

* With reference image: `match_input_image` (match input image)
* Without reference image: `16:9`

Supported aspect ratios:

| Value | Description |
| - | - |
| `match_input_image` | Match input image ratio (image editing only) |
| `1:1` | Square |
| `4:3` / `3:4` | Traditional display ratio |
| `16:9` / `9:16` | Widescreen/portrait |
| `3:2` / `2:3` | Standard photo |
| `21:9` / `9:21` | Ultrawide/ultra-narrow |

**image\_urls** `string[]`

Reference image URL array for image editing

**⚠️ URL format only (base64 not supported)**

* Publicly accessible image URL (http\:// or https\://)
* Use the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) to upload local images and get URLs

**Limits:**

* Maximum 1 image
* With image = image editing mode; without = text-to-image mode

**metadata** `object`

Metadata parameters for additional configuration options

**Supported metadata fields**

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

Output image format

Options: `png`, `jpg`

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

Safety filter tolerance

Range: `0` - `6`, higher values = higher tolerance

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

Enable prompt enhancement

* `true`: Auto-optimize/expand prompt
* `false`: Use original prompt (default)

## Response

**id** `string`

Unique task identifier for querying task status

**object** `string`

Object type, fixed as `generation.task`

**model** `string`

Model name used for generation

**status** `string`

Task status

* `queued` - Waiting to be processed
* `in_progress` - Processing
* `completed` - Successfully completed
* `failed` - Failed

**progress** `integer`

Task progress percentage (0-100)

**created\_at** `integer`

Task creation timestamp (Unix timestamp)

**metadata** `object`

Task metadata

## Use Cases

### Case 1: Text-to-Image

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "Cyberpunk city at night, neon lights flickering",
  "size": "16:9",
  "metadata": {
    "response_format": "png",
    "safety_tolerance": 2
  }
}
```

### Case 2: Image Editing

```json theme={null}
{
  "model": "flux-kontext-max",
  "prompt": "Transform this photo into watercolor style",
  "size": "match_input_image",
  "image_urls": ["https://example.com/photo.jpg"],
  "metadata": {
    "response_format": "jpg",
    "prompt_upsampling": true
  }
}
```

### Case 3: High-Quality Text-to-Image (Max Model)

```json theme={null}
{
  "model": "flux-kontext-max",
  "prompt": "A cute orange cat sunbathing on a windowsill, photorealistic style",
  "size": "1:1",
  "metadata": {
    "response_format": "png",
    "safety_tolerance": 3
  }
}
```

> [!NOTE]
>
> **Query Task Results**
>
> Image generation is an async task. After submission, a task ID is returned. Use the [Get Image Task Status](https://docs.toapis.com/docs/en/api-reference/tasks/image-status.md) endpoint to query generation progress and results.

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-pro",
    "prompt": "Cyberpunk city at night, neon lights flickering",
    "size": "16:9",
    "metadata": {
      "response_format": "png"
    }
  }'
```

```bash cURL (Image Editing) theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-max",
    "prompt": "Transform this photo into watercolor style",
    "size": "match_input_image",
    "image_urls": ["https://example.com/photo.jpg"],
    "metadata": {
      "response_format": "jpg"
    }
  }'
```

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

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "flux-kontext-pro",
        "prompt": "Cyberpunk city at night, neon lights flickering",
        "size": "16:9",
        "metadata": {
            "response_format": "png"
        }
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
print(f"Status: {task['status']}")
```

```python Python (Image Editing) theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "flux-kontext-max",
        "prompt": "Transform this photo into watercolor style",
        "size": "match_input_image",
        "image_urls": ["https://example.com/photo.jpg"],
        "metadata": {
            "response_format": "jpg"
        }
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
print(f"Status: {task['status']}")
```

```javascript JavaScript theme={null}
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'flux-kontext-pro',
    prompt: 'Cyberpunk city at night, neon lights flickering',
    size: '16:9',
    metadata: {
      response_format: 'png'
    }
  })
});

const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);
```

```javascript JavaScript (Image Editing) theme={null}
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'flux-kontext-max',
    prompt: 'Transform this photo into watercolor style',
    size: 'match_input_image',
    image_urls: ['https://example.com/photo.jpg'],
    metadata: {
      response_format: 'jpg'
    }
  })
});

const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);
```

```json 200 theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "flux-kontext-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}
```


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