API do Nano Banana — use o OpenAI SDK como está, preço por imagem e como chamar

Ao pesquisar a API do Nano Banana em coreano, os resultados se dividem em dois — a documentação oficial do Google ou um artigo sobre “como obter uma chave no AI Studio”. O que falta está entre esses dois. Este artigo reúne o caminho para fazer chamadas mantendo o SDK existente da OpenAI e os preços por imagem de toda a família em uma única tabela. Não é necessário ter um projeto do Google Cloud.

Preço por imagem — toda a família

As tarifas abaixo são lidas do catálogo de modelos, não inseridas manualmente no artigo. Quando os preços mudarem, esta tabela também mudará.

Tudo é baseado em per image e é descontado do saldo pré-pago, não de uma assinatura. Não há cobrança nos meses sem geração.

Chamada — altere apenas base_url e o nome do modelo

Se você já usa o SDK da OpenAI, não há nada novo para aprender. Basta alterar dois pontos na inicialização do cliente: base_url e o nome do modelo.

# 기존 OpenAI SDK를 그대로 씁니다. base_url과 모델 이름만 바뀝니다.
# Google Cloud 프로젝트도, 별도 SDK 설치도 필요 없습니다.
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

img = client.images.generate(
    model="nano-banana-2",
    prompt="한옥 마당에 눈이 내리는 장면, 따뜻한 조명, 사진 스타일",
    n=1,
)
print(img.data[0].url)

O endpoint é POST /v1/images/generations, no mesmo formato do endpoint de imagens da OpenAI. Portanto, se o código já tiver geração de imagens integrada, a troca é feita alterando uma única string do nome do modelo.

Verifique primeiro se a chave funciona

Antes de alterar o código, confirme a chave e o endereço com uma única solicitação. Assim, se ocorrer um erro depois, será possível restringir a causa ao código.

# 키가 되는지 30초 만에 확인하는 최소 요청
curl -sS https://api.kunavo.com/v1/images/generations \
  -H "Authorization: Bearer sk-kn-..." \
  -H "content-type: application/json" \
  -d '{"model":"nano-banana","prompt":"a paper crane on a desk","n":1}'

401 significa um problema de autenticação, 429 significa limitação de taxa e 529 significa sobrecarga do upstream. A tabela de decisão de Resumo dos erros do Claude Code se aplica da mesma forma para distinguir esses casos.

Qual nível usar como padrão

A melhor relação custo-benefício é deixar o modelo básico como padrão e subir para o Pro apenas quando o resultado for insuficiente. Como basta alterar uma string do nome do modelo, aproveite o fato de que o custo dos testes comparativos é praticamente zero — execute o mesmo prompt uma vez em cada nível e decida.

Os preços de vídeo estão em preços do Veo 3; a documentação detalhada em inglês está em API do Nano Banana. Métodos de pagamento e cadastro de cartões domésticos estão em preços e pagamentos da API do Claude.

Perguntas frequentes