Os três valores necessários para qualquer integração
Quase todo guia sobre integração da api Nanobanana se resume a preencher os mesmos três campos em lugares diferentes. O serviço usa o protocolo de chat-completions da OpenAI, então uma ferramenta que permita substituir o endpoint da OpenAI pode conversar com ele.
| Campo | Valor |
|---|---|
| URL base | https://api.nanobananaapis.com/v1 |
| Chave de API | Sua chave, enviada como Authorization: Bearer <key> |
| ID do modelo | uncensored |
Uma nota sobre o escopo antes de começar. Este é um modelo de linguagem de texto, então não funcionará em locais que esperam geração de imagem, fala ou embeddings. Os métodos suportados são POST /v1/chat/completions e GET /v1/models. Se uma ferramenta pedir um modelo de embeddings para busca, direcione essa parte para outro provedor.
Você obtém uma chave na página de chaves de API. Contas novas podem reivindicar $0,50 de crédito de teste com um clique, sem cartão, válido por 7 dias.
Teste o endpoint antes de modificar qualquer ferramenta
Quando uma integração falha, as pessoas culpam a ferramenta. Na maioria das vezes, a chave ou a URL estão erradas. Um teste de curl de trinta segundos elimina essa dúvida. Primeiro, liste os modelos:
curl https://api.nanobananaapis.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
Depois, envie uma solicitação de chat curta:
curl https://api.nanobananaapis.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with the word ready."}],"max_tokens":10}'
Se ambos funcionarem, o endpoint e a chave estão corretos, e qualquer erro posterior vem da configuração de uma ferramenta. Se a primeira chamada retornar 401, a chave está errada ou falta a palavra Bearer no cabeçalho. Um 404 geralmente significa que a URL está faltando /v1 ou tem um caminho extra.
SillyTavern
O SillyTavern é uma interface para interpretação de papéis e bate-papo com personagens, e permite adicionar um endpoint compatível com OpenAI. Os rótulos do menu mudam entre versões, então trate os passos como um mapa e não como texto exato.
- Abra o painel de conexão de API e escolha Chat Completion como tipo de API.
- Selecione a fonte Custom (OpenAI-compatible).
- Cole
https://api.nanobananaapis.com/v1como URL do endpoint. - Cole sua chave no campo de chave.
- Insira
uncensoredcomo nome do modelo, ou pressione o botão de conexão e escolha-o na lista queGET /v1/modelsretorna. - Pressione conectar e envie uma mensagem de teste.
Duas notas de ajuste. O SillyTavern envia históricos longos com cartas de personagem, então monitore a janela de contexto de 100.000 tokens, que é compartilhada por prompt e resposta. E se você usar chats em grupo que disparam várias solicitações de uma vez, lembre-se do limite de 8 requisições simultâneas em uma chave completa (2 em uma chave de teste). Configurações de roleplay e companheiro são para adultos; o modelo não produzirá conteúdo sexual envolvendo menores de idade, independentemente do prompt.
LangChain
Em Python, o pacote langchain-openai fornece ChatOpenAI, que aceita uma base URL personalizada. Instale-o com pip install langchain-openai.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
model="uncensored",
temperature=0.7,
)
print(llm.invoke("Give me three names for a fictional smuggler ship.").content)
Chains, modelos de prompt e parsers de saída funcionam da mesma forma depois, já que eles só se importam com a interface de chat. A chamada de ferramentas segue o caminho padrão, então llm.bind_tools([...]) envia tools na solicitação. Teste uma única chamada de ferramenta antes de construir um agente em torno dela, e limite a paralelismo do agente a 8. Um gráfico que se ramifica em vinte ramos atingirá o erro concurrency.
O pacote JavaScript @langchain/openai usa a mesma ideia através de uma opção configuration: { baseURL } no ChatOpenAI.
Cursor e outros editores
O Cursor, como vários outros editores de código, tem uma área de configurações para modelos onde você pode fornecer sua própria chave de API OpenAI e substituir a base URL. Aproximadamente: abra as configurações do modelo, ative a opção de chave OpenAI personalizada, defina a base URL de substituição para https://api.nanobananaapis.com/v1, cole sua chave e adicione uncensored como um nome de modelo personalizado.
Seja realista sobre o que isso oferece. Editores constroem algumas funcionalidades, como conclusão inline, em torno de seus próprios backends e nomes de modelos específicos, então um endpoint personalizado pode se aplicar apenas ao chat ou a um subconjunto de comandos. As opções exatas mudam entre versões, então verifique a documentação atual do editor. Se um recurso exigir algo que esta API não oferece, como embeddings ou entrada de imagem, não funcionará através deste endpoint.
O mesmo padrão se aplica a outros clientes compatíveis com OpenAI, como Open WebUI, Continue e interfaces de chat semelhantes: encontre o campo para um endpoint OpenAI personalizado, insira os três valores e teste.
SDKs puros e variáveis de ambiente
Se você escreve seu próprio código, os SDKs oficiais leem variáveis de ambiente padrão, o que permite alternar endpoints sem tocar nos arquivos de origem. Nos SDKs Python e Node, definir OPENAI_BASE_URL e OPENAI_API_KEY é suficiente.
export OPENAI_BASE_URL="https://api.nanobananaapis.com/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
python app.py # app.py calls client.chat.completions.create(model="uncensored", ...)
Um cliente explícito no Node se parece com isto:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.nanobananaapis.com/v1",
apiKey: process.env.NANOBANANA_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Draft a short product description for a paper lantern." }],
stream: true,
});
for await (const part of stream) {
process.stdout.write(part.choices[0]?.delta?.content ?? "");
}
O streaming chega via SSE com o uso relatado no final. Os detalhes completos dos parâmetros estão na página de documentação, e o artigo sobre geração de prompts mostra como conectar uma etapa de texto a um pipeline de imagem.
Corrigindo as falhas comuns
| Sintoma | Causa provável | Correção |
|---|---|---|
| 401 Não Autorizado | Chave errada, ou cabeçalho faltando Bearer | Reescreva a chave e teste com curl |
| 404 Not Found | Base URL sem /v1, ou caminho duplicado | Use exatamente https://api.nanobananaapis.com/v1 |
| Modelo não encontrado | A ferramenta assume um nome de modelo do fornecedor | Defina o modelo para uncensored |
429 com rate_limited | Mais de 300 requisições por minuto (60 no teste) | Reduza a velocidade e tente novamente |
429 com concurrency | Mais de 8 solicitações de uma vez (2 no teste) | Reduza o paralelismo |
| 429 com Retry-After: 5 | Sobrecarga temporária | Aguarde cinco segundos e tente novamente |
| Requisição muito grande | Corpo acima de 8 MB | Corte anexos ou histórico |
Lembre-se de que uma requisição em streaming ocupa seu slot de concorrência até o fim do streaming, então um editor que abandona streams pode parecer estar atingindo o limite quando não está ocupado. Registre o cabeçalho X-Request-Id das chamadas com falha; é a primeira coisa que o suporte pedirá.
Em termos de custo, uma mensagem de chat típica com 2.000 tokens de entrada e 500 de saída custa $0,00055 a $0,15 e $0,50 por 1M de tokens, e requisições com falha não são cobradas. A página de preços cobre recargas de $20 a $500 e os níveis de bônus.
Chaves, segurança e quem vê o quê
Cada integração armazena sua chave em algum lugar, e algumas armazenam melhor que outras. Em uma interface desktop, a chave fica em um arquivo de configurações local. Em uma ferramenta baseada em navegador, ela pode ser salva no navegador. Em um editor, ela vive na configuração do aplicativo. Saiba qual você está usando antes de compartilhar a tela, confirmar um dotfile ou passar um laptop para outra pessoa.
Algumas regras mantêm isso gerenciável. Use uma chave por ferramenta onde possível, para que você possa substituir uma única sem quebrar o resto. Nunca cole uma chave em um rastreador de problemas público ao pedir ajuda; compartilhe o ID da requisição em vez disso. Se uma chave vaziar, substitua-a na página de chaves e atualize suas ferramentas. Os prompts enviados pela API não são usados para treinamento, e a página de privacidade descreve o restante do manuseio de dados.
Se você hospedar um front-end para outras pessoas, não envie sua chave para o navegador. Coloque um pequeno servidor entre seus usuários e a API, adicione seus próprios limites lá e mantenha a chave no servidor. Seus usuários então compartilham suas 8 requisições simultâneas, então planeje quantas pessoas podem conversar ao mesmo tempo.
Qual ferramenta se encaixa em qual trabalho
Como a integração é a mesma em todos os lugares, a escolha da ferramenta depende do que você está criando.
- SillyTavern ou um front-end de chat similar é adequado para chat de personagens, ficção e roleplay para adultos, onde você quer uma interface polida e cartões de personagem sem escrever código.
- LangChain é adequado para pipelines em código: carregadores, modelos de prompt, analisadores e cadeias de múltiplos passos. Ele adiciona estrutura ao custo de mais uma dependência.
- Uma chamada SDK direta é adequada para scripts pequenos e serviços. Se sua tarefa é um prompt de entrada e uma resposta de saída, o pacote OpenAI sozinho é menos para manter do que um framework.
- Um editor como o Cursor é adequado para chat sobre código. Verifique quais de seus recursos aceitam um endpoint personalizado antes de depender dele.
Comece com o teste curl básico, depois o SDK, e adicione um framework apenas quando sentir necessidade. Mudar mais tarde é fácil, pois os três valores nunca mudam. Para uma primeira requisição e a lista completa de parâmetros, leia a documentação.
