Como funciona o roteamento

Quando sua aplicacao envia uma chamada para api.usetokia.com/v1/chat/completions, o Tokia roteia essa chamada para o provider que hospeda o modelo escolhido. O caminho completo e transparente e toda chamada aparece nos seus logs.

Arquitetura de roteamento

O Tokia opera como um gateway OpenAI-compatible. A arquitetura tem tres camadas:

O que acontece em cada camada

1. Tokia API Gateway

• Valida a chave de API (Bearer token) e identifica o usuario
• Verifica saldo suficiente (cost guard — estimativa de custo antes da chamada)
• Aplica rate limits por chave e por modelo
• Bloqueia modelos fora do tier do usuario (free tier so acessa modelos gratuitos)
• Registra a chamada para billing e logs

2. LiteLLM (proxy interno)

• Traduz o formato OpenAI para o formato nativo do provider (quando necessario)
• Encaminha a chamada para o provider correto com a chave do Tokia
• Gerencia retry e fallback entre providers (ver Fallback)
• Coleta metricas de latencia e custo upstream

3. Providers upstream

O modelo que voce escolhe determina o provider. Exemplos:

• claude-sonnet-4 → Anthropic (via OpenRouter)
• gpt-4.1 → OpenAI (via OpenRouter)
• gemini-2.5-flash → Google AI Studio (direto)
• deepseek-v3-0324 → DeepSeek (direto)
• flux-kontext-pro → Black Forest Labs (via Fal.ai)

Transparencia no roteamento

Diferente de outros gateways que escondem para qual provider a chamada foi, o Tokia expoe em cada evento de uso:

• Provider upstream: quem processou a chamada
• Custo upstream (USD): quanto o Tokia pagou ao provider
• Custo cobrado (BRL): quanto foi debitado do seu saldo
• Status: sucesso ou falha, com classe e mensagem de erro
• Tokens: entrada e saida, contados pelo provider

Modelo nao encontrado

Se voce pedir um modelo que nao existe no catalogo, o LiteLLM retorna 404 model_not_found. Consulte a lista atualizada em Modelos.