> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic Messages API

> Use o Anthropic SDK sem modificações com o AI Gateway do Toqan Router, com prompt caching no Claude e acesso a mais de 500 modelos alterando apenas a base URL.

**Casos de uso**

> [accordion] Adotar o gateway sem reescrever o código da Anthropic
>
> Mantenha uma base de código existente com o Anthropic SDK e aponte-a para o **Toqan Router** com uma única alteração em `base_url`; streaming, uso de ferramentas e entrada multimodal continuam funcionando sem mudanças.

> [accordion] Reduzir custos de entrada em prompts longos e estáveis
>
> Marque o system prompt ou os documentos de referência com `cache_control` para que chamadas repetidas e turnos seguintes os leiam do cache em vez de pagar o preço integral.

> [accordion] Usar qualquer modelo do catálogo a partir de um único cliente
>
> Altere o valor de `model` para qualquer `provider/model_id` do catálogo do **AI Gateway**, do Claude à OpenAI e outros provedores, sem trocar de SDK.

> [accordion] Aplicar a governança do gateway ao tráfego do Claude
>
> Fallbacks, orçamentos, guardrails e traces se aplicam a todas as chamadas do Anthropic SDK roteadas pelo gateway.

***

## Visão geral

O **AI Gateway** é uma camada de roteamento que conecta uma única API a mais de 500 modelos de vários provedores, adicionando fallbacks, orçamentos, guardrails e traces; consulte o [início rápido](/docs/pt-BR/ai-gateway/get-started/introduction.md). Ele expõe um endpoint compatível com a Anthropic em `https://router.toqan.ai/eu/v3/anthropic`. O Anthropic SDK acrescenta `/v1/messages` à base URL automaticamente, portanto o código existente da Anthropic funciona com o **Toqan Router** sem nenhuma outra alteração.

As solicitações são autenticadas com uma chave de API do **Toqan Router** e passam pelo mesmo pipeline da [API compatível com a OpenAI](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md), portanto fallbacks, orçamentos, guardrails e traces se aplicam. O prompt caching nos modelos Claude é opcional e ativado por breakpoints `cache_control`, exatamente como na API nativa da Anthropic.

Configure fallbacks para este endpoint por meio de [Routing Rules](/docs/pt-BR/ai-gateway/configuration/routing-rules.md) ou Policies. O campo `fallbacks` do corpo da solicitação é ignorado. Modelos de fallback configurados desativam o passthrough direto para a Anthropic, para que o gateway possa rotear entre provedores.

## Início rápido

**Antes de começar**: conclua uma vez o [início rápido do AI Gateway](/docs/pt-BR/ai-gateway/get-started/introduction.md). Ele mostra como criar uma conta em [router.toqan.ai/eu](https://router.toqan.ai/eu), conectar um provedor (BYOK) com uma chave de API da Anthropic e criar uma chave de API do **Toqan Router**. Em seguida, defina a chave no ambiente:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export TOQAN_API_KEY="your-api-key"
```

Defina a base URL como `https://router.toqan.ai/eu/v3/anthropic` e envie uma solicitação de mensagens com uma chave de API do **Toqan Router**. As solicitações cURL usam o caminho completo mostrado abaixo; nos SDKs, defina `baseURL` como `https://router.toqan.ai/eu/v3/anthropic` e o cliente acrescenta `/v1/messages` automaticamente.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/anthropic/v1/messages \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Explain the AI Gateway in one paragraph." }
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/anthropic",
});

const message = await client.messages.create({
  model: "anthropic/claude-sonnet-5",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Explain the AI Gateway in one paragraph." },
  ],
});

console.log(message.content[0].text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import anthropic
import os

client = anthropic.Anthropic(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/anthropic",
)

message = client.messages.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain the AI Gateway in one paragraph."}],
)

print(message.content[0].text)
```

## Endpoints compatíveis

Todas as rotas são relativas à base URL `https://router.toqan.ai/eu/v3/anthropic` e espelham os formatos de solicitação e resposta da Anthropic Messages API.

| Endpoint | Descrição |
| - | - |
| `POST /v1/messages` | Cria uma mensagem. Oferece suporte a [streaming](/docs/pt-BR/ai-gateway/features/streaming.md), [uso de ferramentas](/docs/pt-BR/ai-gateway/features/tool-calling.md) e [entrada multimodal](/docs/pt-BR/ai-gateway/features/multimodal.md). |
| `POST /v1/messages/count_tokens` | Conta os tokens de entrada de uma solicitação sem chamar o modelo. Retorna `{"input_tokens": <count>}`. Retorna HTTP `400` com `invalid_request_error` quando a contagem de tokens não é compatível com o modelo resolvido. |
| `GET /v1/models` | Lista os modelos disponíveis pelo **AI Gateway**. |
| `GET /v1/models/{model_id}` | Obtém os detalhes de um único modelo. |

> [!NOTE]
>
> Uma contagem de tokens não compatível fica indisponível, e não igual a zero. Trate a resposta `invalid_request_error` com uma estimativa no lado do cliente ou escolha um modelo compatível com a contagem de tokens.

## Autenticação

Escolha entre usar a configuração de provedores do workspace ou enviar uma credencial da Anthropic em cada solicitação.

### Usar uma chave de API do Toqan Router

Autentique-se com a chave de API do **Toqan Router** em qualquer um dos cabeçalhos:

* `Authorization: Bearer $TOQAN_API_KEY`
* `x-api-key: $TOQAN_API_KEY` (o cabeçalho que o Anthropic SDK envia por padrão)

O **Anthropic SDK** funciona sem modificações: defina `ANTHROPIC_API_KEY` como uma chave do **Toqan Router** e `ANTHROPIC_BASE_URL` como `https://router.toqan.ai/eu/v3/anthropic`. Como alternativa, passe os parâmetros do construtor mostrados no Início rápido (`apiKey`/`baseURL` em TypeScript, `api_key`/`base_url` em Python).

> [!NOTE]
>
> Para saber mais sobre as chaves de API do **Toqan Router**, consulte [Chaves de API](/docs/pt-BR/ai-gateway/configuration/api-keys.md).

### Usar uma credencial da Anthropic

Envie uma chave de API ou um token OAuth da Anthropic pelo **AI Gateway** sem adicioná-lo a uma integração do workspace. Mantenha a chave de API do **Toqan Router** em `x-toqan-api-key` e envie a credencial da Anthropic em um cabeçalho próprio:

| Cabeçalho | Valor |
| - | - |
| `x-toqan-api-key` | Chave de API do **Toqan Router**. Obrigatória para acessar o workspace. |
| `x-api-key` | Chave de API da Anthropic, ao usar o faturamento da API. |
| `Authorization` | `Bearer <ANTHROPIC_OAUTH_TOKEN>`, ao usar um token de assinatura do Claude. |
| `anthropic-version` | Versão da API da Anthropic, por exemplo `2023-06-01`. |
| `anthropic-beta` | Inclua o beta OAuth exigido pelo token ao usar a autenticação por assinatura. O **Claude Code** envia esse cabeçalho automaticamente. |

Envie uma única credencial da Anthropic: `x-api-key` ou `Authorization`. Use um modelo público servido diretamente pela Anthropic, como `anthropic/claude-sonnet-5`. Bedrock, Vertex AI, endpoints privados e modelos de outros provedores não podem usar uma credencial da Anthropic.

> [tab] Chave de API da Anthropic
>
> Defina `TOQAN_API_KEY` e `ANTHROPIC_API_KEY` e, em seguida, envie uma solicitação:
>
> ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl https://router.toqan.ai/eu/v3/anthropic/v1/messages \
>   -H "x-toqan-api-key: $TOQAN_API_KEY" \
>   -H "x-api-key: $ANTHROPIC_API_KEY" \
>   -H "anthropic-version: 2023-06-01" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "anthropic/claude-sonnet-5",
>     "max_tokens": 1024,
>     "messages": [{"role": "user", "content": "Explain prompt caching."}]
>   }'
> ```
>
> No **Anthropic SDK**, mantenha a chave da Anthropic como `apiKey` ou `api_key`, defina a base URL como `https://router.toqan.ai/eu/v3/anthropic` e adicione `x-toqan-api-key` por meio de `defaultHeaders` em TypeScript ou `default_headers` em Python.

> [tab] Token de assinatura do Claude
>
> Defina `TOQAN_API_KEY` e `ANTHROPIC_OAUTH_TOKEN` e, em seguida, envie o token como credencial bearer. Inclua o cabeçalho beta OAuth correspondente:
>
> ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl https://router.toqan.ai/eu/v3/anthropic/v1/messages \
>   -H "x-toqan-api-key: $TOQAN_API_KEY" \
>   -H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
>   -H "anthropic-version: 2023-06-01" \
>   -H "anthropic-beta: oauth-2025-04-20" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "anthropic/claude-sonnet-5",
>     "max_tokens": 1024,
>     "messages": [{"role": "user", "content": "Explain prompt caching."}]
>   }'
> ```
>
> Para uso interativo, siga a configuração do **Claude Code** para manter o login existente do Claude. Para um token explícito, execute `claude setup-token` e conclua o login no navegador. Consulte as [instruções de token da Anthropic](https://code.claude.com/docs/en/authentication#generate-a-long-lived-token).

Os mesmos cabeçalhos funcionam para mensagens em streaming e para `POST /v1/messages/count_tokens`. A Anthropic aplica à solicitação do modelo o faturamento ou os limites de assinatura da conta informada. O **Toqan Router** registra o uso em [Traces](/docs/pt-BR/ai-studio/observability/traces.md) sem cobrar essa solicitação como uso de modelo gerenciado pelo **Toqan Router**.

Para configurar o cliente, consulte **Claude Code** ou **Claude Desktop**.

## Nomenclatura de modelos

Use o formato `provider/model_id` do catálogo do **AI Gateway**:

* `anthropic/claude-sonnet-5` para modelos Claude.
* Qualquer outro prefixo de provedor, por exemplo `openai/gpt-5.6-sol`, roteado pelo mesmo endpoint compatível com a Anthropic.

`GET /v1/models` retorna alguns modelos como IDs nativos sem o prefixo do provedor (por exemplo, `claude-sonnet-4-6`). Esses IDs também são resolvidos neste endpoint; a forma `provider/model_id` do catálogo não é ambígua. O mesmo catálogo se aplica a todas as APIs do **AI Gateway**, incluindo `/v3/router` e a Responses API.

Veja todos os modelos disponíveis em [Modelos compatíveis](/docs/pt-BR/ai-gateway/supported-models.md).

## Recursos do gateway

Como as solicitações passam pelo mesmo pipeline do roteador, os seguintes recursos do **AI Gateway** se aplicam às chamadas do Anthropic SDK:

* [Smart Router](/docs/pt-BR/ai-gateway/smart-router.md)
* [Balanceamento de carga e fallbacks](/docs/pt-BR/ai-gateway/features/load-balancing.md)
* [Novas tentativas](/docs/pt-BR/ai-gateway/features/retries.md)
* [Orçamentos](/docs/pt-BR/ai-gateway/budgets.md)
* [Guardrails](/docs/pt-BR/ai-gateway/configuration/guardrails.md)
* Traces
* [Prompt caching](/docs/pt-BR/ai-gateway/features/prompt-caching.md)
* [Cache de respostas](/docs/pt-BR/ai-gateway/features/cache.md)

### Prompt caching

O prompt caching é opcional: adicione um objeto `cache_control` a um bloco de conteúdo para marcar um breakpoint de cache, o final de um prefixo armazenável em cache. Os breakpoints são repassados sem alterações neste endpoint, inclusive em solicitações com vários turnos e em streaming.

> [card] [Prompt caching](/docs/pt-BR/ai-gateway/features/prompt-caching.md)
>
> Valores de `cache_control` compatíveis, TTLs, tipos de bloco, limites mínimos de tokens e relatórios de uso.

As gravações e leituras de cache aparecem em `usage` na resposta como `cache_creation_input_tokens` (gravação) e `cache_read_input_tokens` (leitura), no formato nativo da Anthropic. `cache_control` em um modelo que não é da Anthropic é ignorado, e não rejeitado.

#### Exemplo com vários turnos

Marque o system prompt com um breakpoint e, em seguida, envie um turno seguinte com o mesmo prefixo para ler do cache. O texto de sistema abaixo está abreviado; use um prefixo acima do [limite mínimo de tokens do provedor](/docs/pt-BR/ai-gateway/features/prompt-caching.md#minimum-token-thresholds) para que a leitura do cache apareça. As abas TypeScript e Python reutilizam o cliente do Início rápido.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
# First call: writes the prefix to cache
curl -X POST https://router.toqan.ai/eu/v3/anthropic/v1/messages \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are a senior legal assistant. The following is our complete contract template library...",
        "cache_control": { "type": "ephemeral", "ttl": "1h" }
      }
    ],
    "messages": [
      { "role": "user", "content": "Summarize clause 7 of the NDA template." }
    ]
  }'

# Second call with the same prefix: reads from cache
curl -X POST https://router.toqan.ai/eu/v3/anthropic/v1/messages \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are a senior legal assistant. The following is our complete contract template library...",
        "cache_control": { "type": "ephemeral", "ttl": "1h" }
      }
    ],
    "messages": [
      { "role": "user", "content": "Summarize clause 8 of the NDA template." }
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Uses the client from the Quick Start above
const system = [
  {
    type: "text",
    text: "You are a senior legal assistant. The following is our complete contract template library...",
    cache_control: { type: "ephemeral", ttl: "1h" },
  },
];

// First call: writes the prefix to cache
await client.messages.create({
  model: "anthropic/claude-sonnet-5",
  max_tokens: 1024,
  system,
  messages: [
    { role: "user", content: "Summarize clause 7 of the NDA template." },
  ],
});

// Second call with the same prefix: reads from cache
const message = await client.messages.create({
  model: "anthropic/claude-sonnet-5",
  max_tokens: 1024,
  system,
  messages: [
    { role: "user", content: "Summarize clause 8 of the NDA template." },
  ],
});

console.log(message.usage.cache_read_input_tokens);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Uses the client from the Quick Start above
system = [
    {
        "type": "text",
        "text": "You are a senior legal assistant. The following is our complete contract template library...",
        "cache_control": {"type": "ephemeral", "ttl": "1h"},
    }
]

# First call: writes the prefix to cache
client.messages.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=1024,
    system=system,
    messages=[{"role": "user", "content": "Summarize clause 7 of the NDA template."}],
)

# Second call with the same prefix: reads from cache
message = client.messages.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=1024,
    system=system,
    messages=[{"role": "user", "content": "Summarize clause 8 of the NDA template."}],
)

print(message.usage.cache_read_input_tokens)
```

A segunda chamada envia o mesmo prefixo de sistema com um novo turno do usuário. Quando o prefixo marcado está acima do limite mínimo de tokens do provedor, a resposta informa `cache_read_input_tokens` maior que zero, em vez de pagar o preço integral pelo system prompt.

#### Prompt caching manual vs. automático

A forma de ativar o prompt caching depende do endpoint e do provedor:

| Endpoint | Provedor | Como o cache é ativado |
| - | - | - |
| Compatível com a Anthropic (`/v3/anthropic`) | Claude | Breakpoints `cache_control` manuais nos blocos de conteúdo ou cache automático com um `cache_control` no nível superior. Ambos são repassados ao provedor. |
| Responses API (`/v3/router/responses`) | Claude | `cache_control` manual no system prompt por padrão. Use o parâmetro `cache_control` no nível superior apenas ao continuar com `previous_response_id`. |
| Responses API (`/v3/router/responses`) | OpenAI | Totalmente automático. Nenhuma alteração na solicitação é necessária. |
| Responses API (`/v3/router/responses`) | Google Gemini 2.5+ | Automático. O cache explícito com marcadores `cache_control` funciona em implantações do Vertex AI com autenticação por conta de serviço; o gateway o ignora no Google AI (Gemini API) quando a solicitação tem um system prompt ou ferramentas, e totalmente em implantações do Vertex AI Express (chave de API). |

Use breakpoints manuais quando a solicitação tiver um prefixo longo e estável e o limite do cache for importante. O `cache_control` no nível superior da Responses API marca automaticamente o último bloco armazenável em cache; ele não permite vários breakpoints e é a forma a usar com `previous_response_id`. Consulte [Conversas com vários turnos](/docs/pt-BR/ai-gateway/features/prompt-caching.md#multi-turn-conversations). OpenAI e Gemini 2.5+ fazem cache automaticamente, portanto nenhuma alteração na solicitação é necessária; o Gemini 2.5+ também oferece cache explícito por meio de marcadores `cache_control` em implantações do Vertex AI com autenticação por conta de serviço, enquanto o gateway o ignora no Google AI quando a solicitação tem um system prompt ou ferramentas, e totalmente em implantações do Vertex AI Express (chave de API). Para a comparação completa, consulte [Prompt caching](/docs/pt-BR/ai-gateway/features/prompt-caching.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.