Adotar o gateway sem reescrever o código da Anthropic
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.Reduzir custos de entrada em prompts longos e estáveis
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.Usar qualquer modelo do catálogo a partir de um único cliente
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.Aplicar a governança do gateway ao tráfego do Claude
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. Ele expõe um endpoint compatível com a Anthropic emhttps://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: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 URLhttps://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_KEYx-api-key: $TOQAN_API_KEY(o cabeçalho que o Anthropic SDK envia por padrão)
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 emx-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.
- Chave de API da Anthropic
- Token de assinatura do Claude
Defina No Anthropic SDK, mantenha a chave da Anthropic como
TOQAN_API_KEY e ANTHROPIC_API_KEY e, em seguida, envie uma solicitação:cURL
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.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 formatoprovider/model_id do catálogo do AI Gateway:
anthropic/claude-sonnet-5para 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:- Smart Router
- Balanceamento de carga e fallbacks
- Novas tentativas
- Orçamentos
- Guardrails
- Traces
- Prompt caching
- Cache de respostas
Prompt caching
O prompt caching é opcional: adicione um objetocache_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.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.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.
