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
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@vertexfaz 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
- 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.
- 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. - Dois headers em toda requisição:
Authorization: Bearer $HIAPI_API_KEYContent-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 paragemini-4-argonougemini-4-carbon@vertexe você atinge um destino diferente sem qualquer outra alteração.messages— um array ordenado. Os papéis sãosystem,usereassistant. 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 — inspecionarjson()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=Truepararequests. 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/exceptacima é 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:
- Envie a mensagem do usuário junto com as declarações de ferramenta.
- Inspecione o turno do assistente. Se ele contiver argumentos de chamada de ferramenta, o modelo quer que você execute algo.
- Execute a função localmente — o HiAPI não executa seu código.
- Anexe duas mensagens: o turno de chamada de ferramenta do assistente e uma mensagem com papel
toolcontendo o resultado da função, associada ao ID da chamada correspondente. - 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
parametersmarca 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
- Turnos de texto simples — confirme que o ID é reconhecido e que a autenticação continua válida.
- Seu prompt real mais longo — variantes diferentes podem tratar entradas longas ou estruturadas de forma distinta; verifique truncamento e formatação.
- Streaming — execute novamente o caminho de streaming, pois o ritmo dos chunks e os limites podem variar por destino.
- 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-carbonegemini-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:roleausente,contentque 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=Truena chamada do cliente, entãorequestsarmazenou 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 →-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio
-
Tutorial
Cenários práticos de aplicação do gemini-4-neon: 5 usos de alto valor e pontos-chave de integração
-
Tutorial
Tutorial da API seedance-2.5-flash image-to-video: curl e Python Requests
Um exercício prático de integração para desenvolvedores: estrutura da requisição, entradas de primeiro/último quadro, polling assíncrono e diagnóstico de erros