# Nano Banana Pro API: tutorial em Python, edição de imagem e preço

> Chame o Nano Banana Pro no Python: id do modelo, campos de tamanho e input.image, opção 4K, preço por imagem do Google e o JSON que cada chamada devolve.

- Canonical HTML: https://omniakey.com/pt-BR/blog/nano-banana-pro-api
- Markdown: https://omniakey.com/pt-BR/blog/nano-banana-pro-api.md
- Published: 2026-11-03 (updated 2026-11-03)
- Author: Kiki, COO at OmniaKey
- Language: pt-BR
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

O Nano Banana Pro é o `gemini-3-pro-image` do Google, e no OmniaKey você chama com um único `POST /v1/media/tasks`. Nossos três testes em 3:4 voltaram em 896x1200, 1792x2400 e 3584x4800, e todas as palavras do pôster estavam escritas corretamente.

## Resposta curta

- **Modelo:** `gemini-3-pro-image` é o id GA do Google. A ficha do modelo no Vertex traz data de lançamento em 28 de maio de 2026.
- **Chamada:** envie `POST https://api.omniakey.com/v1/media/tasks` com uma `Idempotency-Key`, consulte `GET /v1/media/tasks/{id}` até o status ser succeeded e baixe `assets[0].url`.
- **Parâmetros:** `parameters.aspect_ratio` e `parameters.image_size`; os valores de tamanho são 1K, 2K e 4K, com K maiúsculo.
- **Limite da requisição:** 1 MiB para o corpo inteiro, incluindo os dados de imagem em Base64.
- **Preço do Google:** $0.134 por imagem 1K/2K e $0.24 por imagem 4K, da página de preços da API Gemini.
- **Nossos tokens:** as três tarefas reportaram 1,133, 1,225 e 2,480 tokens de saída. A $120 por milhão de tokens de imagem, isso dá $0.136, $0.147 e $0.298.
- **Edição:** use `operation: "edit"` e coloque a imagem de origem em `input.image` como `{data, mime_type}`.

A [página do modelo Nano Banana Pro](https://omniakey.com/pt-BR/gemini-3-pro-image) no OmniaKey também aceita `gemini-3-pro-image-preview`, o id de snapshot mais antigo, pelo mesmo preço.

## O id do modelo e o que você precisa

O id para escrever no código é `gemini-3-pro-image`. A [ficha do modelo no Vertex](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image) lista o modelo como GA, com lançamento em 28 de maio de 2026, e saída em 1K, 2K e 4K.

O id -preview aponta para o mesmo modelo. A [tabela de modelos de imagem](https://docs.omniakey.com/en/media/image) do OmniaKey descreve `gemini-3-pro-image-preview` como "Same model, -preview snapshot id", com a mesma tarifa por chamada.

Você precisa de duas coisas:

1. Uma chave de API do OmniaKey, exportada para o script ler: `export OMNIAKEY_API_KEY="your-key"`.
2. Python 3. O script abaixo usa só a biblioteca padrão: urllib, json, time, uuid, base64 e pathlib. Não há SDK para instalar.

## O script em Python

Três passos: criar a tarefa, consultar e baixar a imagem. Salve como `nano_banana.py` e rode com `python3 nano_banana.py`.

```python
import base64
import json
import os
import time
import urllib.request
import uuid
from pathlib import Path

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}",
    "Content-Type": "application/json",
}


def call(url, payload=None, headers=None, method=None):
    body = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(url, data=body, headers=headers or HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=60) as resp:
        return resp.status, json.loads(resp.read())


def create_task(prompt, aspect_ratio="3:4", image_size="2K", image_path=None):
    body = {
        "model": "gemini-3-pro-image",
        "type": "image",
        "operation": "generate" if image_path is None else "edit",
        "input": {"prompt": prompt},
        "parameters": {"aspect_ratio": aspect_ratio, "image_size": image_size},
    }
    if image_path:
        encoded = base64.b64encode(Path(image_path).read_bytes()).decode("utf-8")
        body["input"]["image"] = {"data": encoded, "mime_type": "image/png"}
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    status, task = call(API, body, headers, "POST")
    print("created", task["id"], "HTTP", status)
    return task


def wait(task_id, interval=3, timeout=300):
    deadline = time.time() + timeout
    while time.time() < deadline:
        _, task = call(f"{API}/{task_id}")
        print(task["status"], task["progress"]["percent"])
        if task["status"] in ("succeeded", "failed", "canceled"):
            return task
        time.sleep(interval)
    # A timeout is not a failure: keep the task id and poll it again.
    raise TimeoutError(f"task {task_id} is still running")


def download(task, out_path):
    asset = task["assets"][0]
    with urllib.request.urlopen(asset["url"], timeout=120) as resp:
        Path(out_path).write_bytes(resp.read())
    print("saved", out_path, asset["mime_type"], asset["byte_size"], "bytes")


if __name__ == "__main__":
    task = create_task(
        "A vintage travel poster for the Night Train from Zürich to Milano, "
        "departing 21:40 from platform 7. A steam train crosses a stone arch "
        "bridge below snowy mountains under a deep blue night sky, with a cream "
        "border. Spell every word exactly as written.",
        aspect_ratio="3:4",
        image_size="2K",
    )
    task = wait(task["id"])
    if task["status"] != "succeeded":
        raise SystemExit(f"{task['status']}: {task.get('error')}")
    download(task, "night-train.jpg")
```

`image_size` aceita 1K, 2K ou 4K. O guia de imagens do Google é explícito: "You must use an uppercase 'K' … Lowercase parameters (e.g., 1k) will be rejected." Envie 2K, não 2k.

`Idempotency-Key` é obrigatório. Um UUID novo por requisição é a regra simples; reutilize uma chave apenas quando repetir exatamente o mesmo corpo. O OmniaKey devolve a tarefa original com HTTP 200 em vez de cobrar duas vezes, e responde 409 se a mesma chave chegar com outro corpo.

A chamada de criação retorna 202 com um id. A [documentação de tarefas de mídia](https://docs.omniakey.com/en/media/overview) do OmniaKey descreve o ciclo completo; a tarefa concluída carrega os campos abaixo:

```json
{
  "id": "task_AbMRVqzSnVh0VwBj0S7NuMUxy5sZtfHP",
  "status": "succeeded",
  "progress": {"percent": 100, "stage": "completed"},
  "usage": {"total_tokens": 1133},
  "assets": [
    {
      "kind": "image",
      "mime_type": "…",
      "url": "https://…signed-url…"
    }
  ]
}
```

Leia `assets[0].url` e baixe na hora: o link assinado dura cerca de uma hora, e o registro da tarefa fica 24 horas. O campo `mime_type` diz o formato; os modelos Gemini costumam devolver JPEG.

O mesmo script em 1:1 e 2K, com um letreiro em chinês no prompt, devolveu isto:

![Um letreiro de metal escuro numa parede de tijolos, com três linhas de texto em chinês e um número de telefone](https://omniakey.com/_img/blog/nano-banana-pro-api/g2-sign.7e3e8e4d.1600.webp)

_2K, 1:1: 2048x2048 em 47.2 s. As três linhas em chinês e o 010-6789 4321 saíram certos; a ferrugem cobre parte do primeiro 0._

## Editar uma imagem existente

Ponha `operation: "edit"` e passe a imagem de origem em `input.image` como `{data, mime_type}`. O script acima já faz isso quando você passa um image\_path:

```python
task = create_task(
    "Hang this poster in a thin black frame on a warm white wall, with a brass "
    "picture light above it, a low wooden cabinet below and a trailing plant on "
    "the right. Keep the poster exactly as it is.",
    aspect_ratio="1:1",
    image_size="2K",
    image_path="night-train-2k.png",
)
```

O corpo que ele envia fica assim:

```json
{
  "model": "gemini-3-pro-image",
  "type": "image",
  "operation": "edit",
  "input": {
    "prompt": "Hang this poster in a thin black frame on a warm white wall…",
    "image": {"data": "…base64…", "mime_type": "image/png"}
  },
  "parameters": {"aspect_ratio": "1:1", "image_size": "2K"}
}
```

A origem do exemplo é um PNG, então o script marca `image/png`; troque esse rótulo para um JPEG. Para várias referências, use `input.images` e dê a cada item o mesmo formato `{data, mime_type}`. O guia do Google põe o limite em 14 imagens de referência; no `gemini-3-pro-image` a divisão é 6 imagens de objeto, 5 de personagem e 3 de estilo.

Mantenha o corpo abaixo de 1 MiB. O Base64 deixa o arquivo cerca de um terço maior, então reduza ou comprima a origem antes de codificar. Nossa edição usou o pôster de 2K e preservou cada palavra e o layout:

![O pôster do trem noturno numa moldura preta na parede, com um luminária de quadro acima e uma planta à direita](https://omniakey.com/_img/blog/nano-banana-pro-api/g3-edit.98011b5c.1600.webp)

_2K, edição 1:1: 2048x2048 em 49.9 s. O texto e o desenho do pôster sobreviveram; a moldura é um retângulo limpo._

## 1K, 2K e 4K: o que cada um entrega

Rodamos o mesmo prompt de pôster em 3:4 nos três tamanhos. Os pixels bateram exatamente com a tabela do Google para 3:4: 896x1200 em 1K, 1792x2400 em 2K e 3584x4800 em 4K. O texto do pôster saiu certo em todos os tamanhos.

![O pôster do trem noturno em 1K: trem a vapor numa ponte de pedra, montanhas nevadas e céu azul profundo](https://omniakey.com/_img/blog/nano-banana-pro-api/g1-1k.12bc0ed0.896.webp)

_1K, 3:4: 896x1200 em 28.4 s. As quatro linhas do pôster estão certas; os faróis e as bielas da locomotiva se aglomeram._

![O mesmo pôster do trem noturno em 2K, com um vilarejo e duas torres acrescentados na encosta da direita](https://omniakey.com/_img/blog/nano-banana-pro-api/g1-2k.38a932bb.1600.webp)

_2K, 3:4: 1792x2400 em 48.2 s. Mesmo texto, mais um vilarejo e duas torres na encosta da direita._

![O mesmo pôster do trem noturno em 4K, com três vagões e o tender desenhados atrás da locomotiva](https://omniakey.com/_img/blog/nano-banana-pro-api/g1-4k.6c8048ad.1600.webp)

_4K, 3:4: 3584x4800 em 66.9 s. Três vagões e o tender aparecem; as juntas dos tijolos variam de espessura._

O que muda com o tamanho é o detalhe, não a grafia:

- **1K:** a frente do trem fica apertada: faróis, rodas e bielas quase se encostam.
- **2K:** o vilarejo e suas duas torres aparecem na encosta da direita, a chaminé solta um fio claro de fumaça e a ponte mostra sete arcos.
- **4K:** os três vagões e o tender ficam separados, e a alvenaria mostra juntas de espessuras diferentes. A mecânica sob a locomotiva continua simplificada.

A velocidade subiu com o tamanho: 28.4 s, 48.2 s e 66.9 s. Rodamos cada tamanho uma vez, então leia esses segundos como uma única passada.

O Google cobra a saída de imagem a $120 por milhão de tokens, e a tabela dele dá 1,120 tokens tanto para 1K quanto para 2K e 2,000 tokens para 4K. Daí sai a estimativa dele:

```text
1,120 × $120 ÷ 1,000,000 = $0.134 per 1K image
1,120 × $120 ÷ 1,000,000 = $0.134 per 2K image
2,000 × $120 ÷ 1,000,000 = $0.24  per 4K image
```

Nossas tarefas reportaram mais tokens que os exemplos do Google. Aqui está a mesma conta com os nossos números:

```text
1,133 × $120 ÷ 1,000,000 = $0.136 per 1K image
1,225 × $120 ÷ 1,000,000 = $0.147 per 2K image
2,480 × $120 ÷ 1,000,000 = $0.298 per 4K image
```

|Tamanho|Pixels, 3:4|Nosso tempo|Nossos tokens|Estimativa do Google|
|-|-|-|-|-|
|1K|896x1200|28.4 s|1,133|$0.134|
|2K|1792x2400|48.2 s|1,225|$0.134|
|4K|3584x4800|66.9 s|2,480|$0.24|

O OmniaKey cobra a chamada de imagem por valor fixo, não por token, então o valor não muda com essas contagens; a tarifa atual por chamada está na [página do modelo](https://omniakey.com/pt-BR/gemini-3-pro-image), e uma tarefa com falha é reembolsada. A estimativa do Google pela tarifa de tokens para as mesmas três imagens é $0.134, $0.134 e $0.24.

## Erros que você vai encontrar

As falhas listadas aqui quase sempre se resumem a um nome de campo ou a um tamanho de arquivo, não ao modelo. Estas são as que a documentação de mídia do OmniaKey lista para este endpoint:

|HTTP|Código ou status|O que significa|O que fazer|
|-|-|-|-|
|400|`invalid_request`|Corpo malformado, operação não suportada ou parâmetro errado|Confira o JSON e os nomes de campo abaixo|
|503|`no_available_channel`|Nenhum canal atende este modelo agora|Troque de modelo; repetir não resolve|
|—|`failed`|A tarefa terminou sem resultado|Leia `error.code` e `error.message`|

Uma tarefa `failed` não é erro HTTP: a chamada de criação deu certo, então consulte a tarefa e leia o objeto `error`. Tarefas que falharam ou foram canceladas são reembolsadas automaticamente.

Uma origem em resolução total enviada em Base64 pode empurrar o corpo acima de 1 MiB. Reduza primeiro e olhe o comprimento codificado, não só o tamanho do arquivo.

O guia do Google recusa um `1k` minúsculo. Use 1K, 2K ou 4K.

A documentação de imagem do OmniaKey também recusa `size` e um `mime_type` de primeiro nível nos modelos Gemini, porque não são parâmetros do Gemini. Use `parameters.aspect_ratio` e `parameters.image_size`, e leia o formato de saída no campo `mime_type` da resposta.

## Perguntas frequentes

### Qual é o id de modelo da API Nano Banana Pro?

`gemini-3-pro-image`. A ficha Vertex do Google o lista como GA, com lançamento em 28 de maio de 2026, e o OmniaKey aceita o mesmo id. O id antigo `gemini-3-pro-image-preview` ainda funciona no OmniaKey e aponta para o mesmo modelo.

### Quanto custa uma imagem do Nano Banana Pro?

O Google estima $0.134 para uma imagem 1K ou 2K e $0.24 para uma 4K, na tarifa de $120 por milhão de tokens de imagem. Nossas tarefas reportaram 1,133, 1,225 e 2,480 tokens, o que dá $0.136, $0.147 e $0.298 nessa tarifa. A página do modelo no OmniaKey mostra a tarifa própria por chamada.

### O Nano Banana Pro desenha texto em chinês?

Sim. Nosso letreiro em 2K voltou com três linhas corretas em chinês — 同福客栈, 住宿 餐饮 茶水 e 010-6789 4321 — com os 11 dígitos e o hífen.

### Devo pedir 1K, 2K ou 4K?

Para um pôster como o nosso, 2K é o meio útil. Os três tamanhos escreveram o pôster corretamente, então 4K compra detalhe mais fino — vagões separados e juntas de tijolo — e não texto melhor. Use 1K para rascunhos em que 896x1200 basta.

### Por que minha edição voltou 400 invalid\_request?

As causas comuns são corpo acima de 1 MiB, origem no campo errado ou um modelo Gemini recebendo `size` ou um `mime_type` de primeiro nível. Coloque a imagem em `input.image` como `{data, mime_type}`, mantenha o corpo codificado abaixo de 1 MiB e use `aspect_ratio` e `image_size`.

## Fontes conferidas

- [Google Cloud: ficha do modelo Gemini 3 Pro Image](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image) — conferida em 3 nov 2026.
- [Google: guia de geração de imagens da API Gemini](https://ai.google.dev/gemini-api/docs/image-generation) — conferido em 3 nov 2026.
- [Google: preços da API Gemini](https://ai.google.dev/gemini-api/docs/pricing) — conferidos em 3 nov 2026.
- [Google: anúncio do Nano Banana Pro](https://blog.google/technology/ai/nano-banana-pro/) — conferido em 3 nov 2026.

## Histórico de atualizações

- 2026-11-03: primeira versão; cinco chamadas de teste feitas naquele dia pelo OmniaKey.