Como conectar a API Gemini 4 Neon? Primeira requisição nativa APIYI e compatível com OpenAI

Como conectar a API Gemini 4 Neon? Primeira requisição nativa APIYI e compatível com OpenAI

Nota do autor: este artigo mostra como enviar a primeira requisição ao Gemini 4 Neon na APIYI usando dois protocolos, e quais campos e logs conferir depois que a requisição for bem-sucedida.

Conclusão antecipada: se o projeto já tem um cliente OpenAI Chat, use o endpoint Chat Completions compatível com OpenAI e troque apenas base_url e o nome do modelo. Se precisar definir explicitamente o nível de raciocínio do Gemini, use o endpoint nativo generateContent do Gemini e informe isso em generationConfig.thinkingConfig.thinkingLevel. Não importa o caminho escolhido: primeiro faça um teste de ponta a ponta com texto puro usando o mesmo comando curto; em seguida, valide com base no status HTTP, no corpo da resposta, no motivo de parada, no consumo e nos logs da plataforma. Depois que a validação passar, teste capacidades como saída em streaming e chamada de ferramentas.

O contexto é este. O Google publicou o Gemini 4 Neon no changelog do AI Studio em 18 de novembro de 2026 e anunciou sua disponibilidade geral (GA). A APIYI confirmou a disponibilização em 2026-11-20 às 11:45, horário de Pequim; o modelo gemini-4-neon aparece no catálogo público de preços, e os grupos disponíveis são default e svip. Os exemplos deste artigo foram escritos com base na documentação da APIYI e na documentação do SDK; nenhum endpoint pago foi chamado e o texto não traz estatísticas de testes reais.

gemini-4-neon-api-first-request-native-openai-compatible-pt-pt-image-0


Mapa de conhecimento e índice de integração da API Gemini 4 Neon

Todo o processo de integração tem três etapas: escolher o endpoint, enviar a requisição e conferir a saída e os logs. O resultado de cada etapa é a entrada da próxima. A tabela abaixo reúne a ordem dessas três etapas, a justificativa do arranjo e o objetivo de cada uma; ela serve tanto como mapa de conhecimento quanto como índice de leitura.

Número Etapa O que a etapa anterior fornece Por que está nessa ordem Objetivo desta etapa
1 Escolher o endpoint (1.1 Chat compatível / 1.2 Nativo e nível de raciocínio) Sua stack de código atual e a necessidade de definir o nível de raciocínio O endpoint define a URL, a forma de autenticação e a estrutura dos campos; todas as etapas seguintes dependem dele Definir um único protocolo e não tentar depurar dois caminhos ao mesmo tempo
2 Enviar a mesma requisição curta (2.1 cURL nativo / 2.2 SDK Python) O endpoint e o formato de requisição já definidos Usar um comando curto fixo permite eliminar diferenças de capacidade do modelo e testar apenas se o caminho está funcionando Obter o código de status, os cabeçalhos e o corpo da resposta completos
3 Validação (3.1 Campos / 3.2 Identidade e logs / 3.3 Evidências de falha) A resposta bruta salva na etapa 2 Primeiro olhar a própria resposta, depois comparar com os logs da plataforma; as evidências vão do mais próximo ao mais distante Determinar se o “sucesso textual” se confirma; se não, deixar evidências rastreáveis

Sugestão de leitura: se você usa apenas um dos protocolos, depois de ler a subseção correspondente na seção 1, vá direto para 2.1 ou 2.2; a seção 3 precisa ser lida por inteiro.

gemini-4-neon-api-first-request-native-openai-compatible-pt-pt-image-1

Para saber: termos essenciais da API Gemini 4 Neon

Termo Explicação breve
generateContent Endpoint de geração não streaming nativo do Gemini; o corpo da requisição organiza o conteúdo com contents e parts
thinkingLevel Campo de nível de raciocínio dentro de generationConfig.thinkingConfig no endpoint nativo; nos exemplos deste artigo, usamos high
thought part Parte da resposta nativa marcada como conteúdo de raciocínio; deve ser excluída ao montar o texto final
finishReason / finish_reason Campos de motivo de parada dos endpoints nativo e compatível, respectivamente
X-Shellapi-Request-Id Identificador de requisição retornado pelo APIYI no cabeçalho da resposta bruta ou na mensagem de erro, usado para solução de problemas

1 Escolha do ponto de entrada para a API do Gemini 4 Neon

As duas entradas apontam para o mesmo modelo; a diferença está no formato do protocolo e nos parâmetros que podem ser controlados. A seguir, mostro primeiro uma comparação e depois explico os motivos da escolha em duas subseções.

Item de comparação Chat compatível com OpenAI Gemini nativo
Endereço https://api.apiyi.com/v1 + Chat Completions https://api.apiyi.com/v1beta/models/gemini-4-neon:generateContent
Indicado para Projetos que já têm OpenAI SDK ou cliente Chat Projetos que precisam controlar explicitamente parâmetros do Gemini
Nível de pensamento Este artigo não envia os parâmetros relacionados thinkingConfig.thinkingLevel
Local do texto principal choices[0].message.content O text que não seja thought dentro de candidates[0].content.parts
Identificador do modelo model na resposta modelVersion na resposta (se for retornado)

1.1 Entrada compatível do Gemini 4 Neon: continue usando o cliente Chat atual

Quando o código existente já se baseia no OpenAI Python SDK ou em outro cliente Chat Completions, a abordagem com menos alterações é trocar base_url para https://api.apiyi.com/v1, usar o nome de modelo gemini-4-neon e não mexer na estrutura das mensagens. A vantagem é que o código da camada de negócios quase não muda e, quando surge um problema, fica mais fácil identificar se ele está na rede, na autenticação ou no modelo.

Há alguns limites que precisam ficar claros nesse caminho. Primeiro, não envie reasoning_effort. A própria camada de compatibilidade do Google faz um mapeamento para ele, mas isso não significa que a entrada compatível da APIYI também assuma o mesmo compromisso. Segundo, este artigo não usa a interface /v1/responses. Terceiro, a antiga forma de escrever thinkingBudget e o nível minimal também ficam fora do escopo deste artigo. Se você realmente precisa controlar o nível de pensamento, use a entrada nativa da seção 1.2.

1.2 Entrada nativa do Gemini 4 Neon: defina explicitamente o nível de pensamento

A entrada nativa usa a estrutura de requisição do próprio Gemini. O nível de pensamento é passado explicitamente por generationConfig.thinkingConfig.thinkingLevel; no caso de uso específico da APIYI, o valor usado é "high". A resposta nativa também separa o conteúdo de pensamento e o texto principal em partes diferentes; por isso, ao ler o texto principal, é preciso filtrar ativamente. A seção 2.1 mostra como fazer isso na prática.

Em relação à autenticação, este caso de uso nativo usa o cabeçalho Authorization: Bearer, sem usar o formato comum da API oficial do Gemini com o parâmetro key. Ao migrar código nativo existente, confira esse ponto primeiro.


2 Enviar a mesma requisição curta para a API Gemini 4 Neon

Os dois protocolos usam o mesmo prompt: Reply with exactly NEON_OK and nothing else. A saída esperada deste prompt é bem curta, então o resultado é fácil de avaliar. Se o retorno não for NEON_OK, isso já indica que há um problema na cadeia de chamada ou na etapa de análise, o que permite descartar interferências do tipo “o estilo de resposta do modelo é diferente”. A chave API deve sempre ser lida da variável de ambiente APIYI_API_KEY, nunca escrita no código nem no histórico de comandos.

2.1 cURL nativo do Gemini 4 Neon e extração de valores do JSON

O comando abaixo salva separadamente o código de status HTTP, os cabeçalhos de resposta e o corpo da resposta JSON. Os três serão usados na aceitação da seção 3.

curl -sS -X POST "https://api.apiyi.com/v1beta/models/gemini-4-neon:generateContent" \
  -H "Authorization: Bearer ${APIYI_API_KEY}" \
  -H "Content-Type: application/json" \
  -D neon_native_headers.txt \
  -o neon_native_body.json \
  -w "%{http_code}\n" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Reply with exactly NEON_OK and nothing else."}]}
    ],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "high"}
    }
  }' > neon_native_status.txt

Ao ler o corpo, é preciso concatenar todos os text que não são de thought em candidates[0].content.parts, e não apenas pegar o primeiro part. O exemplo abaixo usa jq; se você não tiver o jq instalado, pode usar qualquer outra ferramenta de análise de JSON:

# Corpo: concatenar os text que não são thought
jq -r '[.candidates[0].content.parts[]? | select(.thought != true) | .text // empty] | join("")' neon_native_body.json

# Motivo de parada, uso e versão do modelo (quando o campo não existe, a saída é null; não preencha valores por conta própria)
jq '{finishReason: .candidates[0].finishReason, usageMetadata, modelVersion}' neon_native_body.json

# Identificador da requisição da plataforma
grep -i "x-shellapi-request-id" neon_native_headers.txt

2.2 Chamada do Gemini 4 Neon com o SDK Python da OpenAI e leitura do retorno

O endpoint compatível usa with_raw_response, assim você obtém tanto o objeto já analisado quanto os cabeçalhos de resposta originais. O max_retries=0 serve para desativar as novas tentativas automáticas do SDK, evitando que uma falha seja mascarada por uma nova tentativa e também impedindo que apareçam vários logs na plataforma, dificultando saber qual deles corresponde a qual requisição.

import os
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",  # Endpoint compatível com OpenAI da APIYI
    max_retries=0,
    timeout=120.0,
)

try:
    raw = client.chat.completions.with_raw_response.create(
        model="gemini-4-neon",
        messages=[{"role": "user", "content": "Reply with exactly NEON_OK and nothing else."}],
        max_tokens=4096,
    )
    print("HTTP:", raw.status_code)
    print("X-Shellapi-Request-Id:", raw.headers.get("x-shellapi-request-id"))

    completion = raw.parse()
    if not completion.choices:
        print("choices 为空,不读取正文")
    else:
        choice = completion.choices[0]
        print("content:", choice.message.content)
        print("finish_reason:", choice.finish_reason)
    print("usage:", completion.usage)
    print("model:", completion.model)

except APIStatusError as e:
    print("HTTP:", e.status_code)
    print("X-Shellapi-Request-Id:", e.response.headers.get("x-shellapi-request-id"))
    print("error:", e.message)  # Antes de registrar, confirme que não contém chaves ou outras informações sensíveis
except APIConnectionError as e:
    print("未拿到 HTTP 响应:", type(e).__name__)

Há um ponto que merece atenção especial neste código: quando choices está vazio, não escreva choices[0] diretamente, senão será lançado um erro de índice que mascara o problema real. Erros de conexão não têm código de status HTTP nem cabeçalhos de resposta, então precisam ser tratados separadamente dos APIStatusError.


3 Verificação da primeira requisição da API Gemini 4 Neon

O objetivo da verificação é determinar se “a requisição de texto puro foi bem-sucedida” de fato. Um status HTTP 2xx com o corpo sendo o NEON_OK esperado apenas indica que essa única requisição de texto funcionou. Isso não comprova a identidade do modelo, nem serve como resultado de teste de desempenho.

3.1 Status HTTP, corpo, motivo de parada e uso

Item de verificação Campo nativo Campo compatível Condição de aprovação
Status HTTP status salvo raw.status_code 2xx
Corpo concatenação de text que não seja thought choices[0].message.content igual a NEON_OK
Motivo de parada candidates[0].finishReason choices[0].finish_reason registrado e consistente com a situação do corpo
Uso usageMetadata usage registrado, para comparação com os logs

Se algum campo não existir na resposta, registre-o como “não retornado” e não tente deduzir seu valor por experiência. O motivo de parada deve ser analisado junto com o corpo. Quando o corpo está vazio e o motivo de parada não é um encerramento normal, o problema geralmente está no processo de geração, não no código de parsing.

3.2 O que o modelVersion nativo, o model compatível e os logs podem comprovar

Essas informações têm alcances diferentes de comprovação. Ao registrá-las, não trate uma como substituta da outra:

Informação Origem Pode comprovar Não pode comprovar
modelVersion corpo da resposta nativa (se retornado) a versão do modelo informada pela própria resposta não serve, sozinho, como prova de identidade
model corpo da resposta compatível o nome do modelo informado pela própria resposta o mesmo acima
Logs da plataforma api.apiyi.com/log conferir esta chamada por horário, token, modelo e uso o console não exibe o ID da requisição
X-Shellapi-Request-Id cabeçalho da resposta original ou mensagem de erro identificador da requisição usado pela plataforma para diagnóstico não é o responseId, nem o id do Chat, nem o _request_id do SDK

Ao conferir os logs, use o horário em que a requisição foi enviada, o token utilizado, o nome do modelo gemini-4-neon e os números de uso para fazer a correspondência. Como o console não exibe o ID da requisição, o X-Shellapi-Request-Id precisa ser salvo por você mesmo a partir dos cabeçalhos da resposta; depois, não será possível consultá-lo no console.

gemini-4-neon-api-first-request-native-openai-compatible-pt-pt-image-2

3.3 Gemini 4 Neon: como preservar evidências quando não há corpo de resposta ou a requisição falha

Quando a requisição falhar ou não houver corpo de resposta, não tente novamente de imediato. Siga a ordem abaixo para guardar as evidências:

  1. Salve o código de status HTTP. Se for erro de conexão, anote o tipo de exceção.
  2. Salve os cabeçalhos brutos da resposta e extraia deles o X-Shellapi-Request-Id.
  3. Salve o corpo bruto da resposta ou a mensagem de erro, removendo conteúdos sensíveis como a chave API.
  4. Registre o motivo de parada e o uso (se houver), além do horário em que a requisição foi enviada, o nome do token usado e o nome do modelo.
  5. Acesse api.apiyi.com/log, encontre o registro correspondente por horário e token e, com os materiais acima em mãos, siga a documentação de solução de problemas por request ID da plataforma.

Sobre a resposta nativa há mais um ponto de atenção: se os parts contiverem apenas conteúdo de thought, o corpo filtrado ficará vazio. Nesse caso, registre fielmente “corpo filtrado vazio” e não trate o conteúdo de thought como corpo só para conseguir uma saída.


Depois que a verificação de texto puro em um único turno passar conforme explicado acima, valide, conforme a necessidade do projeto, recursos como saída em streaming e chamada de ferramentas. A cada recurso adicionado, faça uma verificação separada usando o método “mesma requisição, salvar a resposta bruta, conferir com o log”. Este artigo não trata de benchmarks nem de preços; para essas informações, consulte os anúncios oficiais e o catálogo público da APIYI.

Referências

  1. Changelog do Google AI Studio (2026-11-18): aistudio.google.com/docs/changelog
  2. Estrutura do GenerateContentResponse do Gemini: aistudio.google.com/api-reference/generate-content
  3. Comunicado de lançamento do Gemini 4 Neon na APIYI e exemplos dos dois protocolos: docs.apiyi.com/news/gemini-4-neon-launch.md
  4. Tratamento de resposta do Gemini na APIYI: docs.apiyi.com/api-capabilities/gemini/response-handling
  5. Tratamento de resposta compatível com OpenAI na APIYI: docs.apiyi.com/api-capabilities/openai/response-handling
  6. Solução de problemas por request ID na APIYI: docs.apiyi.com/faq/request-id-troubleshooting
  7. Acesso à resposta bruta no openai-python: github.com/openai/openai-python

Uma jornada de mil milhas começa com um único passo. — Tao Te Ching

Similar Posts