Tutorial

Como usar o Claude Opus 4.8 pela API hiapi

Sep 21, 2026

O que você vai construir

Uma integração funcional que chama o Claude Opus 4.8 pela API Chat Completions compatível com OpenAI da hiapi — o modelo de topo da linha Claude 4.8 atual da Anthropic. Uma única requisição retorna uma conclusão real, junto com os padrões de produção de que você precisará depois que a demo funcionar (streaming, chamada de ferramentas, raciocínio adaptativo).

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

Todo o conteúdo abaixo foi executado de fato contra a API em produção no momento da escrita.

Exemplo mínimo funcional

O Claude Opus 4.8 é um modelo de texto no endpoint padrão Chat Completions — 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-opus-4-8",
    "messages": [
      {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
    ],
    "max_tokens": 1024
  }'

Resposta (resumida):

{
  "id": "msg_011CfFm8abLRcYtLVSky81As",
  "model": "claude-opus-4-8",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14 }
}

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-opus-4-8",
        "messages": [
            {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
        ],
        "max_tokens": 1024,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

Envie diretamente o ID puro do modelo claude-opus-4-8 — sem prefixo de provedor, sem sufixo de roteamento. A hiapi lista duas rotas de backend para esse modelo (default e aws) para fornecer redundância, mas ambas compartilham o mesmo ID de modelo; você não precisa escolher entre elas.

Como o formato da requisição é compatível com OpenAI, isso também funciona sem alterações com os SDKs oficiais openai para Python/JS — basta apontar o base_url para https://api.hiapi.ai/v1 e passar sua chave hiapi.

Padrões de produção

Streaming

Defina "stream": true e leia Server-Sent Events. Cada chunk contém um fragmento de delta.content; o stream termina no último chunk com finish_reason: "stop", seguido por um 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-opus-4-8",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true,
    "max_tokens": 20
  }'

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

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

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

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

data: [DONE]

Acumule choices[0].delta.content entre os chunks para reconstruir o texto completo. O evento de dados final (após finish_reason) carrega os totais de usage, não um delta.

Chamada de ferramentas

Declare funções da mesma forma que no OpenAI, depois reenvie na próxima rodada a mensagem tool_calls do assistente e as mensagens com 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-opus-4-8",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "max_tokens": 200,
    "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 volta com finish_reason: "tool_calls" e inclui, em choices[0].message.tool_calls, o nome da função e os parâmetros codificados em JSON. Execute sua função localmente e, na próxima requisição, envie o resultado como uma mensagem role: "tool" com o tool_call_id correspondente — o modelo continua a partir dali.

Raciocínio adaptativo

O Claude Opus 4.8 oferece rodadas de raciocínio opcionais. Adicione "thinking": {"type": "adaptive"} e escolha o nível de esforço via output_config.effort (low, medium e high estão todos confirmados como disponíveis):

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

Duas coisas vale a pena saber antes de construir em cima disso. Primeiro, "adaptativo" significa que o modelo decide por conta própria se um prompt merece raciocínio — em níveis de esforço low ou até medium, uma pergunta simples pode não retornar o campo reasoning_details de forma alguma, então não presuma que toda requisição produzirá esse campo. Segundo, diferente de alguns outros modelos de texto na hiapi, o Opus 4.8 não retorna um traço de raciocínio legível por humanos: as entradas reasoning.text no array reasoning_details voltam vazias, e apenas as entradas signature são preenchidas. Trate reasoning_details como estado de continuação opaco — se você for levar a conversa para chamadas de ferramentas subsequentes, passe-o sem alterações — em vez de analisá-lo ou exibi-lo ao usuário.

Tratamento de erros

Falhas de autenticação retornam HTTP 401 com um envelope 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 registre error.request_id caso precise escalar — o time de suporte pode rastrear a chamada específica a partir dele.

Idempotência e novas tentativas

Chamadas de Chat Completions não são idempotentes por ID de requisição como as tarefas de /v1/tasks — uma requisição repetida é uma nova conclusão e uma nova cobrança. Para tráfego de produção, envolva sua lógica de repetição com backoff no código para casos de 5xx/timeout, e limite max_tokens para que uma tempestade de novas tentativas (ou chamadas de raciocínio adaptativo de longa duração) não cause custos ilimitados.

Leitura relacionada

Claude Opus 4.8 na hiapi — preços atuais e ficha do modelo.
Autenticação — como as chaves de API hiapi funcionam e como rotacioná-las.
Como usar o Claude Sonnet 4.6 pela API hiapi — o mesmo padrão de integração para a camada Claude de custo equilibrado da hiapi, caso sua carga de trabalho não precise de um modelo tão forte quanto o Opus 4.8.
Preços da hiapi — tarifas por token em tempo real do Claude Opus 4.8 e de todos os outros modelos habilitados.

Perguntas frequentes

claude-opus-4-8 é o ID exato do modelo que devo enviar? Sim — envie a string pura claude-opus-4-8 no campo model. Nenhum prefixo específico de provedor e nenhum sufixo de roteamento são necessários; a hiapi resolve internamente para a rota de backend correta.

Isso usa o mesmo fluxo /v1/tasks dos modelos de imagem e vídeo da hiapi? Não. Modelos de texto como o Claude Opus 4.8 usam o endpoint síncrono POST /v1/chat/completions — uma requisição, uma resposta (ou um stream SSE). O /v1/tasks se aplica apenas a modelos de mídia (imagem, vídeo, áudio), que rodam de forma assíncrona e retornam uma URL ou callback para polling.

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

Devo usar Opus 4.8 ou Sonnet 4.6? Opus 4.8 é a camada de maior capacidade e maior custo — escolha-o para tarefas mais difíceis de raciocínio, codificação ou agentes, quando precisão importa mais que latência ou custo por token. Para tráfego de alto volume ou sensível à latência, o Claude Sonnet 4.6 oferece a mesma forma de API por um preço menor.

O thinking sempre retorna um traço de raciocínio visível? Nem um nem outro: o raciocínio adaptativo pode pular completamente o raciocínio em requisições consideradas simples, e quando de fato raciocina, os campos de texto de reasoning_details do Opus 4.8 atualmente voltam vazios — apenas a signature é preenchida. Não construa UIs que presumam um traço legível sempre presente.

Onde consulto os preços atuais antes de rodar lotes grandes? A página de preços da hiapi lista as tarifas por token em tempo real do Claude Opus 4.8 — consulte-a antes de fazer orçamento, pois este artigo não traz números fixos que possam ficar desatualizados.