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

# Generación y edición de imágenes con FLUX Kontext

> Envía tareas asíncronas de FLUX Kontext para generar o editar imágenes. La API devuelve un ID de tarea; consulta periódicamente el endpoint de tareas para obtener la imagen generada.

```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 hair color to blue",
    "image_urls": ["https://upload.gccai.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
    "size": "16:9"
  }'
```

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

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

payload = {
    "model": "flux-kontext-pro",
    "prompt": "Change hair color to blue",
    "image_urls": ["https://upload.gccai.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
    "size": "16:9"
}

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 hair color to blue",
  image_urls: ["https://upload.gccai.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
  size: "16:9"
};

const headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

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

## Modelos compatibles

| Modelo | Descripción |
| - | - |
| `flux-kontext-pro` | Generación y edición de imágenes según su contexto para flujos de uso general. |
| `flux-kontext-max` | Generación y edición de imágenes según su contexto con mayor calidad. |

Ambos modelos permiten generar imágenes a partir de texto sin imágenes de referencia y editar imágenes mediante imágenes de referencia.

## Autorización

**Authorization** `string` *required*

Todos los endpoints requieren autenticación mediante Bearer Token.

Obtén una clave en [Gestión de claves de API](https://gccai.heqingsong.uk/keys) y añádela al encabezado de la solicitud:

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

## Cuerpo de la solicitud

**model** `string` *required*

Nombre del modelo:

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

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

Indica si se debe moderar el contenido antes de enviar la tarea de imagen.

* `true`: revisar los prompts y las imágenes de entrada con `omni-moderation-latest`
* `false` u omitido: no enviar una solicitud de moderación, sin coste ni latencia de moderación adicionales (predeterminado)

**prompt** `string` *required*

Descripción textual de la imagen que se generará o de la edición que se aplicará a las imágenes de referencia.

**image\_urls** `array`

Imágenes de referencia para editar imágenes. Proporciónalas mediante URL accesibles públicamente o en Base64.

* Máximo: 4 imágenes
* La suma de la imagen de salida y todas las imágenes de referencia no debe superar los 9 MP

Si no se puede acceder a una URL de referencia, la tarea puede devolver `temporarily unavailable dependency`. Comprueba primero que la URL sea pública, no haya caducado y no bloquee el acceso externo.

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

Relación de aspecto de la imagen de salida. Relaciones de aspecto y modo automático compatibles:

* `1:1` (valor predeterminado)
* `4:3`
* `3:4`
* `16:9`
* `9:16`
* `3:2`
* `2:3`
* `21:9`
* `9:21`
* `auto` - Seguir la relación de aspecto de la imagen de referencia

Cuando `size` se establece en `auto`, la salida sigue la relación de aspecto de la imagen de referencia si se proporciona `image_urls`. Si no hay una imagen de referencia, se usa la relación predeterminada `1:1`.

También se puede proporcionar una cadena de píxeles, como `1024x1536`. Kontext la asigna a la relación compatible más cercana y no garantiza esas dimensiones exactas.

El parámetro `resolution` no modifica la salida de Kontext, que se mantiene en torno a 1 MP. No envíes `width` ni `height`: Kontext no admite estos parámetros y la tarea fallará.

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

Formato de la imagen resultante: `png`, `jpeg` o `webp`. El valor predeterminado es `png`.

**response\_format** `string`

Parámetro de compatibilidad para la forma de la respuesta. Valores permitidos: `url` y `b64_json`. No cambia el formato de la imagen; si también se proporciona `output_format`, tiene prioridad `output_format`.

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

Número de imágenes que se generan. Solo se admite el valor `1`.

**seed** `integer`

Semilla aleatoria. Reutiliza la misma semilla y los mismos parámetros para obtener resultados reproducibles; omítela para usar una semilla aleatoria.

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

Indica si el prompt debe mejorarse y reescribirse antes de generar la imagen.

Define este parámetro explícitamente como `false` para desactivar la reescritura del prompt.

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

Tolerancia de seguridad entre `0` y `6`. Los valores más altos son más permisivos.

## Relaciones de aspecto compatibles

| Relación de aspecto | Orientación |
| - | - |
| `1:1` | Cuadrada (valor predeterminado) |
| `4:3` | Horizontal |
| `3:4` | Vertical |
| `16:9` | Horizontal panorámica |
| `9:16` | Vertical |
| `3:2` | Horizontal clásica |
| `2:3` | Vertical clásica |
| `21:9` | Horizontal ultraancha |
| `9:21` | Vertical ultraalta |

### Dimensiones reales de salida

| Relación | Dimensiones reales |
| - | - |
| `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 |

## Ejemplos de uso

### Generación a partir de texto

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

### Edición de imágenes

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

### Varias imágenes de referencia

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

## Respuesta

**code** `integer`

Código de estado de la respuesta.

**data** `array`

Array con el resultado del envío.

**Propiedades**

**status** `string`

Estado del envío. Una tarea aceptada correctamente devuelve `submitted`.

**task\_id** `string`

Identificador único de la tarea. Úsalo para consultar periódicamente el endpoint de tareas.

## Obtener el resultado

Consulta periódicamente `GET /v1/tasks/{task_id}` hasta que la tarea alcance el estado `completed` o `failed`. Consulta la [API de estado de tareas](https://gccai.heqingsong.uk/es/api-reference/tasks/status.md) para ver el esquema completo de la respuesta.

Una tarea completada incluye una imagen generada:

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

La URL de la imagen se encuentra en `data.result.images[0].url[0]`. Su vencimiento lo determina la marca de tiempo Unix de `data.result.images[0].expires_at`; descarga la imagen antes de ese momento.

### Estados de la tarea

| Estado | Significado |
| - | - |
| `submitted` / `pending` | La tarea se ha aceptado o está en cola; sigue consultando |
| `processing` | La imagen se está generando; sigue consultando |
| `completed` | La tarea se ha completado; el resultado está en `result.images` |
| `failed` | La tarea ha fallado; el motivo está en `data.error.message` y se realiza un reembolso completo |

Ejemplo de una tarea fallida:

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

Los parámetros de modelo no válidos no generan un error 400 síncrono. El envío devuelve HTTP 200 y un `task_id`; al consultar la tarea, esta pasa a `failed`. El motivo específico siempre está en `error.message`, mientras que `error.code` es `task_failed`. Las tareas fallidas se reembolsan por completo.

## Notas

1. Las tareas se procesan de forma asíncrona. La respuesta al envío devuelve un `task_id` para realizar las consultas.
2. El parámetro `n` debe ser `1`; cada solicitud genera exactamente una imagen.
3. Las imágenes de referencia pueden proporcionarse mediante una URL accesible públicamente o en Base64.
4. Se admiten hasta 4 imágenes de referencia, y la suma de la salida y todas las referencias no debe superar los 9 MP.
5. Define explícitamente `prompt_upsampling: false` para desactivar la reescritura del prompt.
6. El vencimiento de la URL del resultado lo determina el valor `expires_at` devuelto en la respuesta de la tarea.


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