Tutorial
Como chamar gpt-5.6-sol@azure via API HiAPI: curl e Python
Autenticação, estrutura do corpo da requisição, exemplos disponíveis e tratamento de erros
Nesta página
O que significa gpt-5.6-sol@azure como destino de modelo da HiAPI
gpt-5.6-sol@azure é um identificador de modelo, não um SDK independente, não um endpoint independente e não um método de autenticação independente. É exatamente a string que você coloca no campo model da requisição de chat completion enviada à HiAPI.
O sufixo @azure informa qual provedor de backend atende essa variante do modelo. Do ponto de vista da sua aplicação, isso não altera em nada a forma de chamar: mesma URL base, mesma autenticação bearer, mesma estrutura de requisição e resposta, igual a qualquer outro modelo de chat da plataforma. Você não precisa instalar nada extra nem usar credenciais específicas do provedor — a HiAPI cuida do roteamento e da relação com o provedor do lado dela.
O resultado prático: qualquer cliente compatível com OpenAI que você já usa pode apontar para esse modelo com duas alterações: definir a URL base do cliente para a HiAPI e configurar o nome do modelo como gpt-5.6-sol@azure. Se você atualmente tem o nome do modelo codificado em algum lugar da configuração, esse valor é a única coisa que precisa mudar ao trocar de modelo na plataforma — o que torna a comparação A/B muito barata.
Neste tutorial, o identificador aparece sempre como a string literal gpt-5.6-sol@azure. Digite-o com exatidão: diferencia maiúsculas de minúsculas, e espaços extras trazidos por copiar e colar são uma das causas reais do erro de "modelo desconhecido" descrito mais adiante.
O que você precisa ter antes de começar
- Uma conta HiAPI com acesso à plataforma.
- Uma chave de API gerada a partir da sua conta.
- Um shell com
curl, ou Python 3 com a bibliotecarequests.
Os exemplos abaixo não exigem nenhuma outra ferramenta.
Obter a chave de API e configurar a autenticação
A autenticação da HiAPI é por bearer token: sua chave de API vai no cabeçalho Authorization de cada requisição, prefixada pela palavra Bearer seguida de um espaço.
Authorization: Bearer YOUR_API_KEY
Você gera a chave no painel da sua conta. Trate-a como uma senha — é uma credencial ativa que pode consumir seu saldo e nunca deve aparecer em commits, capturas de tela, notebooks compartilhados ou linhas de log.
Armazene-a em uma variável de ambiente
A prática de base é exportar a chave uma vez por sessão de shell e ler de qualquer outro lugar a partir do ambiente:
export HIAPI_API_KEY="your-key-here"
Em servidores, defina-a por meio do gerenciador de processos ou de um cofre de segredos, e não em um arquivo .env versionado. Se o arquivo .env for realmente a única opção, adicione-o ao .gitignore antes de gravar a primeira chave.
Referencie-a, não a coloque inline
No curl, referencie a variável de shell para que a chave nunca apareça no histórico de comandos nem na lista de processos:
curl -H "Authorization: Bearer $HIAPI_API_KEY" ...
Em Python, leia-a em tempo de execução com os.environ:
import os
API_KEY = os.environ["HIAPI_API_KEY"]
Use deliberadamente os.environ["..."] em vez de os.environ.get("..."): se a variável estiver ausente, você quer falhar ruidosamente na inicialização, e não encontrar um erro de autenticação confuso quinze linhas depois.
Regras de higiene de chaves para internalizar já
- Uma chave por ambiente. Chaves de desenvolvimento e de produção devem ser separadas, para que você possa rotacionar ou revogar uma sem quebrar a outra.
- Exposição exige rotação. Se uma chave apareceu em local público, revogue-a e emita uma nova — não apenas remova o commit.
- Não registre os cabeçalhos. Um middleware de log de requisições que despeja todos os cabeçalhos vai alegremente gravar seu bearer token em disco. Mascare o
Authorizationantes de registrar.
Se a primeira chamada resultar em erro de autenticação, a causa é quase sempre uma destas: a variável foi exportada em um shell diferente do que executa a requisição, o prefixo Bearer foi omitido, ou a chave foi copiada com uma quebra de linha no final.
Anatomia do corpo de requisição mínimo
Toda chamada a gpt-5.6-sol@azure é um POST com corpo JSON. Você pode construir uma requisição válida com um único campo, e essa é a melhor forma de começar: obtenha uma resposta primeiro, depois adicione os ajustes.
Campos obrigatórios
model— a stringgpt-5.6-sol@azure. É ela que roteia a requisição para o destino correto.messages— array de objetos de mensagem. Cada objeto temroleecontent. Os papéis convencionais sãosystem(instruções que moldam o comportamento),user(entrada) eassistant(turnos anteriores em conversas de múltiplos turnos).
O corpo mínimo fica assim:
{
"model": "gpt-5.6-sol@azure",
"messages": [
{ "role": "user", "content": "Explain what an idempotency key is in one paragraph." }
]
}
Isso basta. A resposta volta na estrutura de chat completion: um array choices cujo primeiro elemento guarda a resposta do assistente em message.content, mais um bloco usage descrevendo o consumo de tokens. Seu código deve ler de choices[0].message.content, e não presumir outro campo.
Campos opcionais que vale conhecer
Não são obrigatórios, mas serão os primeiros que você vai usar:
temperature— aleatoriedade da amostragem. Valores baixos tornam a saída mais determinística e repetitiva; valores altos a tornam mais variada. Escolha o valor de forma consciente, não por hábito.max_tokens(ou o limite equivalente de comprimento de saída exposto pelo seu cliente) — teto de geração. Útil tanto para latência quanto para controle de custo.top_p— outro controle de aleatoriedade. Na prática, ajustetemperatureoutop_p, não os dois ao mesmo tempo, senão você não conseguirá atribuir a mudança de comportamento a nenhum deles.stream— quando true, a resposta chega de forma incremental como server-sent events, em vez de um único documento JSON. Excelente para interfaces voltadas ao usuário, mas exige mais trabalho para analisar corretamente.stop— uma ou mais sequências que encerram a geração antecipadamente.
Observação sobre conversas de múltiplos turnos
A API é stateless. Nada é preservado entre requisições. Para continuar uma conversa, você reenvia o array messages inteiro a cada vez, anexando as respostas anteriores do assistente e a nova mensagem do usuário. Por isso, conversas longas fazem o corpo crescer e o consumo de tokens aumentar junto — dimensione isso ao projetar funcionalidades de chat.
Mantenha o corpo enxuto no início
Comece com os dois campos obrigatórios e confirme que você obtém uma resposta razoável. Depois adicione um parâmetro por vez e observe a diferença. Depurar é muito mais fácil quando você tem uma linha de base recente e sabidamente boa.
Requisição funcional com curl
Esta é uma requisição completa e executável. Se sua região ou plano for diferente, substitua a URL base pela URL mostrada na documentação da API da plataforma e garanta que HIAPI_API_KEY esteja exportada no shell atual.
curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol@azure",
"messages": [
{ "role": "system", "content": "You are a concise technical assistant." },
{ "role": "user", "content": "Give me three practical uses for idempotency keys." }
],
"temperature": 0.3
}'
O que cada flag faz
-sSsilencia a barra de progresso, mas ainda imprime erros — assim falhas não passam despercebidas.-X POSTdefine o método explicitamente, principalmente por legibilidade.- O cabeçalho
Authorizationcarrega o bearer token vindo do ambiente. Content-Type: application/jsoné obrigatório; sem ele o servidor não sabe como interpretar o corpo.-dfornece o payload JSON. Coloque-o entre aspas simples para que o shell não interprete as aspas duplas internas.
Ler a resposta
Uma chamada bem-sucedida retorna JSON com um array choices. O texto que você quer está em choices[0].message.content. Há também um objeto usage com as contagens de tokens de prompt e de completion — registre isso, pois é a forma barata de acompanhar a tendência de consumo antes que ele se torne uma surpresa.
Se você quiser inspecionar a estrutura diretamente sem brigar com o terminal, canalize por um formatador:
curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.6-sol@azure","messages":[{"role":"user","content":"Say hello."}]}' \
| python3 -m json.tool
Essa linha é o teste rápido mais veloz da existência de uma nova chave. Execute-a antes de tocar em qualquer código de aplicação — se falhar, o problema está nas credenciais ou na conectividade, não no seu programa.
A mesma requisição em Python
A versão com requests é curta, mas deve ser escrita com cuidado: verifique o código de status antes de analisar o corpo da resposta, porque a estrutura de uma resposta de erro é diferente da de uma resposta de sucesso e, se você acessar choices diretamente, terá um KeyError confuso.
import os
import json
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"
payload = {
"model": "gpt-5.6-sol@azure",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Give me three practical uses for idempotency keys."},
],
"temperature": 0.3,
}
response = requests.post(
URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
if response.status_code != 200:
# Surface the status and the server's error body, not just the exception.
print(f"HTTP {response.status_code}: {response.text}")
response.raise_for_status()
data = response.json()
text = data["choices"][0]["message"]["content"]
print(text)
print(json.dumps(data.get("usage", {}), indent=2))
Três detalhes importantes
Use json=payload, não data=json.dumps(payload). Passar o dicionário para json= define o cabeçalho de tipo de conteúdo para você e serializa corretamente todas as vezes. A serialização manual é a origem da maioria dos corpos de requisição malformados.
Sempre defina timeout. Sem ele, uma requisição travada pendura seu processo de trabalho indefinidamente. Um timeout generoso ainda é muito melhor do que nenhum.
Imprima response.text em caso de falha. O corpo de erro carrega os detalhes que você precisa — tipo de erro, código e mensagem legível. Registrar apenas a mensagem da exceção de raise_for_status() descarta essas informações e deixa você adivinhando.
Empacote em uma função
Assim que a chamada funcionar, promova-a a uma função que recebe o array de mensagens como parâmetro e retorna a string de conteúdo. Isso mantém o código da aplicação limpo e dá a você exatamente um lugar para mudar o nome do modelo, o timeout ou, mais tarde, a política de retentativa.
Diagnosticar erros comuns
Quase toda primeira chamada com falha se encaixa em uma de quatro categorias. Veja como distingui-las rapidamente.
Falha de autenticação
Sintoma: resposta 401, ou 403 se a chave for válida mas faltar acesso ao recurso solicitado.
Verifique na ordem:
HIAPI_API_KEYestá realmente definida no shell ou processo que faz a requisição?echo $HIAPI_API_KEYdeve imprimir algo.- O cabeçalho contém a palavra literal
Bearere exatamente um espaço antes da chave? - A chave trouxe uma quebra de linha ou aspas do copiar e colar? Exporte-a novamente de forma limpa.
- A chave foi revogada ou rotacionada desde que você a copiou? Emita uma nova.
Identificador de modelo desconhecido
Sintoma: 400 ou 404, com mensagem mencionando o modelo.
O culpado habitual é erro de digitação, divergência de maiúsculas/minúsculas ou espaço extra na string. gpt-5.6-sol@azure deve ser exato — o @, os hífens e a grafia em minúsculas contam. Se você lê o nome do modelo de um arquivo de configuração ou variável de ambiente, imprima o valor e o comprimento dele; espaço invisível é um vilão comum.
Corpo de requisição malformado
Sintoma: 400 reclamando de análise de JSON ou de campo ausente.
- Se o erro mencionar análise, seu corpo não é JSON válido. No
curl, coloque o payload entre aspas simples e as chaves entre aspas duplas. Em Python, usejson=payload. - Se mencionar
messages, verifique se você passou um array de objetos comroleecontent, e não strings soltas. - Se mencionar
modelausente, a chave está escrita errada ou no nível de aninhamento errado.
Verificação rápida de sanidade: antes de enviar, passe o payload por um validador de JSON. Leva poucos segundos e elimina toda a categoria.
Limites de taxa e cota
Sintoma: resposta 429, às vezes com indicação de retry-after.
Isso significa que sua requisição está correta e autenticada, mas chegou rápido demais ou passou da cota. A correção não é tentar novamente imediatamente em loop apertado — isso só piora. Use backoff exponencial com jitter, limite o número de tentativas e trate 429 persistentes como sinal para revisar a concorrência.
Erros do lado do servidor
500 ou 502 não são culpa sua. Tente novamente com backoff; se persistir, capture o ID completo da requisição e o corpo da resposta antes de escalar — esses detalhes é que tornam a conversa com o suporte produtiva.
Hábito de depuração genérico
Registre quatro coisas em cada chamada com falha: status HTTP, corpo da resposta, caminho do endpoint e nome do modelo. Não registre a chave de API. Esse quarteto distingue todas as categorias acima em segundos, algo que a mensagem de exceção crua raramente consegue.
Próximos passos após a primeira chamada bem-sucedida
Assim que o teste rápido retornar conteúdo, você tem uma integração funcional. Veja como torná-la duradoura.
Ajuste parâmetros de forma consciente
Escolha um temperature para seu caso de uso e escreva o motivo. Tarefas de extração e classificação costumam querer baixa aleatoriedade; brainstorming quer mais. Mude apenas um parâmetro por experimento para poder atribuir os resultados. Se estiver considerando streaming, prototipe cedo — a diferença na análise de resposta é grande o suficiente para que adaptar depois custe mais do que usar desde o início.
Trate retentativas e timeouts como política, não como reflexão tardia
Envolva a chamada em um wrapper de retentativa com backoff exponencial apenas para respostas 429 e 5xx. Nunca repita 400 ou 401 — a requisição ou a credencial está errada, e repetir só desperdiça tempo. Defina timeout de cliente por requisição e considere um prazo geral para fluxos do usuário.
Monitore custo e latência desde o primeiro dia
Registre o bloco usage junto com suas próprias medições de latência. A contagem de tokens é insumo de toda conversa sobre custo, e a latência é insumo de toda conversa sobre experiência do usuário. Sem elas, você otimiza às cegas.
Coloque o nome do modelo em configuração
Codificar gpt-5.6-sol@azure em três arquivos é a receita para uma migração sofrida. Mantenha-o em um único valor de configuração, e trocar de modelo vira uma mudança de uma linha — que também é a forma de comparar modelos de maneira justa na plataforma.
Mova a chave para a gestão de segredos adequada
Se você começou com uma variável de ambiente no notebook, o caminho de produção é um cofre de segredos gerenciado com injeção em tempo de execução. Mesmo código, guarda mais segura.
Reforce o caminho da saída
A saída do modelo é entrada não confiável. Se você a renderiza como HTML, escape-a. Se a analisa como JSON, valide antes de agir. Se a encaminha para sistemas downstream, decida explicitamente o que acontece quando a resposta vem vazia ou truncada.
Quando estiver pronto para explorar outros destinos de modelo na plataforma, eles usam a mesma estrutura de requisição — só a string model muda, então tudo o que você construiu acima continua valendo como está.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
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