Leia isto primeiro: o que esta API é e não é
Se você chegou aqui se perguntando como usar a API nano banana para produzir imagens, a resposta honesta é que este serviço não faz essa parte. "Nano Banana" é um nome que as pessoas costumam atribuir a um modelo de geração de imagem, e a geração de imagens não é oferecida aqui. O que nanobananaapis.com vende é acesso a um modelo de linguagem de texto por meio de um endpoint compatível com OpenAI.
Isso ainda cabe em muitos fluxos de trabalho de imagens, porque as ferramentas de imagem são tão boas quanto o texto que você alimenta. Um modelo de texto pode escrever os prompts, variá-los, verificá-los contra uma folha de estilos, produzir legendas e texto alternativo, e rascunhar os scripts que unem um pipeline. Esta página mostra como usar isso. Se você só precisa de imagens, quer um serviço de imagem em vez disso, e você pode conectá-lo a este.
O modelo é um único modelo de pesos abertos, executado por um provedor independente, ajustado para responder sem recusas de conteúdo para uso adulto lícito. Não é a API oficial de nenhum grande fornecedor. A única limitação rígida: sem conteúdo sexual envolvendo menores de idade.
Passo 1: obter uma chave
Crie uma conta com o Google, ou com um e-mail e senha, então abra a página de chave de API. Você verá um botão de um clique para reivindicar $0.50 de crédito de teste. É válido por 7 dias, não precisa de cartão, e é limitado a um por pessoa. Uma chave de teste permite 2 requisições simultâneas e 60 requisições por minuto, o que é suficiente para experimentar.
Copie a chave e mantenha-a fora do seu repositório. Em um shell, você pode armazená-la assim:
export NANOBANANA_KEY="paste-your-key-here"
Passo 2: envie sua primeira requisição
Três valores importam: a URL base, o ID do modelo e o cabeçalho Authorization. Todo o resto segue o formato de chat-completions da OpenAI. Aqui está uma primeira chamada com curl:
curl https://api.nanobananaapis.com/v1/chat/completions -H "Authorization: Bearer $NANOBANANA_KEY" -H "Content-Type: application/json" -d '{
"model": "uncensored",
"messages": [
{"role": "user", "content": "Write one detailed image prompt for a foggy harbor at dawn."}
],
"max_tokens": 200
}'
A mesma coisa em Python com o pacote oficial openai:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
)
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write one detailed image prompt for a foggy harbor at dawn."}],
)
print(r.choices[0].message.content)
E em Node:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.nanobananaapis.com/v1",
apiKey: process.env.NANOBANANA_KEY,
});
const r = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Write one detailed image prompt for a foggy harbor at dawn." }],
});
console.log(r.choices[0].message.content);
Verifique os cabeçalhos de resposta uma vez. X-Balance-USD mostra seu crédito restante e X-Request-Id identifica a chamada se precisar de ajuda. A página de documentação lista todos os parâmetros suportados.
Passo 3: transformar ideias em prompts estruturados
A dica mais útil para um pipeline de imagem é fazer o modelo retornar dados estruturados em vez de texto livre. O modo JSON faz isso. Você descreve o esquema na mensagem do sistema, e a resposta é analisada diretamente no seu código, então uma lista de ideias vagas se torna uma tabela de prompts com campos fixos.
import json, os
from openai import OpenAI
client = OpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
)
SYSTEM = (
"You write prompts for an image model. Reply with JSON only: "
'{"prompts": [{"subject": str, "style": str, "lighting": str, "negative": str, "full": str}]}'
)
def expand(idea: str, n: int = 3):
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
temperature=0.9,
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": f"Give {n} distinct prompts for: {idea}"},
],
)
return json.loads(r.choices[0].message.content)["prompts"]
for p in expand("a lighthouse keeper's kitchen in winter"):
print(p["full"])
Aumente a temperatura quando quiser variedade e diminua-a para consistência. O parâmetro seed é passado adiante, então você pode fixá-lo quando precisar reproduzir um lote anterior. Sempre envolva json.loads em um bloco try e solicite novamente uma vez se a análise falhar, já que qualquer modelo de linguagem pode cometer um erro.
O site também tem um guia relacionado sobre o lado das imagens: geração de prompt e pós-processamento. Ele cobre como o passo de texto se conecta a um gerador.
Mais tarefas que um modelo de texto executa bem em um fluxo de trabalho de imagem
- Folhas de estilo. Mantenha uma única mensagem do sistema com suas regras de estilo fixas e alimente cada novo assunto por ela, para que toda uma série permaneça visualmente consistente.
- Legendas e texto alternativo. Depois de gerar as imagens, descreva-as em algumas palavras cada. Passe sua própria descrição da imagem como entrada; o modelo não vê imagens, porque a API recebe apenas texto.
- Listas de tomadas e scripts. Para um storyboard ou um vídeo curto, rascunhe a lista de cenas, a narração e os marcos na tela como texto.
- Crítica de prompts. Cole um prompt que dá resultados ruins e peça três reescritas com as alterações explicadas.
- Ficção e trabalho de personagens para adultos. Folhas de personagem, histórias de fundo e diálogos para histórias e aplicativos de companhia, com o modelo não recusando temas adultos lícitos.
Para tarefas longas, faça streaming da saída com stream: true para que uma interface de usuário possa mostrar o texto conforme ele chega. A chamada de funções também é suportada, o que permite que um modelo decida quando chamar sua própria função, por exemplo, uma que envia um prompt para o serviço de imagem que você usa.
Limites e custo de uma execução
Saiba os números antes de construir um lote. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. A janela de contexto é de 100.000 tokens cobrindo prompt e conclusão, o corpo máximo da requisição é de 8 MB, e max_tokens é opcional. Ultrapassar a taxa retorna HTTP 429 com o código rate_limited ou concurrency; aguarde e tente novamente.
O preço é $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída. Digamos que você gere 500 conjuntos de prompts, cada um com uma entrada de 400 tokens e uma saída de 600 tokens:
- Entrada: 500 x 400 = 200.000 tokens x $0,15 / 1M = $0,03
- Saída: 500 x 600 = 300.000 tokens x $0,50 / 1M = $0,15
- Total: $0,18
Então o crédito de teste de $0.50 cobre aproximadamente 1.300 conjuntos desse tamanho. Para uso regular, recarregue qualquer valor inteiro de $20 a $500, por cripto (USDT em TRC20, USDC em Base). Bônus são 5% a partir de $50, 10% a partir de $100 e 15% a partir de $200. Veja a página de preços para a tabela. O crédito não expira.
Emparelhamento com um serviço de imagem
A configuração usual tem duas etapas. A etapa de texto usa esta API para produzir prompts. A etapa de imagem envia esses prompts para qualquer gerador de imagem que você use, e esse gerador tem sua própria conta, seu próprio preço e suas próprias regras, que você deve ler em seu site. Mantenha as duas etapas em funções separadas, para que você possa alterar qualquer lado sem reescrever o outro.
Uma dica prática: salve cada prompt junto com a semente e a temperatura que você usou para criá-lo. Quando uma imagem ficar boa, você pode rastreá-la de volta ao texto exato que a produziu, e quando um lote decepcionar, você pode ver se a falha estava na ideia, no escritor de prompts ou no modelo de imagem. Isso também oferece uma maneira barata de comparar duas mensagens do sistema executando ambas na mesma lista de ideias e julgando os dois conjuntos de prompts lado a lado.
Um pequeno script de ponta a ponta
Para conectar as peças, aqui está um script curto que lê um arquivo de ideias vagas, expande cada uma em prompts com o modo JSON e grava o resultado em um arquivo que sua ferramenta de imagem pode ler. Ele lida com um modo de falha que, caso contrário, o prejudicará: a resposta que não é JSON válido.
import json, os
from openai import OpenAI
client = OpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
)
def one(idea: str):
for _ in range(2):
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": 'Reply with JSON only: {"prompt": str}'},
{"role": "user", "content": f"Write a vivid, specific image prompt for: {idea}"},
],
max_tokens=250,
)
try:
return json.loads(r.choices[0].message.content)["prompt"]
except (json.JSONDecodeError, KeyError):
continue
return None
ideas = [line.strip() for line in open("ideas.txt") if line.strip()]
out = {i: one(i) for i in ideas}
json.dump(out, open("prompts.json", "w"), indent=2)
Execute-o em cinco ideias primeiro e leia os resultados a olho nu. Ajuste a mensagem do sistema até que os prompts correspondam ao estilo que você deseja, depois escale. Como cada solicitação aqui é pequena, mil ideias terminam rapidamente e custam centavos.
Erros comuns de iniciantes
- Esperando imagens. A resposta é sempre texto. Se o seu código tenta salvar uma imagem binária da resposta, falhará, porque não há nenhuma.
- Procurando um nome de modelo diferente. Há um modelo, e seu ID é
uncensored. Copiar o nome de um modelo de fornecedor de um tutorial dá um erro de não encontrado. - Esquecendo a mensagem do sistema. Sem ela, o modelo não tem orientação de estilo e deriva entre prompts curtos e longos. Coloque suas regras lá.
- Enviando segredos em prompts. Os prompts não são usados para treinamento, mas você ainda deve evitar colar senhas ou chaves privadas em qualquer entrada de modelo.
- Executando cem requisições de uma vez. Uma chave completa permite 8 de cada vez. Use um pool ou um semáforo, e adicione uma nova tentativa para 429.
Se algo se comportar de forma estranha, a página de suporte é o lugar para perguntar, e o ID da solicitação nos cabeçalhos da resposta torna a pergunta muito mais fácil de responder.
