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.

Um seletor giratório de quatro posições sobre uma base de madeira, com a quarta posição marcada em laranja, ligado a uma lâmpada tubular de vidro apagada.

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.io/v1/models) em 19 de novembro de 2026: ela traz google/gemini-4-hydrogen e google/gemini-4-argon, mas não o Neon, e https://ofox.io/models/google/gemini-4-neon retornou 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.

ItemValor no Neon
ID do modelogemini-4-neon (sem o sufixo -preview)
AcessoApenas nível pago da Gemini API; também no Google AI Studio com os planos Google AI Pro e Ultra
APIsInteractions API (usada no quickstart do Google) e generateContent
Níveis de raciocíniolow, medium, high (padrão), xhigh; minimal é rejeitado
Contexto1.048.576 tokens compartilhados entre entrada, raciocínio e saída
Saída síncrona65.536 tokens como padrão e limite por hop (etapa de geração), com ou sem streaming
Saída mais longaExecuçã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
CacheApenas implícito, a partir de 4.096 tokens de prompt; cachedContents explícito não é suportado
Amostragemtemperature, top_p e top_k são ignorados dentro do intervalo válido; fora dele, retornam 400
Data de corte do conhecimentoMarç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.

ÁreaCarbonHydrogenNeon
ID do modelogemini-4-carbongemini-4-hydrogengemini-4-neon
Nível gratuitoNãoSimNão
Raciocínio padrãomediumhighhigh
xhighNão suportadoSuportadoSuportado
Hop sem streaming32.768 tokens por hop em REST bruto65.53665.536
Parâmetros de amostragemIgnoradosIgnorados dentro do intervalo, 400 fora deleIgnorados 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:

  1. Migrar do Carbon aumenta o gasto padrão por chamada. O Carbon usa medium por padrão; o Neon usa high. Código que nunca definiu thinking_level vai 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.
  2. 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.
  3. 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 em high. Use low para 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=False tira essa chamada única do armazenamento. Deixe o armazenamento ligado (o padrão) se for usar background=True ou previous_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:

StatusO que significaO que fazer
queued, in_progressAinda em execução (chamadas em segundo plano)Consulte interactions.get com o mesmo id
completedConcluídaJunte o texto de model_output e leia usage
requires_actionO modelo pediu uma chamada de ferramentaExecute a ferramenta e envie o resultado com este id
requires_continuationUm hop em primeiro plano atingiu o limite de 65.536 e ainda resta orçamentoO SDK continua por padrão; em REST, envie o próximo hop com previous_interaction_id e continuation_token
incompleteTodo o max_output_tokens foi usado; o texto pode estar vazioRetome ou reenvie com um max_output_tokens maior
failedO servidor não conseguiu concluirTente de novo uma vez; se falhar outra vez, guarde o id para o suporte
cancelledVocê cancelouLeia 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.

SignificadoInteractions usagegenerateContent usageMetadata
Tokens de entradatotal_input_tokenspromptTokenCount
Entrada com acerto de cachetotal_cached_tokenscachedContentTokenCount
Saída visíveltotal_output_tokenscandidatesTokenCount
Raciocíniototal_thought_tokensthoughtsTokenCount
Tokens de prompt de uso de ferramentastotal_tool_use_tokenstoolUsePromptTokenCount
Totaltotal_tokenstotalTokenCount

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ívelDescrição do GoogleUso típico
lowMenos tokens, menor latênciaChat rápido, processamento de alto volume, verificações de acesso baratas
mediumMenor uso de tokens, respostas mais rápidasProgramação interativa, prototipagem de UI, chamadas de ferramenta sensíveis à latência
high (padrão)Equilíbrio entre inteligência e velocidadeA maior parte da programação complexa, execução agêntica, trabalho de conhecimento multimodal
xhighMais tokens, raciocínio mais profundoEngenharia 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:

  • xhigh e o limite de 65.536 interagem. O limite cobre raciocínio mais saída. O guia de raciocínio do Google alerta que xhigh pode raciocinar demais e esgotar o max_output_tokens em prompts simples, como extração de texto ou de JSON. Se aparecer MAX_TOKENS ou uma interaction incomplete com 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 um max_output_tokens maior (veja a seção de execução em segundo plano abaixo). Não reduza o max_output_tokens para 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 é em xhigh. 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.

SintomaCausa provável no NeonCorreção
Erro de acesso ou de cota com uma chave que funciona no HydrogenA chave pertence a um projeto do nível gratuito; o Neon é só do nível pagoUse uma chave de um projeto com cobrança paga ativa (passo 1)
Modelo não encontradoErro de digitação, sufixo inventado como -preview ou um gateway que não roteia o NeonUse gemini-4-neon em generativelanguage.googleapis.com
400 em thinking_levelminimal enviado (rejeitado no Gemini 4), estruturas de campo da Interactions e do generateContent misturadas, ou um thinkingBudget antigo enviado junto com o nívelUse low/medium/high/xhigh; ajuste os nomes de campo ao endpoint; remova thinkingBudget
Erro de validação 400 com parâmetros de amostragemtemperature, top_p ou top_k fora do intervaloRemova os parâmetros de amostragem; valores dentro do intervalo são ignorados de qualquer forma
Requisição falha depois de migrar código de cacheReferência antiga a cached_content / cachedContents (cache explícito não suportado)Remova; conte com o cache implícito
MAX_TOKENS, incomplete ou texto vaziomax_output_tokens baixo consumido pelo raciocínioVolte para 65.536, use execução em segundo plano para trabalhos longos ou reduza o raciocínio de forma deliberada
MALFORMED_FUNCTION_CALLO modelo foi instruído a emitir chamadas de ferramenta em JSON como texto puro sem ferramentas declaradasDeclare as ferramentas com function calling ou use saída estruturada
Erros de assinatura no uso de ferramentas em vários turnosAssinaturas de raciocínio descartadas ou copiadas entre chamadas paralelasUse 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íceisO raciocínio em high/xhigh leva minutosAumente o timeout HTTP para pelo menos 15 minutos ou use execução em segundo plano
429Os limites de taxa continuam valendo no nível pagoReduza 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.io/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: completed ou STOP, com texto não vazio.
  • A linha de uso, com tokens de raciocínio e de entrada em cache registrados separadamente.
  • O thinking_level e o max_output_tokens enviados, 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