API Messages

Endpoint: POST /v1/messages. Solicitação e resposta correspondem exatamente à API Messages da Anthropic, então o SDK da Anthropic — ou qualquer ferramenta que use esse formato — funciona com Kunavo alterando apenas a URL base e a chave.

Qual endpoint devo usar?

Kunavo disponibiliza a família Claude de duas formas. Ambas têm a mesma cobrança; escolha conforme o formato de solicitação que seu código já usa.

Autenticação

Aponte a URL base para https://api.kunavo.com — o SDK da Anthropic acrescenta /v1/messages por conta própria. Passe sua chave Kunavo (sk-kn-...) como chave de API; o endpoint a aceita no cabeçalho x-api-key (padrão do SDK da Anthropic) ou em Authorization: Bearer.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-kn-...",                  # your Kunavo key
    base_url="https://api.kunavo.com",    # SDK appends /v1/messages
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a senior staff engineer.",
    messages=[
        {"role": "user", "content": "Pros and cons of event sourcing?"},
    ],
)
print(msg.content[0].text)

cache de prompts

Este é o principal motivo para usar o endpoint nativo. Anexe um ponto de interrupção cache_control a qualquer bloco de sistema, bloco de conteúdo de mensagem ou definição de ferramenta. O prefixo marcado é gravado no cache uma vez e, depois, reutilizado em chamadas subsequentes que o compartilham.

O cache em si não exige este endpoint: em /v1/chat/completions e /v1/responses, a Kunavo define ela mesma os pontos de interrupção para os modelos Claude em um prompt longo. A diferença deste endpoint é não adicionar nenhum: o corpo da requisição é repassado exatamente como você o enviou, então cada ponto de interrupção nele foi definido por você.

# Mark a large, stable prefix with cache_control. The first call writes that
# span to cache at 1.25× the input token price; later calls that reuse it read
# it back at ~10%.
msg = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_STYLE_GUIDE,            # tens of thousands of tokens
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "Review this PR against the guide."}],
)
u = msg.usage
print(u.cache_creation_input_tokens, u.cache_read_input_tokens)

Preços da família Claude na Kunavo:

• cache_read_input_tokens — servido do cache, cobrado a 0.10× da tarifa de entrada (desconto de 90%); 0,025× no Claude Fable 5.1, 0,05× no Claude Opus 5.5.
• cache_creation_input_tokens — gravado no cache, cobrado a 1.25× a tarifa de entrada. Kunavo cobra as gravações com TTL de 1 hora à mesma tarifa de 1.25×, abaixo dos 2× da Anthropic.

Streaming

Defina stream: true (ou use o auxiliar stream() do SDK). Kunavo encaminha sem alterações o fluxo de eventos nativo da Anthropic — message_start, content_block_delta, message_delta, message_stop.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain CRDTs in one paragraph."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Imagens

Envie imagens como fontes base64 ou url. Uma fonte url é a única parte do corpo que Kunavo reescreve: ela própria baixa uma imagem https (ou extrai os dados de uma URI data:) e a encaminha como base64, porque o upstream ignora uma fonte url e responderia como se nenhuma imagem tivesse sido enviada. Imagens dentro de um tool_result são tratadas da mesma forma. Limites: 16 imagens por solicitação, 5 MB por imagem e 20 MB no total; se não for possível buscar uma imagem, será retornado um erro em vez de ignorá-la.

Objeto de uso

Cada resposta (e os eventos de streaming message_delta / message_start) inclui um objeto usage nativo da Anthropic:

Ferramentas do servidor

As ferramentas de servidor da Anthropic (web_search, web_fetch, code_execution) são encaminhadas como definições de ferramentas comuns. O que elas acrescentam à conversa (resultados de busca, uma página obtida, saída de programa) retorna em usage como tokens e é cobrado às tarifas acima.

A busca na web também é cobrada por busca, além desses tokens: a Anthropic lista o preço de US$ 10 por 1.000 buscas, e Kunavo aplica o desconto próprio de cada modelo a esse valor. A contagem é usage.server_tool_use.web_search_requests, na resposta ou no message_delta final de um fluxo; uma busca que retorna um erro (como max_uses_exceeded) não é contabilizada. A obtenção de páginas web e a execução de código não têm custo além dos tokens.

Modelos compatíveis

Qualquer modelo Claude ativado aceita /v1/messages. Envie o slug Kunavo como model:

• claude-fable-5, claude-sonnet-5
• claude-opus-5, claude-opus-4-7, claude-opus-4-6
• claude-sonnet-4-6, claude-haiku-4-5

Modelos GPT não estão disponíveis aqui — chame-os por meio de /v1/chat/completions.

HTTP bruto

Não é necessário SDK — o endpoint aceita uma solicitação POST com JSON simples:

curl https://api.kunavo.com/v1/messages \
  -H "x-api-key: sk-kn-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

Próximos passos

• Conclusões de chat compatíveis com OpenAI
• Como funciona a cobrança (preços por token, tarifas de cache e margem)
• Explore todos os modelos de chat