> ## 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 Generación de imágenes

> Generación de texto a imagen, edición de una imagen y hasta 10 imágenes de referencia, con varias relaciones de aspecto y resolución de hasta 4k.

> [!NOTE]
>
> Este endpoint es asíncrono. Un envío correcto devuelve un `task_id`. Use la [consulta de tareas](https://gccai.heqingsong.uk/es/api-reference/tasks/status.md) para obtener el estado y las imágenes. Deje de consultar cuando el estado sea `completed` o `failed`. La generación en `4k` puede tardar varios minutos; se recomienda un tiempo de espera total de 10 minutos.

```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",
    "prompt": "Plano cinematográfico ultra panorámico de una carretera costera envuelta en niebla al amanecer, un único coche antiguo con los faros encendidos",
    "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",
        "prompt": "Plano cinematográfico ultra panorámico de una carretera costera envuelta en niebla al amanecer, un único coche antiguo con los faros encendidos",
        "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",
    prompt: "Plano cinematográfico ultra panorámico de una carretera costera envuelta en niebla al amanecer, un único coche antiguo con los faros encendidos",
    aspect_ratio: "21:9",
    resolution: "2k"
  })
});
console.log(await response.json());
```

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

## Encabezados de la solicitud

**Authorization** `string` *required*

Autenticación Bearer con el formato `Bearer <token>`, donde `<token>` es su GccAi API Key.

## Parámetros de la solicitud

**model** `string` *required*

Debe ser `flux-3-image`.

**prompt** `string` *required*

Descripción de la escena para texto a imagen o instrucciones de edición. No se admiten prompts negativos; describa lo que desea ver.

Use etiquetas y JSON bbox dentro de `prompt` para definir composiciones o zonas de edición local. Consulte los ejemplos siguientes.

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

Lista de imágenes de referencia, con un máximo de 10 imágenes. Admite URL HTTP(S) accesibles públicamente o entradas Base64.

Omítala para texto a imagen. Proporcione una imagen para editarla o varias para usarlas como referencias.

**aspect\_ratio** `string` (default: auto)

Relación de aspecto de salida. Valores admitidos:

`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` o `auto`.

También se aceptan formatos como `16x9`. Con `auto`:

* Edición o varias referencias: sigue la relación de aspecto de la primera imagen de referencia.
* Texto a imagen: se determina a partir del prompt; usa `1:1` si no se determina una relación.

**size** `string`

Parámetro de compatibilidad para la relación de aspecto. Puede sustituir a `aspect_ratio` y admite los mismos valores. Se recomienda usar solo uno de estos campos.

No se admiten dimensiones en píxeles como `1024x1024`; devuelven HTTP 400. Use `resolution` para elegir la resolución de salida.

**resolution** `string` (default: 1k)

Nivel de resolución. Admite `768sq`, `1k`, `1.5k`, `2k` y `4k`, sin distinguir mayúsculas y minúsculas. `768` equivale a `768sq`.

Este parámetro determina el nivel de facturación. Si se omite, se genera y factura en `1k`. Los valores no admitidos, como `3k`, devuelven HTTP 400.

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

Tolerancia de seguridad del contenido, de 0 a 4. 0 es el nivel más estricto.

**grounding** `boolean` (default: true)

Indica si se permiten búsquedas web o de imágenes antes de la generación. Use `false` para desactivarlas.

Debe ser un booleano, no las cadenas `"false"` o `"true"`.

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

Cada solicitud genera 1 imagen; solo se admite `1`. Para varias imágenes, envíe tareas separadas. Los valores superiores a 1 devuelven HTTP 400.

## Parámetros no admitidos

Los siguientes parámetros devuelven HTTP 400 cuando se proporcionan; no se ignoran silenciosamente:

* `width`, `height`
* Dimensiones en píxeles en `size`, como `1024x1024`
* `seed`, `steps`, `guidance`
* `output_format`, `negative_prompt`, `prompt_upsampling`, `mask_url`

Use `resolution` para una resolución mayor y `aspect_ratio` para una relación de aspecto específica.

## Editar una imagen de referencia

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "Cambia el coche de la imagen a rojo y conserva la carretera, el fondo y la iluminación originales",
  "image_urls": ["https://example.com/car.jpg"],
  "aspect_ratio": "auto",
  "resolution": "2k"
}
```

Sustituya la URL de ejemplo por una URL de imagen accesible públicamente. Para varias referencias, proporcione varias URL en `image_urls`, con un máximo de 10 imágenes en total.

## Referencias múltiples

La edición, la edición local y la composición usan el mismo endpoint y modelo de esta página, con facturación según `resolution`. Las referencias se numeran en orden: `ref_image_0` para la primera y `ref_image_1` para la segunda. También puede usar `Image 1` / `Image 2` en el prompt.

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "Convierte Image 1 al estilo de Image 2.",
  "image_urls": [
    "https://example.com/subject.jpg",
    "https://example.com/style.jpg"
  ],
  "aspect_ratio": "auto"
}
```

## Edición local (bounding box)

Empiece `prompt` con instrucciones en lenguaje natural y use `<etiquetas>` como `<car_1>` para identificar elementos. Añada un array JSON en la misma cadena, con un objeto por recuadro. bbox no es un parámetro de solicitud independiente.

| Campo | Descripción |
| - | - |
| `id` | Coincide con la etiqueta del elemento en el prompt, sin los corchetes angulares. |
| `from` | Origen del elemento, como `ref_image_0`; use `null` para elementos nuevos o que se vayan a redibujar. |
| `src_bbox` | Recuadro en la imagen original; también debe ser `null` cuando `from` es `null`. |
| `tgt_bbox` | Recuadro en la imagen de salida; igual a `src_bbox` conserva la posición, distinto mueve el elemento. |
| `desc` | Describe cómo cambiar el elemento o qué conservar. |

Todos los campos de recuadro (`src_bbox`, `tgt_bbox`, `bbox`) usan `[arriba, izquierda, abajo, derecha]`, es decir, `[y1, x1, y2, x2]`, en una **cuadrícula normalizada de 0 a 1000**: `[0,0]` arriba a la izquierda y `[1000,1000]` abajo a la derecha. No son coordenadas en píxeles.

Este ejemplo cambia a rojo el coche dentro del recuadro y describe el fondo que se debe conservar. La URL y las posiciones son ilustrativas; ajústelas a su imagen.

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "En <ref_image_0>, cambia el coche <car_1> a rojo y conserva el fondo <background_1>. [{\"id\":\"car_1\",\"from\":null,\"src_bbox\":null,\"tgt_bbox\":[250,300,750,800],\"desc\":\"Un coche rojo que conserva su forma y orientación originales.\"},{\"id\":\"background_1\",\"from\":\"ref_image_0\",\"src_bbox\":[0,0,1000,1000],\"tgt_bbox\":[0,0,1000,1000],\"desc\":\"Conservar la carretera, el fondo y la iluminación originales.\"}]",
  "image_urls": [
    "https://example.com/car.jpg"
  ],
  "aspect_ratio": "auto",
  "resolution": "2k"
}
```

### Mover un elemento

Incluya el siguiente objeto en el array bbox al final del prompt. `from` identifica la imagen original, `src_bbox` la posición original y `tgt_bbox` la nueva. Use también la etiqueta correspondiente `<knight_1>` en la instrucción en lenguaje natural.

```json theme={null}
{
  "id": "knight_1",
  "from": "ref_image_0",
  "src_bbox": [
    500,
    150,
    850,
    350
  ],
  "tgt_bbox": [
    194,
    55,
    544,
    255
  ],
  "desc": "Una figura pequeña de un caballero gris de amigurumi."
}
```

## Composición de texto a imagen

También puede definir composiciones sin imágenes de referencia. Cada recuadro usa `id`, `bbox` y `desc`. Especifique `aspect_ratio`, ya que la cuadrícula se estira según la relación de aspecto.

```json theme={null}
{
  "model": "flux-3-image",
  "aspect_ratio": "1:1",
  "prompt": "Ilustración minimalista de una silueta negra corriendo <silhouette_1> sobre un fondo verde amarillento uniforme <background_1>. [{\"id\":\"background_1\",\"bbox\":[0,0,1000,1000],\"desc\":\"Un fondo verde amarillento fluorescente con una sutil textura de papel.\"},{\"id\":\"silhouette_1\",\"bbox\":[150,150,850,850],\"desc\":\"Una silueta negra corriendo con textura punteada.\"}]"
}
```

### Notas de uso

* El JSON bbox forma parte de la cadena `prompt`. Al escribir el JSON de la solicitud manualmente, escape las comillas dobles internas como `\"`. Los SDK o la serialización JSON pueden hacerlo automáticamente.

* Incluya también las zonas que deben conservarse y describa qué mantener en `desc`.

* Las etiquetas de los elementos en el prompt deben corresponder una a una con los valores `id` del JSON. Los identificadores de referencia como `<ref_image_0>` apuntan a las imágenes de entrada.

* Este modelo no tiene un parámetro `mask` ni admite `mask_url`; enviar `mask_url` devuelve HTTP 400. La edición bbox no usa un parámetro de carga de máscaras.

## Respuesta del envío

**code** `integer`

Código de estado de la respuesta. `200` indica éxito.

**data** `array`

Resultado del envío de la tarea.

**Mostrar campos de la tarea**

**status** `string`

`submitted` indica que el envío fue correcto, no que la generación haya terminado.

**task\_id** `string`

ID de la tarea para consultar el estado y los resultados.

## Consultar resultados

```bash theme={null}
curl --request GET \
  --url https://gccai.heqingsong.uk/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

Ejemplo de respuesta correcta (la URL de imagen es ilustrativa):

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.jpg"]
        }
      ]
    }
  }
}
```

Lea los enlaces de imágenes del array `data.result.images[0].url`. Si el estado de la tarea es `failed`, revise el error devuelto en lugar de seguir esperando una imagen.

## Resolución y facturación

Se factura por imagen. El precio unitario depende únicamente de `resolution`, no de la relación de aspecto ni del número de imágenes de referencia. Las referencias no tienen coste adicional.

| Nivel de resolución | Tamaño de salida aproximado |
| - | - |
| `768sq` | Aproximadamente 768×768 |
| `1k` (predeterminado) | Aproximadamente 1MP |
| `1.5k` | Aproximadamente 2MP |
| `2k` | Aproximadamente 4MP |
| `4k` | Aproximadamente 16MP |

Los tamaños son aproximados; las dimensiones reales en píxeles dependen de la imagen devuelta. Consulte los [precios de los modelos](https://gccai.heqingsong.uk/pricing) para cada nivel.

Las tareas que fallen o sean bloqueadas por la moderación reciben un reembolso completo.

## Errores frecuentes de parámetros

| Solicitud | Resultado y acción |
| - | - |
| `resolution: "3k"` | HTTP 400; use uno de los 5 niveles admitidos |
| `size: "1024x1024"` | HTTP 400; use una relación de aspecto y elija la resolución con `resolution` |
| `n: 2` | HTTP 400; solo se genera 1 imagen por solicitud |
| 11 imágenes de referencia | HTTP 400; proporcione como máximo 10 |
| `grounding: "false"` | HTTP 400; use el booleano `false` |


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