Como usar gpt-6-astra através da API hiapi: exemplos de requisição executáveis em curl e Python

gpt-6-astra é um modelo de texto com capacidade de raciocínio, já disponível na hiapi, acessível através de um endpoint compatível com OpenAI: /v1/responses. Este guia fornece um exemplo de requisição executável em curl e Python, um requisito não óbvio que costuma causar problemas (é obrigatório usar streaming) e os padrões de boas práticas de produção necessários antes do lançamento.

O que você vai construir

Um script que envia um prompt para gpt-6-astra e lê a resposta do modelo através de uma resposta em streaming. Não há polling nem task ID — é uma chamada síncrona no estilo chat, apenas entregue na forma de Server-Sent Events em vez de uma resposta JSON bloqueante.

Pré-requisitos: uma chave de API da hiapi. Obtenha-a no console — todas as requisições abaixo precisam dela no cabeçalho Authorization.

Exemplo mínimo executável

gpt-6-astra suporta apenas um endpoint — POST /v1/responses — e aceita somente "stream": true. Independentemente de qualquer outro conteúdo no payload da requisição, enviar "stream": false retorna o erro 400 invalid_request; o modelo não tem modo não-streaming na hiapi. Projete seu cliente em torno da leitura do fluxo de eventos, e não em torno de uma única resposta JSON.

curl

curl -N -X POST "https://api.hiapi.ai/v1/responses" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Explain one practical way to check an AI-generated answer against its source." }
        ]
      }
    ],
    "stream": true,
    "store": false,
    "reasoning": { "effort": "medium" }
  }'

-N desativa o buffer de saída do curl, para que você veja os eventos assim que chegarem, em vez de receber tudo de uma vez no final. O tipo de resposta é text/event-stream, cada linha data: é um objeto JSON e há uma linha event: indicando seu tipo. Uma execução resumida resulta em algo assim:

event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress", ...}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"OK", ...}

event: response.completed
data: {"type":"response.completed","response":{"status":"completed","usage":{"input_tokens":12,"output_tokens":5,"total_tokens":17}, ...}}

O texto que você realmente quer chega em streaming através de eventos response.output_text.delta recorrentes — basta concatenar o campo delta em ordem para obter a resposta completa. O response.completed carrega o bloco final de usage para rastreamento de custos.

Python

import json
import requests

payload = {
    "model": "gpt-6-astra",
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain one practical way to check an AI-generated answer against its source.",
                },
            ],
        },
    ],
    "stream": True,
    "store": False,
    "reasoning": {"effort": "medium"},
}

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json=payload,
    stream=True,
    timeout=60,
) as resp:
    resp.raise_for_status()
    answer = []
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        event = json.loads(line[len(b"data: "):])
        if event.get("type") == "response.output_text.delta":
            answer.append(event["delta"])
        elif event.get("type") == "response.completed":
            usage = event["response"]["usage"]
            print(f"\n\ntokens: {usage['input_tokens']} in / {usage['output_tokens']} out")

    print("".join(answer))

resp.raise_for_status() captura falhas no nível HTTP (autenticação, limite de taxa) antes de você começar a analisar as linhas SSE — um stream malformado e uma requisição rejeitada são dois modos de falha distintos, e você precisa diferenciá-los no tratamento de erros.

Há dois campos no payload da requisição que merecem destaque:

• input é um array de objetos de mensagem, não uma string simples — cada entrada precisa de type: "message", um role e um array de conteúdo composto por partes tipadas (input_text para texto simples).
• reasoning.effort (low / medium / high) é opcional, mas controla quanto raciocínio interno o modelo realiza antes de responder. Se não for definido, a hiapi aplica um valor padrão; se você está equilibrando latência e qualidade da resposta, defina-o explicitamente.

Considerações para produção

• O streaming não é opcional. Não construa um caminho de código que volte para stream: false em retentativas — para esse modelo ele falhará todas as vezes. Se seu framework ou SDK assume uma única resposta JSON, envolva o laço SSE acima e armazene o texto concatenado antes de repassá-lo.
• Falhas de autenticação são explícitas. Chaves inválidas ou revogadas retornam HTTP 401, com "code": "permission_denied" no corpo do erro — verifique esse código em vez de fazer correspondência de padrões na string da mensagem, pois a string pode mudar.
• store: false torna a requisição stateless. A hiapi não mantém a resposta no servidor, portanto em chamadas subsequentes não há previous_response_id para encadear. Se você precisa de contexto de múltiplos turnos, reenvie os turnos anteriores como mensagens adicionais de input, em vez de depender do estado de conversa do servidor.
• Defina timeout no cliente, com ou sem streaming. Conexões SSE podem travar quando a conexão cai e nenhum dos lados envia um sinal de encerramento limpo; definir timeout no requests.post inicial (como no exemplo acima) evita a estagnação do primeiro byte, mas você também deve acompanhar a duração máxima do stream no seu próprio código, como defesa em profundidade.
• Reutilize prompt_cache_key para contexto de sistema repetido. O payload da resposta inclui um prompt_cache_key; se você envia as mesmas instruções em todas as chamadas, manter as requisições na mesma chave permite que a hiapi aplique cache de prompt, em vez de reprocessá-las a cada vez.

Leitura relacionada

• Página do modelo gpt-6-astra — referência completa de parâmetros e preços em tempo real
• Documentação da API hiapi — autenticação, outras famílias de modelos e a lista completa de endpoints
• Preços da hiapi — tarifas por token do gpt-6-astra e de todos os outros modelos

Perguntas frequentes

O gpt-6-astra suporta /v1/chat/completions? Não. Chamá-lo via /v1/chat/completions retorna o erro 400 unsupported_endpoint, sugerindo que você use /v1/responses. Na hiapi ele está registrado apenas para a Responses API.

Posso obter uma única resposta JSON em vez de um stream? Para esse modelo, não. "stream": false é rejeitado diretamente (invalid_request), independentemente de outros parâmetros definidos. Construa sua integração em torno do consumo do fluxo SSE e da montagem do texto final no cliente, como mostrado acima.

O gpt-6-astra suporta chamadas de ferramentas? O modelo aceita um array tools na estrutura de requisição da Responses API (exibido como um array vazio no objeto de resposta quando não definido). Se você for integrar chamadas de função, defina suas ferramentas da mesma forma que faria com qualquer modelo compatível com a OpenAI Responses API, e observe os eventos response.output_item.added com tipo function_call no stream.

Como são os erros de limite de taxa ou cota? Como outros erros da hiapi, eles são retornados em JSON, com type: "hiapi_error" e um campo code pelo qual você pode ramificar, além de um request_id — inclua esse ID ao contatar o suporte, para que eles possam rastrear a requisição exata no servidor.

Posso usar a mesma estrutura de requisição com outros modelos de raciocínio na hiapi? A estrutura de requisição /v1/responses é compartilhada entre as famílias de modelos da hiapi compatíveis com OpenAI Responses — basta trocar o campo model para mudar de modelo. A disponibilidade varia por modelo, então consulte a página do próprio modelo antes de assumir que ele está disponível.