Como usar a API do Gemini 4 Neon: ID do modelo, níveis de raciocínio e primeira chamada verificada
Chame o gemini-4-neon a partir de um projeto pago da Gemini API, escolha entre high e xhigh, leia o uso de tokens de raciocínio e de cache e corrija os erros que mudam em relação ao Carbon.
Para chamar o Gemini 4 Neon, envie model: "gemini-4-neon" a partir de um projeto da Gemini API no nível pago; o Neon não tem nível gratuito. Por padrão, ele raciocina em high, também aceita low, medium e xhigh, e entrada, raciocínio e saída compartilham uma única janela de 1.048.576 tokens. Para código novo, o guia do Google para o Neon parte da Interactions API, mas generateContent também funciona. Uma requisição só pode ser considerada bem-sucedida quando a interaction está completed (ou o candidate parou com STOP), há texto visível e o registro de uso mostra o que será cobrado, incluindo os tokens de raciocínio.
O Google lançou o gemini-4-neon em disponibilidade geral (GA) em 18 de novembro de 2026. Este guia foi conferido com a documentação do Google em 19 de novembro de 2026. O foco está no que é específico do Neon. Configuração de projeto, chaves de API e cobrança são iguais às do outro modelo pago do Gemini 4, por isso aparecem em detalhe uma única vez no nosso guia de configuração da API do Gemini 4 Carbon e aqui aparecem apenas resumidas.
Este artigo tem dois limites:
- O Neon não está disponível na Ofox. Verificamos a lista de modelos da Ofox (
GET https://api.ofox.ai/v1/models) em 19 de novembro de 2026: ela trazgoogle/gemini-4-hydrogenegoogle/gemini-4-argon, mas não o Neon, ehttps://ofox.ai/models/google/gemini-4-neonretornou 404. Todos os exemplos abaixo usam o endpoint nativo do Google e uma chave de API do Google. A Ofox publica este blog. - Não fizemos uma chamada real ao Neon. Não tínhamos uma chave do Google para este guia. Os corpos das requisições foram conferidos com a especificação publicada pelo Google (guia do Neon, referências da Interactions e do
generateContent, documentação de raciocínio, cache e geração longa). O verificador de respostas foi testado offline com 15 respostas sintéticas. Isso comprova a lógica do parser. Não comprova autenticação, latência nem qualidade das respostas.
Gemini 4 Neon API: dados principais
Todos os valores abaixo vêm do guia What’s new in Gemini 4 Neon, da página de preços e do model card do Neon do Google (todos em inglês), conferidos em 19 de novembro de 2026.
| Item | Valor no Neon |
|---|---|
| ID do modelo | gemini-4-neon (sem o sufixo -preview) |
| Acesso | Apenas nível pago da Gemini API; também no Google AI Studio com os planos Google AI Pro e Ultra |
| APIs | Interactions API (usada no quickstart do Google) e generateContent |
| Níveis de raciocínio | low, medium, high (padrão), xhigh; minimal é rejeitado |
| Contexto | 1.048.576 tokens compartilhados entre entrada, raciocínio e saída |
| Saída síncrona | 65.536 tokens como padrão e limite por hop (etapa de geração), com ou sem streaming |
| Saída mais longa | Execução em segundo plano ou continuação no cliente, até 1M menos a entrada |
| Preço padrão (USD por 1M tokens) | Entrada $ 3,00, entrada em cache $ 0,15, saída com raciocínio $ 15,00 |
| Cache | Apenas implícito, a partir de 4.096 tokens de prompt; cachedContents explícito não é suportado |
| Amostragem | temperature, top_p e top_k são ignorados dentro do intervalo válido; fora dele, retornam 400 |
| Data de corte do conhecimento | Março de 2026 (model card) |
O Neon não tem preço promocional de lançamento, ao contrário do Carbon, cuja tarifa promocional termina em 30 de novembro. Para o custo por tarefa em cada nível de raciocínio, veja nossa análise de preços do Gemini 4 Neon.
O que muda em relação a uma requisição do Carbon ou do Hydrogen
O Google afirma que trocar outro modelo do Gemini 4 pelo Neon “não exige mudanças no schema da requisição”. Os campos continuam os mesmos; o que muda são os valores e os limites em torno deles. Se você já tem código funcionando a partir dos nossos guias de configuração do Carbon ou do Hydrogen, estas são as diferenças a considerar.
| Área | Carbon | Hydrogen | Neon |
|---|---|---|---|
| ID do modelo | gemini-4-carbon | gemini-4-hydrogen | gemini-4-neon |
| Nível gratuito | Não | Sim | Não |
| Raciocínio padrão | medium | high | high |
xhigh | Não suportado | Suportado | Suportado |
| Hop sem streaming | 32.768 tokens por hop em REST bruto | 65.536 | 65.536 |
| Parâmetros de amostragem | Ignorados | Ignorados dentro do intervalo, 400 fora dele | Ignorados dentro do intervalo, 400 fora dele |
| Preço padrão (entrada / saída) | $ 2 / $ 10 até 30 de nov., depois $ 4 / $ 20 | $ 1,50 / $ 7,50 | $ 3 / $ 15, fixo |
Fontes: os guias “What’s new” do Carbon, do Hydrogen e do Neon e a página Choosing a model (em inglês). A comparação entre hops de 32.768 e 65.536 tokens está no guia do Google para o Hydrogen.
Daí vêm três consequências práticas:
- Migrar do Carbon aumenta o gasto padrão por chamada. O Carbon usa
mediumpor padrão; o Neon usahigh. Código que nunca definiuthinking_levelvai raciocinar mais no Neon sem nenhuma mudança da sua parte. Defina o nível explicitamente para que esse comportamento fique visível no code review. - Migrar do Hydrogen pode falhar por causa da chave, não da requisição. Uma integração com o Hydrogen pode rodar em um projeto do nível gratuito. A mesma chave não chega ao Neon. Verifique a qual projeto a chave pertence antes de depurar o payload.
- Código escrito para o Neon pode falhar no Carbon.
xhighé válido para o Neon e o Hydrogen, mas não para o Carbon nem para o Argon. Se você distribui etapas entre modelos, faça do nível de raciocínio parte da rota, não uma constante global. Nossa comparação entre Neon e Carbon mostra quando cada modelo vale o que custa.
Passo 1: confirme que a chave pertence a um projeto pago
O Neon exige quatro coisas alinhadas: uma conta Google com permissão para usar a Gemini API, um projeto no Google AI Studio, uma chave de API que pertença a esse projeto e cobrança ativa no nível pago para o mesmo projeto. O guia de cobrança do Google descreve a passagem do nível gratuito para o pago como a vinculação de uma conta de faturamento ao projeto, e a página Projects mostra o nível de cobrança de cada projeto. Um plano Google AI Pro ou Ultra dá acesso ao Neon no AI Studio, mas não o trate como prova de que o projeto da sua chave de API está no nível pago. Confira o nível do projeto nessa página.
A versão passo a passo (importar um projeto do Cloud, tipos e restrições de chave, pré-pago e pós-pago) está na primeira seção do guia de configuração do Carbon e vale para o Neon sem alterações. As fontes do Google são o guia de chaves de API e o guia de cobrança (ambos em inglês).
Guarde a chave em uma variável de ambiente e confira se ela foi carregada sem imprimi-la:
export GEMINI_API_KEY="..." # defina no shell ou no gerenciador de segredos; nunca faça commit
python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'
True só indica que existe um valor. Quem comprova que o projeto alcança o Neon é a primeira requisição.
Passo 2: envie a primeira requisição com a Interactions API
O quickstart do Google para o Neon usa a Interactions API, então comece por ela em código novo. Instale o SDK atual (google-genai, importado como from google import genai; não o pacote antigo google-generativeai):
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade google-genai
Salve como neon_first_call.py:
import json
import os
from pathlib import Path
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
interaction = client.interactions.create(
model="gemini-4-neon",
input="List exactly three checks for confirming a new API integration works.",
store=False,
generation_config={
"thinking_level": "low",
"max_output_tokens": 65536,
},
)
Path("neon-response.json").write_text(
json.dumps(interaction.model_dump(mode="json"), indent=2), encoding="utf-8"
)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
print(interaction.output_text)
Três escolhas nessa requisição são intencionais:
thinking_level: "low"mantém barata a verificação de acesso. Sem isso, o Neon raciocinaria emhigh. Uselowpara provar a rota e depois defina o nível que a sua carga de trabalho real precisa (passo 5).max_output_tokens: 65536é o padrão documentado do Neon e o limite por hop. É um teto para raciocínio mais saída visível, não uma previsão da conta. O Google recomenda não herdar limites baixos, como 8.192, de aplicações antigas; para gastar menos, reduza o nível de raciocínio.store=Falsetira essa chamada única do armazenamento. Deixe o armazenamento ligado (o padrão) se for usarbackground=Trueouprevious_interaction_id; os dois dependem de interactions armazenadas. No nível pago, o Google guarda interactions armazenadas por 55 dias.
A mesma requisição em REST, útil para ver exatamente o que trafega:
curl --silent --show-error --max-time 900 \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-neon",
"input": "List exactly three checks for confirming a new API integration works.",
"store": false,
"generation_config": {
"thinking_level": "low",
"max_output_tokens": 65536
}
}' \
--output neon-response.json
Na Interactions API, os nomes de campo dentro de generation_config são snake_case em Python, JavaScript e REST. output_text é uma propriedade de conveniência do SDK; na resposta REST bruta, o texto fica nos itens de steps do tipo model_output, dentro das entradas de content do tipo text.
O --max-time de 900 segundos segue a orientação de migração do Google de reservar pelo menos 15 minutos para prompts difíceis. Um prompt trivial em low deve voltar bem antes disso. Se o cliente estourar o tempo, o servidor ainda pode ter processado (e cobrado) a requisição, então não dispare uma nova tentativa automática antes de verificar.
Passo 3: ou use generateContent se o seu cliente já usa
O generateContent continua suportado no Neon. Se a sua aplicação já interpreta candidates, talvez baste trocar o nome do modelo e a configuração de raciocínio. Atenção à diferença de grafia: o REST do generateContent usa camelCase.
curl --silent --show-error --max-time 900 \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-4-neon:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "List exactly three checks for confirming a new API integration works."}]}],
"generationConfig": {
"thinkingConfig": {"thinkingLevel": "low"},
"maxOutputTokens": 65536
}
}' \
--output neon-response.json
No SDK de Python, fica assim:
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-neon",
contents="List exactly three checks for confirming a new API integration works.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level="low"),
max_output_tokens=65536,
),
)
print(response.text)
print("Thinking tokens:", response.usage_metadata.thoughts_token_count)
Nas duas formas, os valores de nível são strings em minúsculas ("low", "xhigh"), como no guia de raciocínio do Google (em inglês). Não misture as duas APIs: generation_config.thinking_level vai no corpo da Interactions e generationConfig.thinkingConfig.thinkingLevel no corpo do generateContent. Se aparecer um 400 depois de copiar código de uma API para a outra, confira primeiro a estrutura dos campos. Remova também qualquer thinkingBudget (thinking_budget) antigo: ele está obsoleto no Gemini 4, e enviá-lo junto com um nível de raciocínio retorna 400.
Escolha uma API por caminho de código. A Interactions API oferece estado no servidor (previous_interaction_id) e execução em segundo plano. Com o generateContent, você mesmo gerencia o histórico e precisa reenviar os turnos anteriores do modelo sem alterações, incluindo as assinaturas de raciocínio (thought signatures).
Passo 4: confira status, texto e uso antes de confiar na chamada
Um HTTP 200 não basta. Uma interaction pode voltar com status diferente de completed, e um candidate do generateContent pode terminar com MAX_TOKENS depois de gastar todo o orçamento em raciocínio. Nos dois casos, pode não haver nenhum texto visível. O guia de geração longa do Google (em inglês) indica a ação para cada status da Interactions:
| Status | O que significa | O que fazer |
|---|---|---|
queued, in_progress | Ainda em execução (chamadas em segundo plano) | Consulte interactions.get com o mesmo id |
completed | Concluída | Junte o texto de model_output e leia usage |
requires_action | O modelo pediu uma chamada de ferramenta | Execute a ferramenta e envie o resultado com este id |
requires_continuation | Um hop em primeiro plano atingiu o limite de 65.536 e ainda resta orçamento | O SDK continua por padrão; em REST, envie o próximo hop com previous_interaction_id e continuation_token |
incomplete | Todo o max_output_tokens foi usado; o texto pode estar vazio | Retome ou reenvie com um max_output_tokens maior |
failed | O servidor não conseguiu concluir | Tente de novo uma vez; se falhar outra vez, guarde o id para o suporte |
cancelled | Você cancelou | Leia usage para ver o que foi cobrado |
No generateContent, os equivalentes são os valores de finishReason: STOP indica sucesso, MAX_TOKENS indica que o limite foi atingido e CONTINUATION indica que é preciso mais um hop (os SDKs mais recentes continuam automaticamente).
Este verificador lê uma resposta salva de qualquer uma das duas APIs. Ele não faz chamadas de rede e nunca tenta de novo:
import json
import sys
from pathlib import Path
PENDING = {"queued", "in_progress"}
def check_interaction(p):
status = p.get("status")
if status in PENDING:
raise ValueError(f"Still {status}: poll interactions.get with this id later")
if status != "completed":
raise ValueError(f"Interaction status is {status}, not completed (see the status table)")
text = "".join(
c.get("text", "")
for s in p.get("steps", [])
if s.get("type") == "model_output"
for c in s.get("content", [])
if c.get("type") == "text"
)
u = p.get("usage") or {}
usage = {
"input": u.get("total_input_tokens"),
"cached_input": u.get("total_cached_tokens"),
"output": u.get("total_output_tokens"),
"thinking": u.get("total_thought_tokens"),
"tool_use": u.get("total_tool_use_tokens"),
"total": u.get("total_tokens"),
}
return text, usage
def check_generate_content(p):
cands = p.get("candidates") or []
if not cands:
reason = (p.get("promptFeedback") or {}).get("blockReason")
raise ValueError(f"No candidates (prompt block reason: {reason})")
c = cands[0]
reason = c.get("finishReason")
if reason != "STOP":
raise ValueError(f"finishReason is {reason}, not STOP")
text = "".join(
part.get("text", "")
for part in (c.get("content") or {}).get("parts", [])
if not part.get("thought")
)
u = p.get("usageMetadata") or {}
usage = {
"input": u.get("promptTokenCount"),
"cached_input": u.get("cachedContentTokenCount", 0),
"output": u.get("candidatesTokenCount"),
"thinking": u.get("thoughtsTokenCount"),
"tool_use": u.get("toolUsePromptTokenCount", 0),
"total": u.get("totalTokenCount"),
}
return text, usage
def check(payload):
if "error" in payload:
raise ValueError("API error: " + json.dumps(payload["error"]))
if "candidates" in payload or "promptFeedback" in payload:
text, usage = check_generate_content(payload)
elif "status" in payload or "steps" in payload:
text, usage = check_interaction(payload)
else:
raise ValueError("Unrecognised response shape")
if not text.strip():
raise ValueError("Completed, but no visible text")
return text, usage
if __name__ == "__main__":
path = sys.argv[1] if len(sys.argv) > 1 else "neon-response.json"
payload = json.loads(Path(path).read_text(encoding="utf-8"))
try:
text, usage = check(payload)
except ValueError as exc:
raise SystemExit(str(exc))
print("Usage:", json.dumps(usage))
print(text)
Execute python3 check_neon.py neon-response.json. Se passar, ele imprime uma linha de uso normalizada e a resposta visível. Depois leia a resposta em si: três verificações pertinentes, não uma recusa nem uma frase cortada.
O que testamos. Rodamos o verificador exatamente como está acima com 15 fixtures escritas à mão: uma interaction concluída com o texto dividido em dois steps model_output e um step de raciocínio; a mesma interaction depois de passar pelo modelo Interaction do SDK google-genai e por model_dump(mode="json"), como o passo 2 a salva; interactions in_progress, incomplete, requires_action, requires_continuation, failed e concluída porém vazia; um corpo de erro da API; e respostas do generateContent terminando em STOP (com uma parte de raciocínio a ser excluída), MAX_TOKENS, CONTINUATION e MALFORMED_FUNCTION_CALL, além de um prompt bloqueado e uma resposta só com raciocínio. Os três sucessos bem formados passaram e os outros doze terminaram com a mensagem esperada. As fixtures seguem os nomes de campo documentados; não são saídas capturadas do Neon.
Quais campos de uso importam no Neon
É no registro de uso que aparecem as duas alavancas de custo do Neon: raciocínio e acertos de cache.
| Significado | Interactions usage | generateContent usageMetadata |
|---|---|---|
| Tokens de entrada | total_input_tokens | promptTokenCount |
| Entrada com acerto de cache | total_cached_tokens | cachedContentTokenCount |
| Saída visível | total_output_tokens | candidatesTokenCount |
| Raciocínio | total_thought_tokens | thoughtsTokenCount |
| Tokens de prompt de uso de ferramentas | total_tool_use_tokens | toolUsePromptTokenCount |
| Total | total_tokens | totalTokenCount |
Os nomes de campo vêm das referências de API do Google para Interactions e generateContent (ambas em inglês). O exemplo da referência do Google (de um modelo anterior, não do Neon) mostra o raciocínio informado separadamente da saída visível: 49 tokens de raciocínio ao lado de 23 tokens de saída para uma resposta de uma frase. No Neon, o raciocínio é cobrado pela tarifa de saída de $ 15,00. O Google conta cada token que o modelo processa, incluindo o raciocínio e, com grounding, instruções internas de sistema e declarações de funções. Por isso, uma resposta visível curta ainda pode gerar uma cobrança de saída alta em high ou xhigh. Registre thinking ao lado de output em toda chamada; quando uma conta parecer errada, esse par é a primeira coisa a olhar.
Passo 5: escolha o nível de raciocínio por tarefa
O guia do Google descreve os quatro níveis mais ou menos assim (em paráfrase):
| Nível | Descrição do Google | Uso típico |
|---|---|---|
low | Menos tokens, menor latência | Chat rápido, processamento de alto volume, verificações de acesso baratas |
medium | Menor uso de tokens, respostas mais rápidas | Programação interativa, prototipagem de UI, chamadas de ferramenta sensíveis à latência |
high (padrão) | Equilíbrio entre inteligência e velocidade | A maior parte da programação complexa, execução agêntica, trabalho de conhecimento multimodal |
xhigh | Mais tokens, raciocínio mais profundo | Engenharia difícil em várias etapas, problemas analíticos e científicos em que high não basta |
O método recomendado pelo Google: avalie a sua tarefa nos quatro níveis com um max_output_tokens alto, para que o limite não corte as respostas, e depois use o nível mais baixo que atenda ao seu padrão de qualidade. Para pedir xhigh:
interaction = client.interactions.create(
model="gemini-4-neon",
input="Audit this retry queue for race conditions and rewrite the lock logic.",
generation_config={"thinking_level": "xhigh"},
)
Dois cuidados específicos do Neon:
xhighe o limite de 65.536 interagem. O limite cobre raciocínio mais saída. O guia de raciocínio do Google alerta quexhighpode raciocinar demais e esgotar omax_output_tokensem prompts simples, como extração de texto ou de JSON. Se aparecerMAX_TOKENSou uma interactionincompletecom pouco texto visível, olhe primeiro para a tarefa. Se for simples, reduza o nível. Se for realmente difícil, mantenha o nível e dê mais espaço com execução em segundo plano e ummax_output_tokensmaior (veja a seção de execução em segundo plano abaixo). Não reduza omax_output_tokenspara economizar: segundo o Google, isso corta a resposta, e o raciocínio já feito continua sendo cobrado.- As afirmações de custo do Google foram medidas em níveis específicos. O anúncio do Neon pelo Google diz que, no nível padrão
high, o Neon combina uma pontuação alta no Artificial Analysis Intelligence Index com um custo por tarefa 32% menor que o do Carbon, e que a maior pontuação de inteligência do Neon é emxhigh. O Google associa os 32% ao AA Intelligence Index, mas não informa com qual nível de raciocínio do Carbon, com qual período de preço do Carbon nem com qual retrato dos dados da AA comparou; os números da AA que lemos em 19 de novembro de 2026 não reproduzem os 32%, e a comparação está no nosso guia de preços do Neon. São resultados de benchmark divulgados pelo Google, não uma previsão para a sua carga de trabalho. Meça a sua própria tarefa com os campos de uso acima.
O previous_interaction_id carrega apenas o histórico da conversa. Ele não carrega generation_config, tools nem system_instruction, então um turno seguinte sem thinking_level volta ao padrão do Neon, high. Reenvie o nível em cada turno.
Use cache implícito em vez de cachedContents
O Neon só suporta cache implícito. Se você estiver migrando código que cria caches com caches.create ou envia cached_content, remova esses campos. O guia de cache do Google diz que o cache explícito não é suportado na Interactions API nem para os modelos do Gemini 4.
O cache implícito é aplicado automaticamente em prompts de pelo menos 4.096 tokens. Um acerto é cobrado a $ 0,15 por 1M tokens de entrada em vez de $ 3,00, um desconto de 95%. Não dá para forçar um acerto, mas o guia de cache do Google (em inglês) aponta duas formas de aumentar as chances:
- Coloque o conteúdo grande e compartilhado (instruções de sistema, um mapa do repositório, um documento de referência) no início do prompt e a pergunta de cada requisição no final.
- Envie requisições com o mesmo prefixo próximas no tempo.
Para chats com vários turnos e loops de agentes, o Google acrescenta uma regra do Gemini 4: a requisição anterior inteira só entra no cache se a nova requisição acrescentar pelo menos 2.050 tokens (saída do modelo, raciocínio e resultados de funções contam). Acréscimos menores fazem os últimos 2.050 tokens da requisição anterior serem reprocessados pela tarifa padrão de entrada. Segundo o Google, a maioria dos turnos de agentes passa desse limite.
Depois, confirme com dados em vez de suposições: total_cached_tokens (Interactions) ou cachedContentTokenCount (generateContent) deve ser diferente de zero na segunda requisição e nas seguintes que compartilham um prefixo longo. Se continuar em 0, verifique se o prefixo é idêntico byte a byte, incluindo timestamps ou IDs de requisição que você talvez esteja inserindo no início.
Saídas maiores que 64K: execução em segundo plano
Uma única resposta síncrona do Neon para em 65.536 tokens de raciocínio mais saída. Para uma especificação longa, um plano grande de refatoração ou uma suíte de testes completa, o Google recomenda a execução em segundo plano:
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-neon",
input="Write a complete migration specification and test plan for this service.",
background=True,
generation_config={"max_output_tokens": 262144, "thinking_level": "high"},
)
while interaction.status in ("queued", "in_progress"):
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
# Junta o texto de todos os hops de continuação de 64K.
text = "".join(
content.text
for step in interaction.steps
if step.type == "model_output"
for content in step.content
if content.type == "text"
)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
print(text)
O texto chega em vários steps model_output porque o servidor continua em hops de 64K, então junte todos eles (o verificador acima faz o mesmo). Uma interaction em segundo plano pode rodar por até 24 horas; se terminar em failed, tente de novo uma vez, como na tabela de status. Há mais dois detalhes fáceis de perder. Se você definir background sem max_output_tokens, o servidor ainda para depois de 65.536 tokens. E a execução em segundo plano exige armazenamento, então não a combine com store=False. O teto é 1.048.576 menos os seus tokens de entrada. O guia de geração longa do Google (em inglês) explica a continuação no cliente para quem não pode armazenar interactions.
Erros comuns da API do Gemini 4 Neon e como corrigir
Registre o endpoint, o ID exato do modelo, o projeto, a versão do SDK e o corpo completo do erro (sem a chave) antes de mudar qualquer coisa. Corrija primeiro a camada que falhou antes das outras na cadeia.
| Sintoma | Causa provável no Neon | Correção |
|---|---|---|
| Erro de acesso ou de cota com uma chave que funciona no Hydrogen | A chave pertence a um projeto do nível gratuito; o Neon é só do nível pago | Use uma chave de um projeto com cobrança paga ativa (passo 1) |
| Modelo não encontrado | Erro de digitação, sufixo inventado como -preview ou um gateway que não roteia o Neon | Use gemini-4-neon em generativelanguage.googleapis.com |
400 em thinking_level | minimal enviado (rejeitado no Gemini 4), estruturas de campo da Interactions e do generateContent misturadas, ou um thinkingBudget antigo enviado junto com o nível | Use low/medium/high/xhigh; ajuste os nomes de campo ao endpoint; remova thinkingBudget |
| Erro de validação 400 com parâmetros de amostragem | temperature, top_p ou top_k fora do intervalo | Remova os parâmetros de amostragem; valores dentro do intervalo são ignorados de qualquer forma |
| Requisição falha depois de migrar código de cache | Referência antiga a cached_content / cachedContents (cache explícito não suportado) | Remova; conte com o cache implícito |
MAX_TOKENS, incomplete ou texto vazio | max_output_tokens baixo consumido pelo raciocínio | Volte para 65.536, use execução em segundo plano para trabalhos longos ou reduza o raciocínio de forma deliberada |
MALFORMED_FUNCTION_CALL | O modelo foi instruído a emitir chamadas de ferramenta em JSON como texto puro sem ferramentas declaradas | Declare as ferramentas com function calling ou use saída estruturada |
| Erros de assinatura no uso de ferramentas em vários turnos | Assinaturas de raciocínio descartadas ou copiadas entre chamadas paralelas | Use previous_interaction_id ou devolva os turnos anteriores sem alterações; veja nossa correção para thought signature ausente (em inglês) |
| Timeout do cliente em prompts difíceis | O raciocínio em high/xhigh leva minutos | Aumente o timeout HTTP para pelo menos 15 minutos ou use execução em segundo plano |
| 429 | Os limites de taxa continuam valendo no nível pago | Reduza a concorrência e faça backoff; veja nosso guia de novas tentativas após 429 (em inglês) |
A maioria das linhas vem diretamente do checklist de migração do Neon do Google. Para diagnósticos completos de rota, cota e resposta em um modelo da mesma família, veja nosso passo a passo de erros da API do Gemini 4 Argon; os valores específicos do Argon que aparecem lá (raciocínio padrão, níveis) não se aplicam ao Neon. Os erros do Carbon, Neon e Hydrogen, incluindo respostas vazias ou cortadas, estão reunidos no nosso guia de erros do Gemini 4 Carbon, Neon e Hydrogen.
Dá para chamar o Gemini 4 Neon pela Ofox?
Não, em 19 de novembro de 2026. A lista de modelos da Ofox retornou o Gemini 4 Hydrogen e o Argon, mas não o Neon, e o caminho da página do modelo Neon retornou 404. Não aponte o código acima para uma URL base da Ofox: o endpoint da Interactions e uma chave da Ofox são sistemas diferentes, e não existe rota para o Neon.
Para conferir de novo mais tarde, procure google/gemini-4-neon na lista de modelos da Ofox (GET https://api.ofox.ai/v1/models com a sua chave da Ofox) ou em ofox.ai/models. Se ele aparecer, a página do modelo informa os protocolos suportados e o preço atual. O formato de requisição para modelos Gemini na Ofox está na documentação da Gemini API da Ofox. Use essa documentação para endpoint e autenticação; não presuma que o código nativo do Google deste artigo funcione sem alterações.
Se você precisa de um modelo do Gemini 4 pela Ofox hoje, o Gemini 4 Hydrogen está na lista e o guia de configuração cobre a rota pela Ofox. Para ver como o Neon se sai diante dos carros-chefe concorrentes com que o Google o compara, leia Gemini 4 Neon vs Claude Opus 5.5 vs GPT-6.2 Sol.
Checklist de aceite da primeira chamada
Antes de dar a integração com o Neon por concluída, salve este registro sem segredos:
- ID do modelo
gemini-4-neon, endpoint, versão do SDK e identificador do projeto. - Uma resposta salva que passe no verificador:
completedouSTOP, com texto não vazio. - A linha de uso, com tokens de raciocínio e de entrada em cache registrados separadamente.
- O
thinking_levele omax_output_tokensenviados, escritos explicitamente no código em vez de herdados dos padrões. - Qualquer erro encontrado e a mudança que o corrigiu.
Com essa base pronta, acrescente ferramentas, documentos longos ou jobs em segundo plano um de cada vez. Quando algo falhar, você saberá que foi a parte nova.
Documentação relacionada
- Documentação da Gemini API da Ofox: formato de requisição para os modelos Gemini disponíveis na Ofox
- Guia de tratamento de erros da Ofox: como ler erros e tentar de novo nas rotas da Ofox
- Limites de taxa da Ofox: limites padrão atuais e como pedir aumento
- Google: What’s new in Gemini 4 Neon (em inglês): guia oficial do modelo e checklist de migração


