Blogue

Tutorial

Como usar o gpt-6-sol via API HiAPI: curl, Python e uma requisição que funciona

Nov 12, 2026
Arte de capa arquitetônica com planos de concreto cinza quente cortados por uma sombra angular azul-ardósia e uma fina costura verde-sálvia.
Nesta página

O que você precisa antes da primeira chamada

Antes de escrever qualquer código, prepare três coisas. O restante deste tutorial se apoia nisso.

Uma chave de API HiAPI

Toda requisição enviada à API HiAPI precisa ser autenticada com uma chave de API. Crie uma chave no painel da sua conta HiAPI e guarde-a em um local seguro, de preferência em uma variável de ambiente, e não em um arquivo de código-fonte. Trate-a como uma senha: se vazar, rotacione-a imediatamente.

export HIAPI_API_KEY="your-api-key-here"

O endpoint base

Todas as chamadas deste guia vão para o endpoint base da API HiAPI, e cada modelo é acessado pelo mesmo formato de caminho de requisição. Você não precisa de um host ou SDK separado para cada modelo — o gpt-6-sol é selecionado no corpo da requisição, e não alterando as configurações do cliente.

Um cliente HTTP

Você precisa de um dos seguintes:

  • curl, disponível por padrão na maioria dos sistemas Linux e macOS e no terminal do Windows.
  • Python com a biblioteca requests instalada (pip install requests), ou a biblioteca padrão urllib, se preferir não adicionar dependências.

Nenhuma outra ferramenta é necessária. Você não precisa de um SDK de fornecedor específico nem de instalar nada relacionado ao modelo. Basta conseguir enviar uma requisição HTTPS POST com corpo JSON e cabeçalhos para chamar o gpt-6-sol.

Um hábito que vale a pena cultivar agora: mantenha um arquivo de rascunho registrando a requisição funcional que você está usando, para que, quando algo falhar, você possa comparar a chamada que falhou com a última chamada que sabidamente funcionava.

Autenticar com uma chave bearer

A autenticação é o ponto mais propenso a erros na primeira chamada, então vale a pena tratá-la com cuidado.

O cabeçalho Authorization

A API HiAPI espera sua chave no cabeçalho bearer padrão:

Authorization: Bearer $HIAPI_API_KEY

É a palavra literal Bearer, um espaço e depois a chave. Erros comuns incluem: omitir a palavra Bearer, arrastar quebras de linha extras ao copiar o valor, ou colocar aspas na chave quando o cliente já adiciona aspas.

O tipo de conteúdo precisa ser JSON

A requisição carrega um corpo JSON, então o cabeçalho de tipo de conteúdo precisa corresponder:

Content-Type: application/json

Se esse cabeçalho estiver ausente, alguns servidores ainda analisam o corpo, mas você não deve contar com isso — defina-o explicitamente. Um tipo de conteúdo incompatível é uma causa comum de erros de validação da requisição que parecem erros no corpo.

Conjunto mínimo de cabeçalhos

Você só precisa dos dois cabeçalhos acima:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Mantenha o conjunto de cabeçalhos o menor possível. Cabeçalhos especulativos emprestados de exemplos de outras APIs têm mais chance de causar confusão do que de ajudar. Depois que uma chamada com esses dois cabeçalhos funcionar, você terá uma linha de base limpa para comparar mais tarde.

Evite colar a chave diretamente no histórico do shell ou em arquivos commitados. Referenciar a variável de ambiente como acima mantém a chave fora do código-fonte e do histórico do terminal.

Montar o corpo da requisição para o gpt-6-sol

O corpo da requisição é JSON, e seu núcleo é uma lista de mensagens. Comece com a configuração mínima; só adicione campos depois que a chamada funcionar.

Payload mínimo da requisição

O corpo útil mínimo precisa especificar o modelo e fornecer uma mensagem:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "Explique em uma frase o que é um API bearer token." }
  ]
}

Dois campos entram em jogo aqui:

  • model seleciona o gpt-6-sol, de modo que o mesmo endpoint possa servir outros modelos depois.
  • messages é uma lista ordenada de turnos de conversa. Cada item tem um role (system, user ou assistant) e um content em string.

Padrões seguros e itens opcionais

Trate model e messages como obrigatórios. Todo o resto é opcional e deve ser adicionado de forma consciente:

  • Uma mensagem system colocada no início de messages define o comportamento ou o tom da conversa. É uma mensagem comum, não um campo de nível superior separado.
  • Se necessário, o controle de comprimento da saída é definido como parâmetro no corpo da requisição. Adicione-os somente quando a saída padrão for curta ou longa demais para o seu caso de uso.
  • Parâmetros de amostragem alteram a forma da saída, não a validade. Evite alterá-los ao depurar uma chamada com falha, pois eles não corrigem erros de autenticação ou de estrutura do corpo.

Uma regra prática

Quando houver falha, o payload deve ficar o mais próximo possível do exemplo mínimo. Remova os campos opcionais um a um até a chamada funcionar, depois adicione-os de volta. Isso isola o problema rapidamente: um parâmetro ruim é mais fácil de encontrar do que um parâmetro ruim enterrado entre cinco parâmetros bons.

Enviar uma requisição funcional com curl

A seguir está um comando completo que pode ser executado diretamente, desde que sua chave esteja exportada. Ele usa um caminho de endpoint de exemplo compatível com as convenções da API HiAPI descritas acima.

curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Explique em uma frase o que é um API bearer token." }
    ]
  }'

Defina HIAPI_BASE_URL como o endpoint base do seu painel HiAPI. Os flags são importantes:

  • -X POST define o método; essas chamadas são todas POST.
  • -H adiciona cada cabeçalho, um por linha.
  • -d fornece o corpo JSON. As aspas simples impedem a interpolação pelo shell.
  • -sS mantém a saída silenciosa, mas ainda mostra erros, que é exatamente o que se precisa ao usar em scripts.

Ler a resposta

Uma resposta bem-sucedida é JSON. Normalmente você verá um objeto de nível superior contendo o nome do modelo e uma lista de choices, cada choice com uma mensagem cujo content guarda o texto gerado. Leia a estrutura antes do corpo: confirme que o objeto pode ser analisado e depois localize o campo content.

Para melhorar a legibilidade, canalize para uma ferramenta de formatação JSON:

... | python -m json.tool

Se o seu terminal em vez disso imprimir um objeto de erro, a chamada não foi bem-sucedida — pule para a seção de erros em vez de ajustar o prompt. Quando a requisição nem chegou ao modelo, o problema não está no prompt.

Enviar a mesma requisição com Python

O payload que você acabou de validar no curl pode ser migrado diretamente. Mantenha o corpo exatamente igual, para que as correções validadas no terminal também se apliquem no código.

import os
import requests

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

payload = {
    "model": "gpt-6-sol",
    "messages": [
        {"role": "user", "content": "Explique em uma frase o que é um API bearer token."}
    ],
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    timeout=60,
)

response.raise_for_status()
data = response.json()

for choice in data.get("choices", []):
    message = choice.get("message", {})
    print(message.get("content", ""))

Por que esta versão é mais segura no código da aplicação

  • O corpo é um dicionário. Quando você passa json=payload, o requests o serializa e define o tipo de conteúdo para você, mas manter o cabeçalho explícito evita surpresas ao trocar de cliente.
  • A chave vem de uma variável de ambiente. Nenhum segredo está embutido no código, então o arquivo pode ser commitado.
  • raise_for_status() executa primeiro. Respostas fora da faixa 2xx lançam imediatamente uma exceção, antes que você tente ler campos inexistentes no corpo de erro.
  • Um timeout está definido. Sem timeout, uma conexão travada pode deixar um processo de trabalho pendurado indefinidamente.

O laço que percorre choices também protege contra chaves ausentes, o que torna o exemplo tolerante a respostas com pouca ou nenhuma saída. Construa seu wrapper de produção em torno deste esqueleto: validar, enviar, verificar o status, depois analisar.

Receber respostas em streaming em vez de esperar

Por padrão, a API retorna a resposta completa em um único JSON. Para saídas longas ou interfaces interativas, você pode, em vez disso, solicitar que a resposta seja entregue progressivamente durante a geração.

O interruptor de streaming

O streaming é ativado por um flag no corpo da requisição, não por um endpoint diferente:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "Escreva um texto curto sobre códigos de status HTTP." }
  ],
  "stream": true
}

Adicione este flag por último, depois que a chamada não-streaming já estiver funcionando. Ele altera a forma como a resposta é organizada, não se a requisição é válida.

Consumir a saída incremental

Com o streaming ativado, a resposta não é mais um único documento JSON. Ela chega como uma série de eventos, normalmente separados por linha, cada evento carregando um pequeno trecho de saída. Seu cliente precisa lê-los à medida que chegam, em vez de chamar .json() no corpo inteiro da resposta.

with requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    stream=True,
    timeout=60,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))

No terminal, o mesmo interruptor se comporta de forma diferente da chamada não-streaming: a saída aparece progressivamente, então um pipe truncado pode parecer uma requisição com falha, quando na verdade só o stream foi interrompido.

Qual usar

Use não-streaming para tarefas em lote, testes e qualquer caso em que você precise do objeto completo de uma vez. Use streaming quando alguém estiver esperando o texto ou quando a saída for longa o suficiente para que a latência seja perceptível. Mantenha os dois caminhos no código, porque o caminho não-streaming é mais fácil de depurar.

Ler e corrigir códigos de erro comuns

Diagnostique primeiro pelo código de status e depois pelo corpo da resposta. Não altere o modelo nem reescreva o prompt antes de ter certeza de qual camada falhou.

401 Unauthorized

Causa: chave ausente, malformada ou revogada. Correção: confirme que o cabeçalho está exatamente como Authorization: Bearer <key>, verifique se há caracteres de espaço ocultos ou variáveis de ambiente desatualizadas e valide se a chave ainda está ativa no seu painel. Imprima o comprimento da variável em vez do valor para detectar erros de variável vazia.

400 Bad Request

Causa: o corpo não pode ser analisado ou faltam campos obrigatórios. Correção: envie novamente o payload mínimo contendo apenas model e messages. Valide o JSON com python -m json.tool antes de enviar; vírgulas finais ou erros de digitação em model são causas comuns. Confirme que Content-Type é application/json.

403 Forbidden

Causa: a chave é válida, mas falta permissão de acesso ao recurso solicitado. Correção: verifique se sua conta tem acesso ao gpt-6-sol e se o nome do modelo no corpo da requisição corresponde ao configurado na sua conta.

404 Not Found

Causa: caminho de URL incorreto, geralmente por erro de digitação no endpoint ou caminho base ausente ou duplicado. Correção: compare a URL completa caractere por caractere com uma chamada curl funcional.

429 Too Many Requests

Causa: você está enviando requisições mais rápido do que a conta permite. Correção: aplique backoff e tente novamente com atrasos crescentes. Siga qualquer orientação de retry nos cabeçalhos da resposta e nunca tente novamente em um laço apertado — isso só piora o problema. Diferencie isso de 5xx, que indica um problema do lado do servidor, não da sua taxa de requisições.

Erros 5xx do servidor

Causa: o serviço não consegue processar uma requisição que de outra forma seria válida. Correção: tente novamente com backoff; se o problema persistir, capture o corpo da resposta e o ID da requisição e evite alterar o payload, já que ele estava funcionando.

Ordem de depuração reproduzível

  1. Código de status — é problema de autenticação, caminho ou corpo da requisição?
  2. Corpo da resposta — ele aponta o campo com problema?
  3. Estrutura do payload — volte ao exemplo mínimo.
  4. Só por último considere o prompt ou os parâmetros.

Essa ordem encurta continuamente o tempo entre a falha e a correção. Assim que suas chamadas estiverem estáveis, mantenha as versões curl e Python funcionais lado a lado, para que cada teste futuro comece de um estado conhecido como funcional.

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