Como usar a API grok-4.6: cURL, Python e uma requisição funcional

grok-4.6 é um modelo de chat ajustado para raciocínio, disponível através da API hiapi. Diferente dos modelos de imagem e vídeo da hiapi, ele não usa o pipeline assíncrono /v1/tasks — é uma interface síncrona de chat completions compatível com OpenAI, então você obtém diretamente uma resposta HTTP normal (ou um stream SSE), sem polling. Este artigo apresenta primeiro uma requisição mínima funcional e depois aborda o que você realmente precisa em produção: streaming, chamada de ferramentas, modo JSON e tratamento de erros.

O que você precisa preparar

• Uma chave de API hiapi. Se você ainda não tem uma, obtenha no console — cada requisição abaixo exige que ela seja enviada no cabeçalho Authorization: Bearer sk-....
• Qualquer cliente HTTP. Os exemplos usam curl e requests do Python; a estrutura JSON é a mesma independentemente da linguagem.
• Nenhum SDK necessário. O formato de requisição/resposta do grok-4.6 segue de perto a convenção de chat completions da OpenAI, então ferramentas compatíveis com OpenAI geralmente funcionam, mas a hiapi oferece seu próprio endpoint de chat completions, e não um endpoint proprietário — aponte seu cliente para https://api.hiapi.ai/v1/chat/completions e use o ID de modelo puro grok-4.6.

Requisição mínima funcional

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "Explique em uma frase a função do filtro de Kalman."}
    ]
  }'

Uma resposta bem-sucedida se parece com isto:

{
  "id": "b6c018d3-218e-9b06-aa12-5afc02e21b5c",
  "object": "chat.completion",
  "model": "grok-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "O filtro de Kalman estima o estado real de um sistema ao longo do tempo combinando medições ruidosas com um modelo de previsão e ponderando cada um pela sua incerteza."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 31,
    "total_tokens": 55
  }
}

O texto da resposta fica em choices[0].message.content, como em qualquer API de chat no estilo OpenAI.

Abaixo está a mesma chamada em Python usando requests:

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [
            {"role": "user", "content": "Explique em uma frase a função do filtro de Kalman."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

Ajustes de raciocínio do grok-4.6

grok-4.6 é um modelo de raciocínio: antes de escrever a resposta final, ele gasta tokens extras “pensando”, e esses tokens de raciocínio são cobrados como tokens de saída (consulte as tarifas atuais). Você pode controlar a quantidade de raciocínio com reasoning_effort, que aceita um dos valores low, medium, high ou xhigh (se omitido, a API usa high por padrão):

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Cumprimente em cinco palavras."}],
    "reasoning_effort": "low"
  }'

Respostas não-streaming fornecem o traço de raciocínio do modelo em message.reasoning_content, separado do message.content final. Para tarefas curtas e de baixa latência, reduza para low ou medium; para problemas de múltiplas etapas, high ou xhigh trocam latência e tokens por melhores respostas.

Resposta em streaming

Defina "stream": true para ler a resposta como Server-Sent Events, em vez de esperar pela conclusão completa:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Conte de 1 a 5."}],
    "stream": true
  }'

Cada linha é um bloco de dados data: {...}. Os tokens de raciocínio são transmitidos via choices[0].delta.reasoning_content, depois os tokens da resposta via choices[0].delta.content, e o stream termina com o literal data: [DONE]:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"Listar"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1, 2"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Em Python, requests pode iterar o stream linha a linha:

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [{"role": "user", "content": "Conte de 1 a 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[len(b"data: "):]
        if payload == b"[DONE]":
            break
        chunk = json.loads(payload)
        delta = chunk["choices"][0]["delta"]
        if "content" in delta:
            print(delta["content"], end="", flush=True)

Chamada de ferramentas

grok-4.6 suporta chamada de funções no estilo OpenAI: passe um array tools e use tool_choice: "auto" para deixar o modelo decidir quando chamar uma ferramenta.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Como está o clima em Tóquio?"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Obter o clima atual de uma cidade",
          "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Quando o modelo decide chamar a ferramenta, finish_reason retorna "tool_calls", e os argumentos chegam como uma string JSON que você mesmo precisa analisar:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_...",
            "type": "function",
            "function": {"name": "get_weather", "arguments": "{\"city\":\"Tokyo\"}"}
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Execute sua função e então anexe uma mensagem com role: "tool" (contendo o resultado da execução e o tool_call_id correspondente) a messages, e envie a conversa de volta para obter a resposta final em linguagem natural.

Modo JSON

Se você quer analisar a resposta sem a ida e volta da chamada de ferramentas, defina response_format:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "system", "content": "Responda com um objeto JSON contendo as duas chaves \"city\" e \"country\"."},
      {"role": "user", "content": "Onde fica a Torre Eiffel?"}
    ],
    "response_format": {"type": "json_object"}
  }'

message.content é retornado como uma string JSON (ainda dentro do envelope normal de chat completions), e você a analisa do seu lado com json.loads(...). Certifique-se de instruir o modelo no prompt a realmente gerar JSON — response_format restringe o formato da saída, mas não constrói o schema por você.

Práticas para produção

• Trate os códigos de erro documentados. Chave inválida ou ausente retorna HTTP 401, com corpo {"error":{"code":"permission_denied","message":"...","request_id":"...","type":"hiapi_error"}}. Saldo insuficiente retorna 402; ID de modelo inválido ou parâmetro mal formatado retorna 400. Verifique o código de status primeiro e registre o request_id do corpo de erro — é exatamente a informação que você usará se precisar reportar um problema.
• Use retry com backoff para 429 e 503. A hiapi aplica limites de taxa por conta; 429 significa que você excedeu o limite, 503 significa que o modelo está temporariamente indisponível. Ambos são adequados para retry com backoff exponencial limitado (por exemplo, 1s, 2s, 4s, desistindo após algumas tentativas), em vez de um loop apertado.
• Defina timeout de requisição. Com intensidade de raciocínio high ou xhigh, o tempo é significativamente maior que com low; configure o timeout do cliente de acordo com o nível de intensidade usado, em vez de usar uma única constante global.
• Prefira streaming em qualquer cenário voltado ao usuário. Chamadas não-streaming bloqueiam até a resposta completa (incluindo todos os tokens de raciocínio) estar pronta; o streaming entrega os primeiros tokens à sua UI imediatamente e permite mostrar um estado de “pensando” quando os incrementos de reasoning_content chegam antes da resposta final.
• Não codifique chaves no código. Carregue de variáveis de ambiente ou de um gerenciador de segredos, nunca do controle de versão — os exemplos acima leem de $HIAPI_API_KEY / os.environ["HIAPI_API_KEY"] justamente por isso.

Para a referência completa de parâmetros (incluindo cada campo aceito pelo grok-4.6), consulte a página do modelo e a documentação do grok-4.6.

Perguntas frequentes

O grok-4.6 na hiapi é compatível com o SDK da OpenAI? As estruturas de requisição e resposta seguem a convenção de chat completions da OpenAI (messages, choices[0].message.content, incrementos de streaming, chamada de ferramentas), então a maioria das ferramentas compatíveis com OpenAI que permitem sobrescrever a URL base e o ID de modelo deve funcionar. Aponte a URL base para https://api.hiapi.ai/v1 e use grok-4.6 como ID de modelo.

Por que minha resposta é mais lenta que a de outros modelos? grok-4.6 gasta tokens em uma etapa de raciocínio interno antes de responder, e esses tokens são cobrados como tokens de saída. Para chamadas sensíveis à latência, reduza reasoning_effort para low ou medium, ou use streaming, assim você não precisa esperar pela resposta inteira de uma vez.

O que significa reasoning_content e posso ocultá-lo do usuário? É o traço de raciocínio intermediário do modelo, retornado separadamente de content (ou como delta.reasoning_content durante o streaming). Você pode perfeitamente não renderizá-lo na UI — apenas content é a resposta final.

Recebi 401 e permission_denied — o que deu errado? Seu cabeçalho Authorization está ausente, mal formatado, ou a chave é inválida/foi revogada. Verifique novamente se você enviou Authorization: Bearer sk-... e se está usando uma chave válida do console.

Posso usar chamada de funções e modo JSON do grok-4.6 na mesma requisição? tools/tool_choice e response_format são parâmetros independentes e podem ser definidos juntos, mas se o modelo decidir chamar uma ferramenta, o finish_reason dessa rodada será "tool_calls" e message.content pode estar vazio — trate primeiro a chamada de ferramentas e depois solicite a resposta final em formato JSON em rodadas subsequentes.

Como controlar o custo? Tokens de raciocínio contam como tokens de saída, então o custo varia com reasoning_effort e o comprimento da resposta. Antes de executar tarefas de alta carga, consulte as tarifas atuais por token na página de preços.