> ## 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 Geração de imagens > Geração de texto para imagem e edição de imagens de referência em 1K / 2K / 4K, com 14 proporções e versões oficial e Ext. ## Escolha do modelo | ID do modelo | Cobrança | Imagens por solicitação | Tamanho das imagens de referência | | - | - | - | - | | `gemini-nano-banana-2.1` | Uso real de tokens | 1–4 | Até 20MB por imagem | | `gemini-nano-banana-2.1-ext` | Por imagem, conforme a faixa de resolução | Apenas 1 | Até 20MB por imagem, 50MB no total | Os dois modelos oferecem as mesmas dimensões de saída e qualidade de imagem. Escolha a versão oficial para gerar várias imagens em uma solicitação ou Ext para estimar o custo por imagem. Consulte os [preços dos modelos](https://gccai.heqingsong.uk/pricing) para os valores aplicáveis. > [!NOTE] > > Este endpoint é assíncrono. Um envio bem-sucedido retorna um `task_id`. Use a [consulta de tarefas](https://gccai.heqingsong.uk/pt/api-reference/tasks/status.md) para obter o status e as imagens. Consulte a cada 3–5 segundos e configure um tempo limite total de espera de pelo 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": "Um gato laranja sobre uma mesa de madeira ao lado de uma xícara de café, luz suave da manhã, fotografia 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": "Um gato laranja sobre uma mesa de madeira ao lado de uma xícara de café, luz suave da manhã, fotografia 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: "Um gato laranja sobre uma mesa de madeira ao lado de uma xícara de café, luz suave da manhã, fotografia 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..." } ] } ``` ## Cabeçalhos da solicitação **Authorization** `string` *required* Autenticação Bearer no formato `Bearer `, em que `` é sua GccAi API Key. ## Parâmetros da solicitação **model** `string` *required* ID do modelo: `gemini-nano-banana-2.1` ou `gemini-nano-banana-2.1-ext`. **prompt** `string` *required* Descrição textual para gerar ou editar imagens. Chinês e inglês são suportados. **size** `string` (default: auto) Proporção da imagem de saída. Suporta `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` e `21:9`. Formatos como `16x9` também são aceitos. Se omitido ou definido como `auto`, o modelo decide. Na geração de imagem para imagem, a saída segue a proporção da imagem de referência. As 14 proporções são suportadas pelas versões oficial e Ext em `1K`, `2K` e `4K`. **resolution** `string` (default: 1K) Faixa de resolução de saída: `1K`, `2K` ou `4K`. Letras minúsculas são aceitas. Também afeta a cobrança. `0.5K` e `512` não são suportados e retornam HTTP 400 no envio. Outros valores não reconhecidos, como `3K`, são gerados e cobrados como `1K`. Use apenas os valores suportados acima. **n** `integer` (default: 1) Número de imagens geradas: 1–4 na versão oficial; apenas 1 na Ext. Valores acima de 4 retornam HTTP 400 imediatamente. Solicitações Ext com 2–4 falham durante a execução e recebem reembolso integral. Para várias imagens, envie tarefas Ext separadas ou use a versão oficial. **image\_urls** `string[]` Lista de imagens de referência. Omita para texto para imagem; inclua para imagem para imagem ou edição. Cada item aceita: * Uma URL de imagem HTTP(S) acessível publicamente. * Uma Data URL Base64, como `data:image/png;base64,...`. Recomenda-se PNG, JPEG ou WEBP. A versão oficial permite até 20MB por imagem. Ext permite até 20MB por imagem e 50MB no total. A plataforma não define um limite fixo de quantidade de imagens de referência, mas isso não significa uploads ilimitados: ultrapassar os limites do modelo pode causar falha na tarefa e reembolso. Mais imagens de referência geralmente aumentam o tempo de processamento. **official\_fallback** `boolean` (default: false) Aplica-se apenas a `gemini-nano-banana-2.1-ext`. Quando ativado, tenta concluir a tarefa com a versão oficial se Ext falhar. **Se a versão oficial for realmente usada, a cobrança passa a seguir seu uso real de tokens, e não o preço por imagem da Ext.** **webhook** `string` URL de callback para notificação ao término da tarefa. Consulte os [webhooks de tarefas](https://gccai.heqingsong.uk/pt/api-reference/tasks/webhook.md). ## Referência de dimensões de saída | Proporção | 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 dimensões incluem valores medidos e valores de referência da família de modelos. Nem todas as combinações foram testadas. As dimensões reais em pixels da imagem retornada são as definitivas. ## Editar uma imagem de referência ```json theme={null} { "model": "gemini-nano-banana-2.1-ext", "prompt": "Coloque um gorro vermelho de tricô no gato da imagem e mantenha todo o restante inalterado", "image_urls": ["https://example.com/cat.jpg"], "resolution": "1K" } ``` Substitua a URL de exemplo por uma URL de imagem acessível. Se `size` for omitido, a saída segue a proporção da imagem de referência. ## Geração em lote (apenas versão oficial) ```json theme={null} { "model": "gemini-nano-banana-2.1", "prompt": "Cidade cyberpunk à noite, luzes de neon, ruas após a chuva", "size": "16:9", "resolution": "2K", "n": 4 } ``` ## Resposta do envio **code** `integer` Código de status da resposta. `200` indica sucesso. **data** `array` Resultado do envio da tarefa. `status` é `submitted`. `task_id` serve para consultar o status e os resultados; não é a URL da imagem final. ## Consultar resultados da tarefa ```bash theme={null} curl --request GET \ --url https://gccai.heqingsong.uk/v1/tasks/task_01K... \ --header 'Authorization: Bearer ' ``` Exemplo de resposta bem-sucedida (a URL da imagem é 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 } ] } } } ``` | Status da tarefa | Significado | | - | - | | `pending` | Na fila | | `processing` | Em geração | | `completed` | Sucesso; leia o array de URLs em `data.result.images[0].url` | | `failed` | Falha; motivo em `data.error.message`. Reembolso integral; `data.cost` é 0 | Todos os links das imagens finais estão no array `data.result.images[0].url`. Ao gerar 4 imagens, esse array contém 4 links. Apenas imagens finais são retornadas; `n=1` corresponde a 1 imagem final. Os links expiram 24 horas após a conclusão da tarefa, conforme `expires_at`. Baixe e salve as imagens a tempo. A saída é PNG ou JPEG; considere o conteúdo real do arquivo. `data.cost` no resultado da consulta é o valor final cobrado em USD. ## Cobrança * **Versão oficial**: cobrança pelo uso real de tokens de entrada e saída. Prompts e imagens de referência contam como entrada. No envio, um valor é debitado antecipadamente com base na resolução e em `n`; ao concluir, é ajustado ao uso real por reembolso ou cobrança adicional. * **Versão Ext**: preço unitário da faixa de resolução × quantidade real de imagens geradas. A proporção não afeta a faixa. Se `official_fallback` estiver ativado e a versão oficial for realmente usada, aplica-se a cobrança por tokens da versão oficial. * Consulte os [preços dos modelos](https://gccai.heqingsong.uk/pricing) para os valores unitários. Solicitações rejeitadas no envio não criam tarefas nem geram cobrança. Tarefas com falha recebem reembolso integral. ## Erros comuns | Situação | Ação | | - | - | | HTTP 400 | Verifique `0.5K` / `512`, `n` acima de 4 ou imagens de referência que excedam o limite por imagem | | HTTP 401 | Verifique a API Key | | HTTP 402 | Verifique se o saldo cobre o débito inicial | | HTTP 429 | Limite de requisições atingido; tente novamente com espera progressiva | | Falha: proporção não suportada | Use uma das 14 proporções `size` suportadas ou `auto` | | Falha: várias imagens solicitadas com Ext | Defina `n` como 1 ou use a versão oficial | | Falha: bloqueio de segurança do conteúdo | Altere o prompt ou as imagens de referência e tente novamente | | Falha: download da imagem de referência | Verifique se a URL da imagem é acessível publicamente | > [!WARNING] > > Nano banana 2.1 e Gemini 3.1 Flash Image são modelos diferentes; seus nomes não são aliases intercambiáveis. Ao migrar deste último, altere a resolução não suportada `0.5K`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.