Como usar o Claude Sonnet 4.6 através da API hiapi

O que você vai construir

Um exemplo de integração funcional: chamar o Claude Sonnet 4.6 através da API Chat Completions compatível com OpenAI da hiapi — uma única requisição retorna uma conclusão real, e o exemplo também abrange os padrões de nível de produção que você usará de fato depois de validar a demonstração (streaming, chamada de ferramentas, pensamento adaptativo).

Pré-requisitos: uma chave de API hiapi. Obtenha-a no console — é apenas uma string sk-..., e a mesma chave funciona para todos os modelos habilitados na sua conta, não apenas este.

Todo o conteúdo abaixo foi verificado na prática contra a API em tempo real no momento em que este texto foi escrito.

Exemplo mínimo funcional

O Claude Sonnet 4.6 é um modelo de texto no endpoint padrão Chat Completions — e não o fluxo assíncrono /v1/tasks que a hiapi usa para modelos de imagem/vídeo/áudio. Uma requisição, uma resposta, sem polling.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Explain how an HTTP cache works in three short paragraphs."}
    ]
  }'

Resposta (recortada):

{
  "id": "msg_bdrk_011Cf8Bo25qCVFFQF5ETk8Wf",
  "model": "claude-sonnet-4-6",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 13, "completion_tokens": 4, "total_tokens": 17 }
}

A mesma chamada em Python usando apenas requests:

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-sonnet-4-6",
        "messages": [
            {"role": "user", "content": "Explain how an HTTP cache works in three short paragraphs."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

Como a estrutura é compatível com OpenAI, este código também funciona com os SDKs oficiais openai para Python/JS sem modificações — basta apontar base_url para https://api.hiapi.ai/v1 e passar sua chave hiapi.

Padrões de nível de produção

Streaming

Defina "stream": true e leia os Server-Sent Events. Cada bloco de dados carrega um fragmento de delta.content; o stream termina no último bloco com finish_reason: "stop", seguido do sentinela [DONE]:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true
  }'

data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":"Here"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":" you"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Acumule choices[0].delta.content entre os blocos de dados para reconstruir o texto completo.

Chamada de ferramentas

Declare funções da mesma forma que no OpenAI e, na próxima rodada, reenvie a mensagem de tool_calls do assistente junto com uma mensagem de resultado tool:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_task_status",
        "description": "Look up a task by ID.",
        "parameters": {
          "type": "object",
          "properties": {"task_id": {"type": "string"}},
          "required": ["task_id"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

A resposta retorna finish_reason: "tool_calls", com o nome da função e os argumentos codificados em JSON em choices[0].message.tool_calls. Execute sua função localmente e, na próxima requisição, envie o resultado de volta como uma mensagem role: "tool" com o tool_call_id correspondente — o modelo continua a partir daí.

Pensamento adaptativo

O Claude Sonnet 4.6 suporta uma etapa de raciocínio habilitada sob demanda. Adicione "thinking": {"type": "adaptive"} e escolha o nível de esforço via output_config.effort (low, medium, high ou max):

{
  "model": "claude-sonnet-4-6",
  "messages": [{"role": "user", "content": "Compare two approaches and state the trade-offs."}],
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "high"}
}

Um traço de raciocínio legível é retornado em choices[0].message.reasoning_content; o array bruto reasoning_details carrega metadados de assinatura e, se você for continuar a conversa e entrar em chamada de ferramentas, deverá preservá-lo exatamente como está — não o analise, exiba ou invente, apenas repasse-o diretamente na próxima requisição.

Tratamento de erros

Falhas de autenticação retornam HTTP 401 com o envelope de erro hiapi_error:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Verifique response.status_code antes de acessar response.json()["choices"] e, se precisar escalar o caso, registre error.request_id — a equipe de suporte pode usá-lo para rastrear a chamada específica.

Idempotência e novas tentativas

Chamadas ao Chat Completions não são idempotentes por ID de requisição como os jobs de /v1/tasks — uma requisição repetida é uma nova conclusão. Para tráfego de produção, envolva as chamadas em novas tentativas com backoff para lidar com 5xx/timeouts, e defina um teto em max_tokens para evitar cobranças ilimitadas causadas por uma tempestade de novas tentativas.

Leitura relacionada

• Referência do modelo Claude Sonnet 4.6 — tabela completa de parâmetros, schema de resposta e mais exemplos de requisição diretamente da documentação da hiapi.
• Autenticação — como as chaves de API hiapi funcionam e como rotacioná-las.
• Preços hiapi — tarifas por token em tempo real do Claude Sonnet 4.6 e de todos os outros modelos habilitados.

Perguntas frequentes

claude-sonnet-4-6 é o ID de modelo exato que devo enviar? Sim — envie a string simples claude-sonnet-4-6 no campo model. A hiapi o roteia para o Claude Sonnet 4.6 da Anthropic por trás de uma interface compatível com OpenAI, portanto nenhum prefixo específico de provedor é necessário.

Isso usa o mesmo fluxo /v1/tasks que os modelos de imagem e vídeo da hiapi? Não. Modelos de texto como o Claude Sonnet 4.6 usam o endpoint síncrono POST /v1/chat/completions — uma requisição, uma resposta (ou um stream SSE). O /v1/tasks é usado apenas para modelos de mídia (imagem, vídeo, áudio), que são executados de forma assíncrona e retornam uma URL consultável ou callback.

Posso usar o SDK da OpenAI em vez de curl/requests nativos? Sim. Como o endpoint é compatível com OpenAI, basta apontar o base_url do SDK oficial openai para https://api.hiapi.ai/v1 e usar sua chave hiapi como api_key — nenhuma outra alteração de código é necessária para chat básico, streaming ou chamada de ferramentas.

O Claude Sonnet 4.6 suporta entrada de imagens? Sim, por meio de blocos de conteúdo — defina o content da mensagem como um array contendo um bloco com type: "image_url", cujo image_url.url aponta para uma URL pública de imagem, junto com seus blocos de texto.

O que acontece se eu omitir thinking? De acordo com a versão atual, o pensamento adaptativo é habilitado sob demanda — omita o campo thinking (ou defina thinking.type como disabled) e o modelo responderá diretamente, sem reasoning_content na resposta.

Onde vejo os preços atuais antes de executar tarefas em grande escala? A página de preços da hiapi lista as tarifas por token em tempo real do Claude Sonnet 4.6 — consulte-a antes de definir um orçamento, pois as tarifas podem mudar e este texto não fixa um número que pode ficar desatualizado.