Como chamar gpt-5.6-terra@azure pela API da HiAPI: guia com curl e Python

O que gpt-5.6-terra@azure significa em uma requisição HiAPI

Em uma requisição HiAPI, gpt-5.6-terra@azure é um identificador de modelo — você o coloca no campo model do corpo da requisição de chat. Essa é toda a convenção do seu lado. Você não precisa montar URLs específicas do provedor, nem trocar o SDK, nem alterar a estrutura do corpo da requisição.

O sufixo @azure é metadado de roteamento: ele informa à HiAPI qual backend deve tratar as requisições dessa variante do modelo. Todo o restante do corpo — messages, temperature, max_tokens, stream, tools — mantém a estrutura padrão de chat-completions que você já conhece. Isso importa na prática: se você já tem uma requisição funcional que chama outros modelos na HiAPI, migrar para gpt-5.6-terra@azure normalmente exige mudar uma única linha.

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

Dois hábitos fazem bugs relacionados ao ID do modelo quase desaparecerem:

• Trate o ID como uma string opaca. Copie exatamente como está, incluindo o @ e o sufixo em minúsculas. Sem espaços, sem alterar maiúsculas e minúsculas.
• Coloque-o na configuração, não espalhado pelo código. Usar uma constante ou variável de ambiente transforma testes A/B entre IDs de modelo em mudança de configuração, não em refatoração.

Como o sufixo é responsável pelo roteamento, você não deve inferir nada sobre a stack subjacente apenas a partir do ID. Latência, limites e parâmetros suportados são propriedades da forma como a HiAPI expõe esse modelo, então valide o comportamento na prática com uma requisição pequena antes de gravar suposições na sua aplicação.

Pré-requisitos e preparação da chave

Antes da primeira chamada, confirme três coisas:

1. Uma conta HiAPI. Você precisa estar logado para criar credenciais e consultar no console as informações atuais de modelos e preços.
2. Uma chave de API. Gere no console e guarde em local seguro — trate-a como senha. Este guia não assume um formato específico de chave; qualquer string que o console forneça é o valor a colocar no cabeçalho Authorization.
3. Um cliente HTTP. Use curl para validações rápidas e Python 3 com requests ou o SDK compatível com OpenAI para o código da aplicação.

Mantenha a chave fora dos arquivos-fonte

Use variáveis de ambiente. O padrão é o mesmo em todas as plataformas:

export HIAPI_API_KEY="your-key-here"

Depois referencie em tempo de execução. No shell: "$HIAPI_API_KEY". Em Python: os.environ["HIAPI_API_KEY"]. Em CI, use o armazenamento de segredos do seu provedor em vez de commitar um arquivo .env.

Se você colar a chave no terminal para depurar, lembre-se de que ela pode ficar no histórico do shell — se for uma credencial real, rotacione-a depois. Para desenvolvimento local, usar uma chave descartável apenas de teste é mais fácil de gerenciar do que reutilizar credenciais de produção.

Confirme sua Base URL e o endpoint

A HiAPI oferece um endpoint de chat completions compatível com OpenAI. Obtenha a base URL e o caminho na documentação do seu console e mantenha-os consistentes entre curl e Python — a maioria dos relatos de “funciona no curl mas não no Python” acaba sendo barra final ou segmento de caminho faltando.

Uma requisição curl funcional

Abaixo está a chamada mínima correta. Substitua a base URL pela que aparece no seu console e garanta que HIAPI_API_KEY esteja exportada.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

Campo a campo:

• -sS silencia a barra de progresso, mas ainda exibe erros. Se quiser ver cabeçalhos de resposta junto com o corpo, adicione -i.
• Authorization: Bearer $HIAPI_API_KEY autentica a requisição. O prefixo Bearer e o espaço são obrigatórios.
• Content-Type: application/json — se omitido, muitos servidores rejeitam a requisição antes mesmo de analisar o corpo.
• model — o ID exato gpt-5.6-terra@azure.
• messages — array ordenado. system define o comportamento; user carrega o prompt. Em conversas de múltiplos turnos, acrescente turnos assistant e user em ordem.
• max_tokens — limite superior do tamanho da resposta. Mantenha pequeno em validações rápidas, para que falhas custem pouco e sejam rápidas.

Uma resposta bem-sucedida é um JSON com um array choices; o texto que você precisa está em choices[0].message.content. Nas primeiras vezes, passe a saída por um formatador JSON para enxergar a estrutura, em vez de encarar uma linha longa.

Assim que essa requisição funcionar, salve-a como um script shell que lê a chave de variáveis de ambiente. Assim você tem um health check repetível para rodar sempre que alterar o ID do modelo ou os parâmetros.

A requisição Python equivalente

O corpo da requisição é idêntico — só muda o transporte. Com requests:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

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

Três detalhes que vale manter: use json=payload em vez de serializar manualmente (ele configura cabeçalhos e codificação para você), sempre defina timeout e chame raise_for_status(), para que 4xx ou 5xx apareçam como exceção, em vez de gerar IndexError quando você tentar indexar um corpo de erro.

Estilo com SDK do provedor

Como o endpoint é compatível com OpenAI, um SDK configurado com base URL personalizada produz a mesma requisição:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

Mostrar as duas formas importa porque o ID do modelo é a única variável que identifica qual modelo atende você. O resto é o pipeline comum de chat-completions, então você pode alternar entre HTTP bruto e SDK sem reescrever a lógica.

Adicionando streaming e chamada de ferramentas

Ambos os recursos são incrementais. Você não reescreve a requisição base — adiciona campos e muda a forma de consumir a resposta.

Streaming

Defina "stream": true no corpo da requisição:

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

A resposta passa a ser uma série de server-sent events, em vez de um único objeto JSON. Cada chunk carrega um delta com um fragmento de conteúdo; no primeiro e no último chunk, delta.content pode ser None, então proteja-se antes de concatenar. O mesmo vale com HTTP bruto — leia o corpo linha a linha, remova o prefixo data: , ignore [DONE] e faça o parse do JSON de cada linha.

Chamada de ferramentas

Descreva as ferramentas na requisição e deixe o modelo decidir quando chamá-las:

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

Quando o modelo quiser chamar uma ferramenta, choices[0].message conterá um array tool_calls, em vez de texto puro. Cada item tem um id e um function com name e arguments (uma string JSON que você precisa fazer o parse). Execute sua função e então envie o resultado de volta como uma mensagem com role: "tool", levando o tool_call_id correspondente e a saída serializada — depois faça outra requisição para obter a resposta final.

tool_choice aceita "auto" (o modelo decide), "none" (apenas texto) ou uma função específica. Streaming e ferramentas podem ser combinados, mas os argumentos da chamada de ferramenta chegam em fragmentos ao longo dos chunks, e você precisa acumulá-los antes de fazer o parse — primeiro faça funcionar a chamada de ferramenta sem streaming.

Diagnosticando erros comuns de requisição

Depure nesta ordem; cada passo isola uma camada, para você não perseguir dois problemas ao mesmo tempo.

1. Autenticação (401 / 403)

Causa mais provável: chave ausente, prefixo Bearer perdido ou variável de ambiente expandindo para string vazia. Exiba como o cabeçalho está sendo montado sem imprimir a chave inteira e confirme que a variável está definida no mesmo shell ou processo que executa a requisição.

2. Endpoint e caminho (404)

404 normalmente significa caminho errado — erro de digitação, /v1 faltando ou barra final sobrando onde não deveria. Copie a URL exata do console em vez de digitá-la novamente.

3. ID do modelo (400 com mensagem sobre o modelo)

O ID deve corresponder exatamente: gpt-5.6-terra@azure. Erros comuns incluem mudança de maiúsculas/minúsculas, ausência de @azure ou espaços extras vindos de copiar e colar. Se a mensagem disser que o modelo é desconhecido, compare caractere a caractere a string configurada com a lista do console antes de suspeitar de falha do serviço.

4. Corpo da requisição mal formatado (400 / 422)

Se o erro mencionar o corpo, verifique primeiro a validade do JSON — vírgulas finais ou aspas não escapadas são culpados comuns. Depois confira nomes de campos (é messages, não message) e papéis (system, user, assistant, tool). max_tokens deve ser número e tools deve ser um array de objetos com estrutura correta.

5. Tratar resposta em streaming como JSON comum

Se a saída vier vazia, ilegível ou lançar erro de parse, você provavelmente pediu stream: true e tentou interpretar a resposta como um único documento JSON. Leia como fluxo de eventos, ignore [DONE] e proteja-se contra deltas None.

6. Timeout do cliente

Gerações longas podem ultrapassar o timeout HTTP padrão. Aumente-o explicitamente no cliente ou mude para streaming, para que os bytes comecem a chegar imediatamente.

Checklist de reprodução rápida

• Execute a chamada curl mínima. Se funcionar, o problema está no seu código.
• Se falhar, tente novamente em um shell novo com sua chave e o ID do modelo.
• Registre o código de status HTTP e o corpo da resposta — corpos de erro trazem detalhes de diagnóstico.
• Só depois que essas verificações passarem é que você deve suspeitar de problema no servidor a ponto de escalar o caso.

Com uma requisição funcional, o loop de streaming e este checklist, gpt-5.6-terra@azure se comporta na sua stack como qualquer outro modelo de chat — e trocar de modelo vira uma linha de mudança na configuração.