Blogue

Tutorial

Gemini-4 Argon e Carbon no HiAPI: curl, Python e requisições executáveis

Um guia prático de integração para desenvolvedores que escolhem entre gemini-4-argon, gemini-4-carbon e gemini-4-carbon@vertex

Nov 17, 2026
Arte de capa em índigo profundo e plano com setas largas em chevron aninhadas com bordas dianteiras em damasco subindo diagonalmente, para um artigo tutorial do HiAPI.
Nesta página

Escolha a variante do Gemini-4 antes de escrever código

A primeira decisão de qualquer integração com o Gemini-4 não é curl ou Python — é qual model ID você envia. No HiAPI, gemini-4-argon, gemini-4-carbon e gemini-4-carbon@vertex são três destinos roteáveis distintos, e a string que você passa no campo model determina qual backend atende sua requisição. Escolhê-la desde o início evita depurar um corpo de requisição que nunca funcionaria.

Os três destinos na prática

  • gemini-4-argon — uma variante independente do Gemini-4, com seu próprio model ID. Trate-a como um modelo próprio, não como um alias: seu comportamento, características de latência e propriedades de saída podem diferir do Carbon.
  • gemini-4-carbon — o destino Carbon padrão sob o roteamento padrão do HiAPI.
  • gemini-4-carbon@vertex — a mesma família Carbon, mas servida por uma rota com suporte a Vertex. O sufixo @vertex faz parte do próprio model ID, não é um parâmetro separado.

Como decidir

Parta da carga de trabalho. Se você está avaliando o Gemini-4 de forma ampla, execute o mesmo prompt em gemini-4-argon e gemini-4-carbon e compare as saídas antes de se decidir. Se você realmente precisa do roteamento Vertex — por exemplo, porque ele corresponde ao ambiente que sua equipe já opera — vá direto para gemini-4-carbon@vertex.

Ponto prático: os três usam a mesma estrutura de requisição. Escolher a variante é questão de mudar uma linha, então você pode adiar a decisão final até ter uma requisição funcional. Se quiser ver o model card primeiro, consulte gemini-4-argon e gemini-4-carbon.

Os exemplos deste guia usam gemini-4-carbon do início ao fim; para acompanhar com qualquer variante, basta substituir esse ID.

Prepare as credenciais e a URL base

Antes que qualquer corpo de requisição importe, três coisas precisam estar corretas: a URL base, a API key e o formato do header de autenticação. A maioria das falhas na primeira requisição vem de uma dessas três.

O que você precisa

  1. Uma API key do painel da sua conta HiAPI. Trate-a como segredo — carregue de uma variável de ambiente, nunca cole no arquivo-fonte.
  2. A URL base do HiAPI. Todas as chamadas de modelo vão para o mesmo host; a variante do modelo é escolhida pelo campo model, não pelo caminho.
  3. Dois headers em toda requisição:
    • Authorization: Bearer $HIAPI_API_KEY
    • Content-Type: application/json

Configure seu ambiente

export HIAPI_API_KEY="your-key-here"

Depois, antes de escrever qualquer código, verifique se o seu shell consegue vê-la:

echo "${HIAPI_API_KEY:0:4}..."

Se não imprimir nada, sua chave não foi exportada no shell atual e toda requisição falhará com erro de autenticação. Corrija aqui, não no seu cliente.

A estrutura de requisição que você vai reutilizar

Todo exemplo abaixo envia um corpo JSON contendo uma string model e um array messages. Essa estrutura não muda entre curl e Python, entre não-streaming e streaming, nem entre variantes de modelo. Mantenha-a estável e você poderá portar código copiando o corpo da requisição.

Uma requisição curl executável

Abaixo está uma chamada não-streaming completa, pronta para copiar e colar. Execute-a antes de adicionar qualquer outra coisa — se ela passar, isso prova que sua chave, URL base e headers estão corretos.

curl -sS "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain what an idempotency key is in two sentences."}
    ]
  }'

O que cada campo faz

  • model — o seletor de variante. Mude para gemini-4-argon ou gemini-4-carbon@vertex e você atinge um destino diferente sem qualquer outra alteração.
  • messages — um array ordenado. Os papéis são system, user e assistant. Se usar uma mensagem de sistema, coloque-a primeiro.
  • content — o texto da mensagem. Para turnos simples de texto, é uma string comum.

Lendo o corpo da resposta

A resposta é um objeto JSON contendo a réplica do modelo e metadados como uso de tokens. Como é não-streaming, o corpo inteiro chega de uma vez e o curl encerra após imprimi-lo. Se você receber um objeto JSON analisável com a mensagem de resposta, sua requisição está funcionando — tudo o que vem depois se apoia nessa linha de base.

Uma verificação rápida de sanidade: passe a saída por um formatador JSON (| jq .) para que a estrutura da resposta fique legível em vez de uma única linha longa.

Envie a mesma requisição com Python

A versão em Python mantém o corpo da requisição idêntico — só o transporte muda. Use requests:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gemini-4-carbon",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain what an idempotency key is in two sentences."},
    ],
}

response = requests.post(
    f"{base_url}/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])

Por que isso corresponde exatamente à chamada curl

Observe que payload é byte a byte igual ao corpo JSON da seção anterior. O argumento json= o serializa e define o Content-Type para você; o dicionário de headers fornece a autenticação. Nada muda em modelo, mensagens ou papéis.

Dois hábitos que vale manter

  • Defina um timeout. Sem timeout, uma conexão travada deixa seu processo pendurado indefinidamente. Para chamadas não-streaming, timeout=60 é um ponto de partida razoável.
  • Chame raise_for_status() antes de ler o corpo da resposta. Requisições com falha retornam um objeto de erro estruturado, não uma completion — inspecionar json() em um 4xx vai te enganar. Deixe a exceção estourar primeiro e então registre o texto da resposta.

Coloque o corpo da requisição em uma função ou pequeno objeto de configuração, para que as seções de streaming e chamada de ferramentas o estendam em vez de copiá-lo.

Adicione suporte a streaming à chamada

Faça a requisição não-streaming passar primeiro. Depois habilite o streaming — os modos de falha são diferentes, e empilhar as duas mudanças torna os erros difíceis de isolar.

Ative o streaming

Adicione um campo ao corpo de requisição existente:

{
  "model": "gemini-4-carbon",
  "stream": true,
  "messages": [
    {"role": "user", "content": "List three uses for a message queue."}
  ]
}

Essa é toda a mudança de protocolo. O servidor agora retorna uma sequência de eventos em vez de um documento JSON.

Consuma o stream corretamente

Regra principal: não chame .json() em uma resposta em streaming. Você terá erro de parsing, porque o corpo da resposta não é um único objeto JSON. Com requests, itere linha a linha e analise cada chunk separadamente:

import json, os, requests

response = requests.post(
    f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "gemini-4-carbon",
        "stream": True,
        "messages": [{"role": "user", "content": "List three uses for a message queue."}],
    },
    stream=True,
    timeout=60,
)
response.raise_for_status()

for line in response.iter_lines():
    if not line:
        continue
    decoded = line.decode("utf-8")
    if decoded.startswith("data: "):
        decoded = decoded[len("data: "):]
    if decoded.strip() == "[DONE]":
        break
    try:
        chunk = json.loads(decoded)
    except json.JSONDecodeError:
        continue
    print(chunk)

O que observar

  • Passe stream=True para requests. Caso contrário, o cliente armazena o corpo inteiro da resposta em buffer e só depois você vê uma linha, o que anula o propósito.
  • Ignore linhas vazias e mensagens keep-alive que não sejam JSON. O try/except acima é intencional — o stream pode conter linhas que não são chunks analisáveis.
  • Acumule texto entre chunks. Cada chunk carrega um fragmento, não a resposta completa. Anexe os deltas de texto à medida que chegam.

Quando o streaming funcionar, volte stream para false nos seus testes não-streaming, para que a chamada de ferramentas continue fácil de ler. Para uma visão geral do destino Carbon, a página do modelo gemini-4-carbon é uma boa referência.

Adicione chamada de ferramentas ao corpo da requisição

A chamada de ferramentas muda a requisição em dois pontos: você declara ferramentas e você lida com um turno de resposta que pode conter pedidos de chamada de ferramenta em vez de texto. Adicione esse recurso somente depois que a chamada de texto não-streaming passar.

Declare as ferramentas

Adicione um array tools ao lado de model e messages. Cada ferramenta tem um nome, uma descrição e o JSON Schema dos seus parâmetros. A descrição importa — é o que o modelo usa para decidir se chama a ferramenta.

{
  "model": "gemini-4-carbon",
  "messages": [
    {"role": "user", "content": "What is the weather in Lisbon?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

O ciclo de chamada de ferramentas

Uma requisição que usa ferramentas é uma conversa, não uma chamada única:

  1. Envie a mensagem do usuário junto com as declarações de ferramenta.
  2. Inspecione o turno do assistente. Se ele contiver argumentos de chamada de ferramenta, o modelo quer que você execute algo.
  3. Execute a função localmente — o HiAPI não executa seu código.
  4. Anexe duas mensagens: o turno de chamada de ferramenta do assistente e uma mensagem com papel tool contendo o resultado da função, associada ao ID da chamada correspondente.
  5. Reenvie o histórico completo de mensagens. O modelo agora produz a resposta final.

Pontos de falha específicos de ferramentas

  • Incompatibilidade de schema. Se o seu schema de parameters marca um campo como obrigatório, mas o resultado o omite, turnos seguintes podem ser rejeitados. Mantenha o schema preciso.
  • Descartar o histórico. Cada reenvio deve incluir a mensagem original do usuário e o turno de chamada de ferramenta — não apenas o resultado da ferramenta.
  • Streaming mais ferramentas. Argumentos de chamada de ferramenta podem chegar divididos em vários chunks do stream. Enquanto você aprende o fluxo, execute ferramentas com stream: false, para que cada turno chegue como um objeto legível.

Troque de modelo e de provedor sem reescrever o cliente

Como a variante do modelo é apenas uma string no corpo da requisição, trocar de destino é uma mudança de configuração, não uma refatoração. Projete o cliente para ler o model ID de uma variável — variável de ambiente, arquivo de configuração, flag de CLI — e nunca o codifique em vários lugares.

A troca em si

export HIAPI_MODEL="gemini-4-carbon"      # default
export HIAPI_MODEL="gemini-4-argon"       # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex"  # Vertex-backed Carbon

No código, referencie essa variável no corpo da requisição:

payload = {
    "model": os.environ["HIAPI_MODEL"],
    "messages": messages,
}

O sufixo @vertex viaja junto com a string do modelo. Não o separe em um campo próprio nem o remova — ele faz parte do ID roteável, e removê-lo roteia silenciosamente para o destino não-Vertex.

O que retestar após a troca

  1. Turnos de texto simples — confirme que o ID é reconhecido e que a autenticação continua válida.
  2. Seu prompt real mais longo — variantes diferentes podem tratar entradas longas ou estruturadas de forma distinta; verifique truncamento e formatação.
  3. Streaming — execute novamente o caminho de streaming, pois o ritmo dos chunks e os limites podem variar por destino.
  4. Chamada de ferramentas — revalide o ciclo completo de chamada de ferramentas; o formato dos argumentos é onde as diferenças entre variantes costumam aparecer mais.

Mantenha um pequeno script de smoke test que execute essas quatro verificações contra o HIAPI_MODEL atualmente configurado. Assim, trocar de provedor vira uma mudança de configuração e um comando, não uma sessão de depuração.

Solucione falhas comuns de requisição

Quase toda falha de integração se encaixa em poucas categorias. Identifique o sintoma, aplique a correção e execute novamente a linha de base não-streaming antes de mudar qualquer outra coisa.

Autenticação e roteamento

  • 401 ou 403. Chave ausente, expirada ou com prefixo incorreto. Verifique se o header é exatamente Authorization: Bearer <key>, com um único espaço, e confirme que a variável realmente foi exportada no shell ou processo que executa o código. Imprima os primeiros caracteres para confirmar.
  • Endpoint retorna 404. Sua URL base está errada ou há um segmento de caminho duplicado. O modelo vai no corpo da requisição, não na URL.
  • Modelo não encontrado. Erro de digitação no model ID. Compare caractere a caractere com gemini-4-argon, gemini-4-carbon e gemini-4-carbon@vertex — o sufixo @vertex é o que as pessoas mais esquecem.

Problemas no corpo da requisição

  • 400 com mensagem de schema. Normalmente é o formato de messages: role ausente, content que deveria ser string mas não é, ou array vazio. Comece com o corpo mínimo de duas linhas deste guia e adicione um campo por vez.
  • 400 depois de adicionar ferramentas. Seu schema de parameters é um JSON Schema inválido, ou o turno de resultado da ferramenta não corresponde ao ID de chamada na mensagem do assistente. Registre o corpo completo da resposta — o texto do erro aponta o campo problemático.

Falhas de streaming

  • Erro de parsing JSON na resposta. Você chamou .json() no stream. Em vez disso, itere linha a linha e analise cada chunk, ignorando linhas vazias e o marcador [DONE].
  • A resposta chega de uma vez. Você esqueceu de definir stream=True na chamada do cliente, então requests armazenou o corpo inteiro em buffer.
  • Saída truncada. Seu loop encerrou cedo — geralmente em uma linha vazia ou mensagem keep-alive. Pare somente no marcador explícito de fim de stream.

Disciplina de depuração

Faça uma busca binária na mesma ordem em que você construiu: autenticação e headers, depois texto não-streaming, depois streaming, depois ferramentas. Cada camada tem assinaturas de falha diferentes, então o que você alterou por último quase sempre é a causa. Em cada falha, registre o status HTTP e o corpo completo da resposta — a mensagem geralmente aponta o campo específico.

Faça a linha de base passar primeiro em gemini-4-argon ou gemini-4-carbon e então estenda o corpo da requisição a partir dali. Se você ainda está decidindo qual variante se adequa à sua carga de trabalho, a página do modelo gemini-4-argon é o ponto de partida.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API