> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/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.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/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.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
      "size": "16:9"
    }'
  ```

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "flux-kontext-pro",
      "prompt": "Change hair color to blue",
      "image_urls": ["https://upload.apimart.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://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "flux-kontext-pro",
    prompt: "Change hair color to blue",
    image_urls: ["https://upload.apimart.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));
  ```
</RequestExample>

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

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

<ParamField header="Authorization" type="string" required>
  Todos los endpoints requieren autenticación mediante Bearer Token.

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

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Cuerpo de la solicitud

<ParamField body="model" type="string" required>
  Nombre del modelo:

  * `flux-kontext-pro`
  * `flux-kontext-max`
</ParamField>

<ParamField body="prompt" type="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.
</ParamField>

<ParamField body="image_urls" type="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.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Relación de aspecto de la imagen de salida. Valores compatibles:

  * `1:1` (valor predeterminado)
  * `4:3`
  * `3:4`
  * `16:9`
  * `9:16`
  * `3:2`
  * `2:3`
  * `21:9`
  * `9:21`

  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á.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  Formato de la imagen resultante: `png`, `jpeg` o `webp`. El valor predeterminado es `png`.
</ParamField>

<ParamField body="response_format" type="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`.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Número de imágenes que se generan. Solo se admite el valor `1`.
</ParamField>

<ParamField body="seed" type="integer">
  Semilla aleatoria. Reutiliza la misma semilla y los mismos parámetros para obtener resultados reproducibles; omítela para usar una semilla aleatoria.
</ParamField>

<ParamField body="prompt_upsampling" type="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.
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  Tolerancia de seguridad entre `0` y `6`. Los valores más altos son más permisivos.
</ParamField>

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

<ResponseField name="code" type="integer">
  Código de estado de la respuesta.
</ResponseField>

<ResponseField name="data" type="array">
  Array con el resultado del envío.

  <Expandable title="Propiedades">
    <ResponseField name="status" type="string">
      Estado del envío. Una tarea aceptada correctamente devuelve `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Identificador único de la tarea. Úsalo para consultar periódicamente el endpoint de tareas.
    </ResponseField>
  </Expandable>
</ResponseField>

## 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](/es/api-reference/tasks/status) 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.apimart.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.