> ## 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. # Nano banana 2.1 Generación de imágenes > Generación de texto a imagen y edición de imágenes de referencia en 1K / 2K / 4K, con 14 relaciones de aspecto y versiones oficial y Ext. ## Selección del modelo | ID del modelo | Facturación | Imágenes por solicitud | Tamaño de las imágenes de referencia | | - | - | - | - | | `gemini-nano-banana-2.1` | Uso real de tokens | 1–4 | Hasta 20MB por imagen | | `gemini-nano-banana-2.1-ext` | Por imagen, según el nivel de resolución | Solo 1 | Hasta 20MB por imagen, 50MB en total | Ambos modelos ofrecen las mismas dimensiones de salida y calidad de imagen. Elija la versión oficial para generar varias imágenes en una solicitud, o Ext para estimar el coste por imagen. Consulte los [precios de los modelos](https://gccai.heqingsong.uk/pricing) para conocer las tarifas aplicables. > [!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. Consulte cada 3–5 segundos y configure un tiempo de espera total de al menos 3 minutos. ```bash cURL theme={null} curl --request POST \ --url https://gccai.heqingsong.uk/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "gemini-nano-banana-2.1", "prompt": "Un gato naranja sobre una mesa de madera junto a una taza de café, suave luz matinal, fotografía realista", "size": "16:9", "resolution": "2K", "n": 1 }' ``` ```python Python theme={null} import requests response = requests.post( "https://gccai.heqingsong.uk/v1/images/generations", headers={"Authorization": "Bearer "}, json={ "model": "gemini-nano-banana-2.1", "prompt": "Un gato naranja sobre una mesa de madera junto a una taza de café, suave luz matinal, fotografía realista", "size": "16:9", "resolution": "2K", "n": 1 } ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://gccai.heqingsong.uk/v1/images/generations", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json" }, body: JSON.stringify({ model: "gemini-nano-banana-2.1", prompt: "Un gato naranja sobre una mesa de madera junto a una taza de café, suave luz matinal, fotografía realista", size: "16:9", resolution: "2K", n: 1 }) }); 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 `, donde `` es su GccAi API Key. ## Parámetros de la solicitud **model** `string` *required* ID del modelo: `gemini-nano-banana-2.1` o `gemini-nano-banana-2.1-ext`. **prompt** `string` *required* Descripción textual para generar o editar imágenes. Admite chino e inglés. **size** `string` (default: auto) Relación de aspecto de salida. Admite `1:4`, `4:1`, `1:8`, `8:1`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9` y `21:9`. También se acepta el formato `16x9`. Si se omite o se establece en `auto`, el modelo decide. En imagen a imagen, la salida sigue la relación de aspecto de la imagen de referencia. Las 14 relaciones están disponibles en las versiones oficial y Ext con `1K`, `2K` y `4K`. **resolution** `string` (default: 1K) Nivel de resolución de salida: `1K`, `2K` o `4K`. Se aceptan minúsculas. También afecta a la facturación. `0.5K` y `512` no se admiten y devuelven HTTP 400 al enviar la solicitud. Otros valores no reconocidos, como `3K`, generan y facturan en `1K`. Use solo los valores admitidos indicados arriba. **n** `integer` (default: 1) Número de imágenes: 1–4 en la versión oficial; solo 1 en Ext. Los valores superiores a 4 devuelven HTTP 400 de inmediato. Las solicitudes Ext con 2–4 fallan durante la ejecución y se reembolsan por completo. Para varias imágenes, envíe tareas Ext separadas o use la versión oficial. **image\_urls** `string[]` Lista de imágenes de referencia. Omítala para texto a imagen; inclúyala para imagen a imagen o edición. Cada elemento admite: * Una URL de imagen HTTP(S) accesible públicamente. * Una Data URL Base64, como `data:image/png;base64,...`. Se recomienda PNG, JPEG o WEBP. La versión oficial permite hasta 20MB por imagen. Ext permite hasta 20MB por imagen y 50MB en total. La plataforma no fija un número máximo de imágenes de referencia, pero esto no implica cargas ilimitadas: superar los límites del modelo puede provocar el fallo de la tarea y un reembolso. Más imágenes de referencia suelen requerir más tiempo. **official\_fallback** `boolean` (default: false) Solo se aplica a `gemini-nano-banana-2.1-ext`. Si se activa, intenta completar la tarea con la versión oficial cuando Ext falla. **Si se utiliza realmente la versión oficial, se factura según su uso real de tokens, no según el precio por imagen de Ext.** **webhook** `string` URL de callback para recibir una notificación al finalizar la tarea. Consulte los [webhooks de tareas](https://gccai.heqingsong.uk/es/api-reference/tasks/webhook.md). ## Dimensiones de salida de referencia | Relación de aspecto | 1K | 2K | 4K | | - | - | - | - | | 1:1 | 1024×1024 | 2048×2048 | 4096×4096 | | 2:3 | 848×1264 | 1696×2528 | 3392×5056 | | 3:2 | 1264×848 | 2528×1696 | 5056×3392 | | 3:4 | 896×1200 | 1792×2400 | 3584×4800 | | 4:3 | 1200×896 | 2400×1792 | 4800×3584 | | 4:5 | 928×1152 | 1856×2304 | 3712×4608 | | 5:4 | 1152×928 | 2304×1856 | 4608×3712 | | 9:16 | 768×1376 | 1536×2752 | 3072×5504 | | 16:9 | 1376×768 | 2752×1536 | 5504×3072 | | 21:9 | 1584×672 | 3168×1344 | 6336×2688 | Estas dimensiones incluyen valores medidos y valores de referencia de la familia de modelos. No se han probado todas las combinaciones. Las dimensiones reales en píxeles de la imagen devuelta son las definitivas. ## Editar una imagen de referencia ```json theme={null} { "model": "gemini-nano-banana-2.1-ext", "prompt": "Pon un gorro rojo de punto al gato de la imagen y deja todo lo demás sin cambios", "image_urls": ["https://example.com/cat.jpg"], "resolution": "1K" } ``` Sustituya la URL de ejemplo por una URL de imagen accesible. Si se omite `size`, la salida sigue la relación de aspecto de la imagen de referencia. ## Generación por lotes (solo versión oficial) ```json theme={null} { "model": "gemini-nano-banana-2.1", "prompt": "Ciudad ciberpunk de noche, luces de neón, calles después de la lluvia", "size": "16:9", "resolution": "2K", "n": 4 } ``` ## 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. `status` es `submitted`. `task_id` permite consultar el estado y los resultados; no es la URL de la imagen final. ## Consultar los resultados de la tarea ```bash theme={null} curl --request GET \ --url https://gccai.heqingsong.uk/v1/tasks/task_01K... \ --header 'Authorization: Bearer ' ``` Ejemplo de respuesta correcta (la URL de imagen es ilustrativa): ```json theme={null} { "code": 200, "data": { "id": "task_01K...", "status": "completed", "progress": 100, "result": { "images": [ { "url": ["https://example.com/generated-image.png"], "expires_at": 1791417625 } ] } } } ``` | Estado de la tarea | Significado | | - | - | | `pending` | En cola | | `processing` | Generando | | `completed` | Éxito; lea el array de URL de imágenes en `data.result.images[0].url` | | `failed` | Fallo; motivo en `data.error.message`. Reembolso completo; `data.cost` es 0 | Todos los enlaces de las imágenes finales están en el array `data.result.images[0].url`. Si se generan 4 imágenes, el array contiene 4 enlaces. Solo se devuelven imágenes finales; `n=1` corresponde a 1 imagen final. Los enlaces caducan 24 horas después de finalizar la tarea, según `expires_at`. Descargue y guarde las imágenes a tiempo. La salida es PNG o JPEG; consulte el contenido real del archivo. `data.cost` en el resultado de la consulta es el importe final cobrado en USD. ## Facturación * **Versión oficial**: se factura el uso real de tokens de entrada y salida. Los prompts y las imágenes de referencia cuentan como entrada. Al enviar se descuenta un importe según la resolución y `n`; al finalizar se ajusta al uso real mediante reembolso o cobro adicional. * **Versión Ext**: precio unitario del nivel de resolución × número real de imágenes generadas. La relación de aspecto no afecta al nivel. Si `official_fallback` está activado y se utiliza realmente la versión oficial, se aplica su facturación por tokens. * Consulte los [precios de los modelos](https://gccai.heqingsong.uk/pricing) para conocer las tarifas. Las solicitudes rechazadas al enviarse no crean tareas ni generan cargos. Las tareas fallidas se reembolsan por completo. ## Errores frecuentes | Situación | Acción | | - | - | | HTTP 400 | Compruebe `0.5K` / `512`, `n` superior a 4 o imágenes de referencia que superen el límite por imagen | | HTTP 401 | Compruebe la API Key | | HTTP 402 | Compruebe que el saldo cubra el cargo inicial | | HTTP 429 | Límite de solicitudes alcanzado; reintente con espera progresiva | | Tarea fallida: relación de aspecto no admitida | Use una de las 14 relaciones `size` admitidas o `auto` | | Tarea fallida: varias imágenes solicitadas con Ext | Establezca `n` en 1 o use la versión oficial | | Tarea fallida: bloqueo de seguridad del contenido | Modifique el prompt o las imágenes de referencia y reintente | | Tarea fallida: error al descargar la imagen de referencia | Asegúrese de que la URL de imagen sea accesible públicamente | > [!WARNING] > > Nano banana 2.1 y Gemini 3.1 Flash Image son modelos distintos; sus nombres no son alias intercambiables. Al migrar desde este último, cambie la resolución no admitida `0.5K`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.