Blogue

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

Nov 10, 2026
Folhas de papel em camadas em tons de creme e grafite recuando em degraus rasos, com uma folha terracota como destaque — arte de capa do tutorial gpt-5.6-sol@azure.
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 biblioteca requests.

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 Authorization antes 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 string gpt-5.6-sol@azure. É ela que roteia a requisição para o destino correto.
  • messages — array de objetos de mensagem. Cada objeto tem role e content. Os papéis convencionais são system (instruções que moldam o comportamento), user (entrada) e assistant (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, ajuste temperature ou top_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

  • -sS silencia a barra de progresso, mas ainda imprime erros — assim falhas não passam despercebidas.
  • -X POST define o método explicitamente, principalmente por legibilidade.
  • O cabeçalho Authorization carrega o bearer token vindo do ambiente.
  • Content-Type: application/json é obrigatório; sem ele o servidor não sabe como interpretar o corpo.
  • -d fornece 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:

  1. HIAPI_API_KEY está realmente definida no shell ou processo que faz a requisição? echo $HIAPI_API_KEY deve imprimir algo.
  2. O cabeçalho contém a palavra literal Bearer e exatamente um espaço antes da chave?
  3. A chave trouxe uma quebra de linha ou aspas do copiar e colar? Exporte-a novamente de forma limpa.
  4. 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, use json=payload.
  • Se mencionar messages, verifique se você passou um array de objetos com role e content, e não strings soltas.
  • Se mencionar model ausente, 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 →

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