Gemini 4 Argon API: um chat em Python com streaming nativo

Uma conversa com a API do Gemini 4 Argon usa conteúdo nativo do Gemini: contents, papéis e parts. A primeira requisição é pequena. A parte mais difícil é preservar a resposta corretamente antes de enviar uma pergunta de acompanhamento. Reconstruir um turno do modelo apenas com o texto visível pode fazer você perder conteúdo assinado; adicionar uma mensagem de carregamento vazia ao histórico pode invalidar a próxima requisição.

Este tutorial usa a biblioteca padrão do Python e o endpoint nativo do SeedRouter. Ele cobre chat de texto e streaming. A referência completa da API descreve toda a especificação de parâmetros; este artigo acompanha uma requisição até formar uma conversa utilizável.

Antes da primeira requisição

Você precisa de Python 3, uma chave de API do SeedRouter e saldo suficiente na conta. Mantenha a chave em uma variável de ambiente chamada SEEDROUTER_API_KEY; não a coloque no código-fonte nem em um pacote enviado ao navegador. Cada mensagem enviada pode gerar cobranças. O exemplo não repete requisições automaticamente nem faz chamadas de continuação.

O ID do modelo é gemini-4-argon, e o modelo deve estar no caminho do endpoint. O Google documenta esse formato no guia de geração nativa. O SeedRouter usa autenticação Bearer, como mostrado abaixo.

Enviar uma requisição à API do Gemini 4 Argon

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

A resposta é uma sequência de eventos enviados pelo servidor, não um único documento JSON. Cada evento data: contém JSON nativo do Gemini. O texto visível aparece em candidates[].content.parts[].text; algumas partes contêm raciocínio ou assinaturas em vez disso. usageMetadata pode chegar separado do texto, então leia até o último evento antes de considerar a resposta completa.

Esse orçamento de saída é deliberadamente pequeno para uma verificação inicial de funcionamento. O raciocínio também consome o orçamento, portanto a resposta pode ficar incompleta. Aumente-o de forma consciente para tarefas mais difíceis; não transforme uma resposta incompleta em um ciclo de novas tentativas invisível.

Executar uma conversa de dois turnos em Python

Baixe o exemplo completo em Python, salve-o localmente e execute:

python3 gemini-4-argon-chat.py

Pergunte “Explain a mutex in one sentence” e depois “Give a Python example of that idea”. O script espera sua entrada antes de cada requisição. Digite uma linha vazia para encerrar. A regra principal do histórico é:

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

O script disponível para download também fornece as configurações de geração, analisa os quadros SSE, imprime somente o texto que não é raciocínio e salva o histórico apenas após um motivo de término STOP com parts não vazias. Um erro de API, um fluxo interrompido ou uma resposta vazia mantém o histórico anterior intacto. O script não reenvia uma mensagem silenciosamente.

O trecho menor acima explica a estrutura dos dados; execute o arquivo completo para ter todo o tratamento de requisições. Para respostas sem streaming, a operação correspondente é generateContent, e os exemplos de referência mostram cURL, Python, Node.js e Go.

Preservar as parts nativas, não o indicador de carregamento

A segunda requisição deve conter três turnos reais: a primeira mensagem do usuário, a resposta concluída do modelo e a segunda mensagem do usuário. O texto “Pensando…” da interface não é outro turno do modelo.

Um erro como contents.3.parts: Too small: expected array to have >=1 items significa que a quarta entrada de conteúdo tem um array parts vazio. O índice começa em zero. Verifique como o histórico é montado antes de mudar o prompt ou o modelo. Um indicador de carregamento pertence ao estado de exibição; ele nunca deve virar { "role": "model", "parts": [] } na requisição.

Mantenha todas as partes retornadas na ordem original, incluindo thoughtSignature e as partes marcadas como raciocínio, mesmo que a interface as oculte. O guia de assinaturas de raciocínio do Google explica por que esses campos opacos precisam ser preservados nos turnos seguintes. Não edite, invente nem reconstrua uma assinatura. Armazene o histórico nativo separadamente do texto exibido na interface.

O mesmo princípio de preservação se aplica a conversas com ferramentas, mas executar uma ferramenta e devolver seu resultado exige um ciclo de aplicação mais amplo. Este exemplo de texto não implementa esse ciclo e não deve ser apresentado como um agente de programação completo.

Ler o uso e lidar com a interrupção

Para requisições diretas, preserve os últimos valores de uso informados pelo fluxo. Não some os registros cumulativos repetidos dentro da mesma requisição. A entrada comum é promptTokenCount menos cachedContentTokenCount; a saída cobrada inclui tanto candidatesTokenCount quanto thoughtsTokenCount. O guia de preços transforma essas contagens em um orçamento.

Ctrl+C interrompe o exemplo sem enviar outra requisição. Parar a leitura local não prova que a geração remota não usou tokens. Se o fluxo terminar antes de os dados de uso chegarem, consulte o registro de uso da sua conta. Por precaução, o exemplo exclui o turno incompleto do histórico futuro; preservar respostas parciais é uma decisão separada da aplicação.

A decodificação longa é outro caso distinto. Um motivo de término CONTINUATION retoma a geração original com um token de continuação; não é uma nova mensagem do usuário. O Google exige a requisição original e o token mais recente, sem acrescentar a saída parcial a contents. Consulte o guia de decodificação longa. Este script introdutório para em vez de implementar continuação automática.

O que foi verificado?

O streaming básico de texto passou por uma verificação local de ponta a ponta pelo Playground do SeedRouter. A análise dos dados e a gestão do histórico do exemplo são verificadas com fluxos sintéticos, incluindo partes assinadas, respostas vazias e interrupções. Esses dados de teste verificam o software; não são execuções adicionais do modelo. Ferramentas, mídia e continuação ainda precisam de verificações separadas de capacidade antes de serem descritas como integrações verificadas.

Perguntas sobre a API

Posso substituir o nome de um modelo OpenAI por gemini-4-argon?

Isso, por si só, não converte os formatos das mensagens. Este guia usa os campos nativos do Gemini contents e parts. Verifique se o cliente oferece suporte a esse protocolo, à autenticação e ao endpoint que você configurar.

Por que a resposta está vazia mesmo tendo usado tokens?

O raciocínio pode consumir o orçamento de saída, e a segurança ou uma geração incompleta também podem impedir a exibição de texto. Examine o motivo de término e o uso. Não insira um turno vazio do modelo nem repita automaticamente a requisição paga.

Um contexto de um milhão de tokens significa um milhão de tokens de saída?

Não. Entrada, raciocínio e saída compartilham o contexto. Gerações longas também têm limites por requisição e podem precisar de continuação. Planeje o orçamento para o total compartilhado, não para cotas separadas de entrada e saída.

Adicionar recursos depois que a conversa funcionar

Comece com uma resposta completa e depois confirme que o segundo turno recebe o conteúdo nativo original. Mantenha o histórico da API do Gemini 4 Argon separado do estado de exibição ao adicionar anexos, ferramentas ou persistência. O Playground do modelo e o guia de acesso são os próximos passos para uso interativo e requisitos da conta.