Blogue

Tutorial

Como chamar claude-opus-5-5@aws via API HiAPI: guia com curl e Python

Nov 12, 2026
Arte de capa com pontos de meio-tom verde-menta que variam em densidade sobre um fundo quase preto com acentos em azul-petróleo profundo.
Nesta página

Como é usar claude-opus-5-5@aws via HiAPI

A HiAPI oferece uma interface HTTP unificada para diversos modelos. Em vez de configurar conta, SDK e armazenamento de credenciais separadamente para cada provedor, você usa o mesmo formato de requisição da HiAPI e seleciona o modelo desejado pelo identificador. Neste tutorial, esse identificador é claude-opus-5-5@aws — o sufixo @aws faz parte do nome do modelo, não é um campo separado, e deve ser passado exatamente como está.

O ciclo de vida de uma requisição é o seguinte:

  1. Autenticação — envie sua chave de API HiAPI como bearer token no cabeçalho Authorization.
  2. Envio do payload de chat — um corpo JSON contendo model e um array messages, onde cada mensagem tem role (system, user ou assistant) e content.
  3. Recebimento da resposta JSON — a resposta do assistente aparece no array choices da resposta, acompanhada de metadados de uso.
  4. Continuação da conversa — acrescente a mensagem do assistente e sua próxima mensagem de usuário ao mesmo array messages e envie novamente. A API é stateless; a conversa completa fica no seu payload de requisição.

Como a estrutura de requisição é a mesma entre os modelos, o código que você escreve para claude-opus-5-5@aws pode ser migrado para outro modelo alterando apenas a string de model. Mantenha esse campo centralizado em um único lugar do código — como valor de configuração ou variável de ambiente — em vez de codificá-lo fixamente em vários arquivos.

Uma observação sobre nomenclatura: a plataforma documenta esse modelo como claude-opus-5-5@aws. Use exatamente essa string. Erros de digitação, espaços extras ou omissão do sufixo geram erros do tipo modelo não encontrado, sem avisos úteis.

Obtenção de credenciais e autenticação

Antes de chamar a API, você precisa obter uma chave de API na sua conta HiAPI. Trate essa chave como confidencial: armazene-a em variável de ambiente ou no gerenciador de segredos da plataforma, nunca em controle de versão e jamais em código client-side enviado ao navegador.

A HiAPI autentica requisições por bearer token no cabeçalho Authorization:

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

Toda requisição deve incluir:

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

Algumas regras práticas evitam a maioria das falhas de autenticação:

  • Mantenha o prefixo literal Bearer , seguido de um espaço e depois a chave. A ausência do prefixo ou do espaço é um erro comum de copiar e colar.
  • Não coloque aspas na chave dentro do valor do cabeçalho.
  • Se fizer rotação da chave, atualize a variável de ambiente e reinicie o processo — workers de longa duração costumam manter o valor antigo em cache.
  • Ao colar a chave em um arquivo .env, verifique espaços ou quebras de linha no final; alguns loaders não removem isso automaticamente.

Se a chave estiver ausente ou mal formatada, você receberá um erro de autenticação (classe 401), e não um erro de modelo, o que facilita distingui-lo de problemas posteriores. Uma vez que a requisição passe na autenticação, o mesmo cabeçalho serve para streaming, tool calling e todos os outros padrões deste guia — não é preciso usar credenciais diferentes para cada recurso.

Para código server-side, carregue a chave uma vez na inicialização e passe-a para um cliente compartilhado ou uma pequena função wrapper. Isso centraliza o segredo em um único lugar e torna trivial alternar entre credenciais de desenvolvimento e de produção.

Construção de uma requisição executável com curl

A seguir está uma requisição completa e executável. Substitua a chave placeholder pela sua ou execute antes o export da seção anterior para que o shell faça a substituição.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5@aws",
    "messages": [
      {
        "role": "user",
        "content": "Explique em três frases por que endpoints POST idempotentes são importantes para APIs de pagamento."
      }
    ]
  }'

Detalhando item por item:

  • Endpoint — POST https://api.hiapi.ai/v1/chat/completions.
  • Cabeçalhos — bearer token e tipo de conteúdo JSON. Ambos são obrigatórios.
  • model — o identificador exato claude-opus-5-5@aws.
  • messages — array de objetos com role e content. A última mensagem de usuário é o que o modelo deve responder.
  • Payload — -d envia JSON puro, então o tratamento de aspas importa. No shell, envolva todo o corpo com aspas simples e use aspas duplas nas chaves JSON.

A resposta é um JSON contendo um array choices. O texto gerado fica em choices[0].message.content e inclui informações de uso (contagem de tokens), para que você monitore o consumo. O uso da resposta é cobrado por token; as tarifas atuais estão no painel de preços do site.

Ajustes comuns:

{
  "model": "claude-opus-5-5@aws",
  "max_tokens": 512,
  "temperature": 0.2,
  "messages": [
    {"role": "system", "content": "Você é um editor técnico conciso."},
    {"role": "user", "content": "Resuma o corpo da requisição acima em uma linha."}
  ]
}

Use max_tokens para limitar gerações descontroladas, temperature para controlar verbosidade e variância, e uma mensagem system para definir o comportamento uma vez por conversa. A mensagem system deve ficar no mesmo array messages, antes dos turnos do usuário.

A mesma requisição em Python

A versão em Python usa a biblioteca padrão urllib, então o trecho roda sem instalar nada. Se você preferir uma biblioteca cliente, a estrutura da requisição é idêntica — só muda o transporte.

import json
import os
import urllib.request

API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"

def ask(user_message: str, system_message: str | None = None) -> str:
    messages = []
    if system_message:
        messages.append({"role": "system", "content": system_message})
    messages.append({"role": "user", "content": user_message})

    payload = json.dumps({
        "model": MODEL,
        "messages": messages,
    }).encode("utf-8")

    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        body = json.loads(response.read().decode("utf-8"))

    return body["choices"][0]["message"]["content"]

if __name__ == "__main__":
    print(ask("Cumprimente usando exatamente cinco palavras."))

Por que vale manter essa estrutura:

  • MODEL e API_URL são constantes em nível de módulo, então trocar modelo ou endpoint exige mudar apenas uma linha.
  • A chave vem do ambiente; a função nunca aceita um parâmetro com o segredo em texto puro.
  • A lógica de parsing fica isolada no final, então você pode trocar urllib por httpx ou requests sem alterar a forma de montar a conversa.

Para continuar uma conversa com múltiplos turnos, acrescente a resposta do assistente e a próxima mensagem de usuário a messages antes de enviar novamente. Deixe o array crescer até atingir o limite de contexto e então resuma os turnos mais antigos em uma mensagem system para se manter dentro do orçamento. O uso na resposta é baseado em tokens; as tarifas atuais estão listadas no painel de preços do site.

Respostas em streaming para cenários interativos

Para UIs de chat e gerações longas, o streaming envia conteúdo parcial à medida que a saída é produzida, em vez de esperar a resposta completa. O corpo da requisição permanece igual, exceto por um campo:

{
  "model": "claude-opus-5-5@aws",
  "messages": [{"role": "user", "content": "Escreva uma entrada curta de changelog para uma biblioteca que acabou de adotar streaming."}],
  "stream": true
}

Com stream: true, o endpoint responde com server-sent events: cada bloco é uma linha prefixada com data: , e o stream termina com uma linha final de encerramento. A maioria dos blocos contém, no array choices, um delta com um fragmento de texto, e não a mensagem completa.

Com curl, remova o efeito silencioso de -sS para observar a saída chegando aos poucos:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"Conte até cinco lentamente."}]}'

A flag -N desativa o buffering para que você veja os blocos chegando. Em Python, leia a resposta linha a linha:

with urllib.request.urlopen(request) as response:
    for raw_line in response:
        line = raw_line.decode("utf-8").strip()
        if not line.startswith("data: "):
            continue
        data = line[len("data: "):]
        if data == "[DONE]":
            break
        chunk = json.loads(data)
        delta = chunk["choices"][0].get("delta", {})
        text = delta.get("content")
        if text:
            print(text, end="", flush=True)

Dicas práticas:

  • Sempre trate o marcador de encerramento [DONE] e linhas vazias/de keep-alive; não assuma que toda linha é JSON.
  • Nunca bloqueie a thread da UI no stream inteiro — acrescente os deltas a um buffer à medida que chegam.
  • Se o cliente desconectar, feche a resposta para liberar a geração upstream.
  • O streaming não muda a forma de cálculo do uso; o último bloco geralmente carrega os metadados de uso. A cobrança é por tokens de saída; as tarifas atuais estão no painel de preços do site.

Adição de tool calling à conversa

O uso de ferramentas permite que o modelo solicite ações estruturadas ao seu código, e não apenas gere texto. A requisição ganha um array tools; a conversa ganha mensagens de assistente que carregam tool_calls e mensagens role: "tool" que carregam resultados.

Defina os parâmetros da ferramenta com JSON Schema:

{
  "model": "claude-opus-5-5@aws",
  "messages": [
    {"role": "user", "content": "Como está o tempo em Lisboa agora?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Retorna o clima atual de uma cidade.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "Nome da cidade, por exemplo Lisbon"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

O modelo pode retornar uma mensagem contendo tool_calls em vez de texto final. Cada entrada especifica o nome da função e carrega os argumentos como string JSON. Seu trabalho é executar essa função no seu sistema e então acrescentar o resultado:

  1. Acrescente a mensagem do assistente contendo tool_calls a messages, exatamente como veio.
  2. Para cada chamada, acrescente uma mensagem com role: "tool", o tool_call_id correspondente da mensagem do assistente e content definido como o resultado serializado.
  3. Envie novamente a requisição com o mesmo array tools. O modelo então gera uma resposta em linguagem natural com base no seu resultado.

Proteções que vale estabelecer desde cedo:

  • Valide os parâmetros — antes de executar qualquer ação, valide os parâmetros contra o schema — nunca passe a saída do modelo diretamente para o shell ou para uma consulta de banco de dados.
  • Limite os loops. Defina um teto para as rodadas de tool calling (normalmente de três a cinco), para evitar que um modelo que solicita chamadas continuamente entre em loop infinito.
  • Retorne erros como resultado da ferramenta. Se a função falhar, envie uma string de erro curta com o tool_call_id correspondente; o modelo então pode tentar novamente ou explicar a falha, em vez de travar.
  • Mantenha as descrições das ferramentas precisas. Descrições vagas causam erros de seleção de ferramenta com muito mais frequência do que erros de parâmetros.

As definições de ferramentas são avaliadas junto com a requisição e entram na sua contagem de tokens. As tarifas atuais estão publicadas no painel de preços do site.

Próximos passos

Comece pela chamada curl mínima, mova-a para uma função wrapper em Python e só então acrescente streaming e ferramentas se o seu caso de uso exigir. A string de modelo claude-opus-5-5@aws nunca muda — todo o resto são campos no payload da requisição.

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