Pular para o conteúdo principal
Casos de uso
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.
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.
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.
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. 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, 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 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. Ele mostra como criar uma conta em 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:
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.

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.
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).
Para saber mais sobre as chaves de API do Toqan Router, consulte Chaves de API.

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: 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.
Defina TOQAN_API_KEY e ANTHROPIC_API_KEY e, em seguida, envie uma solicitação:
cURL
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.
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 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.

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:

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.

Prompt caching

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 para que a leitura do cache apareça. As abas TypeScript e Python reutilizam o cliente do Início rápido.
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: 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. 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.