Como migrar uma integração OpenRouter para outro API Gateway

Escolha primeiro o cenário de migração

• Permaneça no OpenRouter quando integração, caminho de cobrança, disponibilidade de modelos e comportamento operacional atuais atendem aos requisitos da aplicação.
• Adicione um backup testado quando uma segunda rota é útil, mas a integração primária não precisa mudar.
• Execute um canário de migração quando o gateway candidato atende aos requisitos de protocolo e modelo e você está pronto para comparar o comportamento real em tráfego controlado.

A BetterToken não vende contas OpenRouter e não pode transferir keys nem saldo do OpenRouter. Para testá-la, crie sua própria conta e API Key da BetterToken e obtenha o Model ID e os requisitos atuais da key no Workspace ou na documentação vigente.

Monte uma matriz de requisitos antes de alterar a configuração

“OpenAI-compatible” descreve parte de uma interface, não o comportamento completo de um serviço. Dois gateways podem aceitar solicitações parecidas e ainda diferir em modelos disponíveis, eventos de streaming, payloads de tool calls, corpos de erro, headers de retry, rate limits ou contabilização do uso.

Registre o comportamento atual e o critério de aceitação de cada requisito antes de testar um candidato.

Não escolha um gateway apenas pela quantidade de modelos. A pergunta importante é se o Model ID e o contrato de resposta exigidos atualmente funcionam nesta aplicação. Disponibilidade e preços são dinâmicos; consulte o catálogo e a tabela de preços atuais do provider durante a migração.

Cenário 1: permanecer no OpenRouter

Permaneça quando não existe uma lacuna concreta a resolver. Se a aplicação depende do catálogo, roteamento, headers ou comportamento de resposta atuais do OpenRouter, a migração cria novos modos de falha sem um benefício correspondente.

Ainda é possível preparar a portabilidade futura:

• mova Base URL, API Key e Model ID para a configuração;
• documente os campos de resposta e erro consumidos pela aplicação;
• separe headers específicos do provider da lógica compartilhada das solicitações;
• adicione testes de contrato executáveis com uma key isolada;
• registre a responsabilidade pelo rollback e a política de retry permitida.

Esse trabalho reduz o risco de uma migração futura sem alterar o tráfego de produção agora.

Cenário 2: adicionar um backup testado

Uma rota de backup só é útil depois de passar pelos mesmos testes de contrato da rota primária. Mantenha as configurações dos providers separadas; não sobrescreva a configuração do OpenRouter apenas para provar que outra solicitação funciona.

Defina exatamente quais falhas permitem fallback. Falhas de autenticação, Model IDs inválidos, métodos não aceitos, solicitações malformadas e a maioria dos outros erros do cliente não devem ser repetidos automaticamente em outro provider. Mesmo para falhas transitórias, o fallback continua limitado por idempotência, limites de retry, orçamento de timeout e recursos aceitos pelo candidato.

Nunca envie a mesma operação de mutação a dois gateways, a menos que a aplicação tenha um mecanismo de idempotência verificado e consiga confirmar o estado de destino. Um backup não garante que todas as solicitações serão concluídas nem que o output será idêntico.

Cenário 3: migrar com um canário

Use um canário quando o candidato já passou pelos testes isolados e o objetivo é mover a rota primária. Envie primeiro apenas um segmento pequeno e controlado de tráfego não crítico. Mantenha a rota atual disponível até terminar a janela de observação e as verificações de rollback.

Defina o sucesso antes de iniciar o canário:

• o schema esperado da resposta é interpretado sem código de fallback;
• o comportamento exigido de streaming e tool calls é aprovado;
• os tipos de erro continuam classificáveis;
• os registros de uso são reconciliados dentro do limite aceito pela aplicação;
• latência, timeout e retries atendem ao limite definido;
• não aparecem efeitos colaterais duplicados nem ausentes.

Se uma condição obrigatória falhar, interrompa a expansão e devolva o novo tráfego à configuração conhecida e funcional.

Procedimento de migração em cinco etapas

Etapa 1: inventarie o contrato atual

Registre protocolo, SDK e método exatos, Base URL do OpenRouter, Model ID, variável de autenticação, headers específicos do provider, modo de streaming, uso de tools, política de timeout, política de retry, campos de erro, request ID e campos de uso.

Identifique quais itens são requisitos rígidos e quais podem mudar. Um campo de log pode ser substituível; o contrato de tool calls usado pela automação de produção talvez não seja.

Não copie API Keys para a planilha. Registre apenas o nome da variável e o local de armazenamento do secret.

Etapa 2: crie uma configuração candidata isolada

Crie uma key de teste separada no gateway candidato. Não reutilize uma key de produção nem faça commit de secrets no repositório.

Para a BetterToken, use sua própria conta e escolha o Model ID e os requisitos da key exibidos atualmente no Workspace ou na documentação da API. Não fixe um Model ID de um tutorial antigo.

Mantenha a configuração candidata ao lado da configuração atual do OpenRouter, não por cima dela. Essa separação permite comparação e rollback.

Etapa 3: defina a Base URL específica do protocolo

Para um cliente BetterToken OpenAI-compatible, use:

TEST_API_KEY=your_test_api_key_here
TEST_BASE_URL=https://www.bettertoken.ai/v1?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-088&utm_content=analog-openrouter-v-rossii-vybor-i-perenos-api
TEST_MODEL_ID=current_model_id_from_provider_catalog

Para um cliente Anthropic-compatible, a Base URL da BetterToken é https://bettertoken.ai, sem /v1. Não reutilize o formato da solicitação Python OpenAI-compatible em um cliente Anthropic-compatible; siga a documentação do SDK e do protocolo desse caminho.

Confirme se o cliente espera uma Base URL versionada ou acrescenta parte do caminho por conta própria. /v1 duplicado ou ausente é erro de configuração, não evidência de que todo o gateway está indisponível.

Etapa 4: execute a mesma solicitação mínima e os testes de contrato

Use a mesma família de SDK e o mesmo método da aplicação. O exemplo Python a seguir testa uma solicitação OpenAI-compatible de Chat Completions com variáveis de ambiente:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TEST_API_KEY"],
    base_url=os.environ["TEST_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["TEST_MODEL_ID"],
    messages=[{"role": "user", "content": "Reply with: gateway test passed"}],
    max_tokens=32,
)

print(response.choices[0].message.content)
print(response.usage)

Os placeholders são intencionais. Carregue a key real pelo mecanismo de secrets do projeto e obtenha o Model ID atual do provider no momento do teste.

Depois da solicitação básica, execute testes separados de streaming, tool calls, autenticação inválida e Model ID inválido se a aplicação de produção depende desses comportamentos. Registre evidências não sensíveis: timestamp, status, request ID quando disponível, formato da resposta, campos de uso e resultado da aplicação.

Etapa 5: envie um canário, compare e decida

Direcione uma parte controlada do tráfego não crítico ao candidato. Compare as duas rotas durante uma janela representativa:

• contagens de sucessos e erros classificados;
• distribuição de latência e comportamento de timeout;
• quantidade de retries e tratamento de Retry-After quando presente;
• schemas de resposta e tool calls;
• conclusão do streaming;
• uso de input, input em cache e output;
• registros de status e cobrança no provider;
• efeitos colaterais duplicados, ausentes ou atrasados.

Expanda somente depois que todos os requisitos rígidos forem aprovados. Se um gatilho de rollback disparar, devolva o novo tráfego ao OpenRouter e investigue o candidato offline.

Valide mais do que uma resposta bem-sucedida

Um HTTP status de sucesso só prova que uma solicitação retornou. Não prova equivalência do protocolo, prontidão para produção nem roteamento correto.

Valide erros deliberadamente

Use a key de teste isolada para provocar falhas controladas:

• um Model ID inválido;
• uma key de teste revogada ou propositalmente inválida;
• um método não aceito, se for seguro testar;
• um timeout em ambiente fora de produção.

Confira HTTP status, corpo do erro, request ID, metadata de retry e comportamento do cliente. Garanta que erros terminais não sejam repetidos indefinidamente e que os logs ocultem credenciais e conteúdo sensível da solicitação.

A referência de erros do OpenRouter documenta o comportamento do OpenRouter. Trate a documentação atual e a resposta observada do candidato como outro contrato.

Reconcilie o uso

Capture o objeto de uso retornado ao SDK e compare-o com o log da aplicação e o registro da conta no provider. Campos necessários podem incluir tokens de input, input em cache, tokens de output ou unidades específicas do provider.

O Dashboard da BetterToken pode mostrar horário da solicitação, modelo, status, tokens de input, output e cache, além da cobrança correspondente. Isso não implica que prompts ou respostas completos sejam armazenados ou exibidos. Associe o registro pelo horário do teste e outras metadata sem segredos; não presuma que uma resposta bem-sucedida prova qual rota a processou.

Teste streaming e tool calls separadamente

Para streaming, verifique primeiro evento, deltas de conteúdo, motivo de conclusão, uso final quando fornecido, tratamento de desconexão e se a aplicação distingue uma resposta parcial de uma concluída.

Para tool calls, compare nome da tool, call ID, argumentos serializados, falhas de validação e fluxo de envio do resultado. Use uma tool read-only no primeiro teste. Uma resposta normal em texto não prova que o caminho de tool calls é compatível.

Limites do rollback

Mantenha o rollback explícito e reversível antes de iniciar o canário.

Faça rollback imediatamente quando um requisito rígido falhar, incluindo:

• a aplicação não consegue interpretar o schema da resposta ou do erro;
• um stream obrigatório termina incompleto;
• argumentos ou IDs de tool calls são corrompidos;
• não é possível reconciliar o uso exigido pelos controles de cobrança;
• o comportamento de timeout ou erro ultrapassa o limite operacional acordado;
• um workflow de mutação produz resultado incerto, duplicado ou ausente.

Ao fazer rollback:

1. pare de aumentar o tráfego do candidato;
2. direcione novas solicitações à configuração conhecida e funcional do OpenRouter;
3. não repita automaticamente solicitações de mutação com resultado desconhecido;
4. preserve timestamps, request IDs, status codes e logs sem segredos para diagnóstico;
5. mantenha a key candidata isolada até entender a causa e revogue-a quando não for mais necessária.

Não apague a configuração nem as credenciais antigas até o responsável pela migração confirmar a janela de observação, o teste de rollback e a reconciliação downstream. Se as duas rotas permanecerem ativas, documente responsabilidade, health checks, erros elegíveis para fallback e o orçamento máximo de retry.

Verificações operacionais e de custo

Não inclua preços fixos em um runbook de migração. Consulte a tabela de preços atual de cada provider na data do teste e compare-a com o uso realmente registrado.

Inclua estes itens na decisão:

• disponibilidade de modelos e recursos;
• tarifas de input, input em cache e output;
• requisitos de saldo mínimo ou conta mostrados no momento do pagamento;
• limites de solicitações e concorrência;
• comportamento de timeout e retry;
• exportação de uso ou visibilidade no Dashboard;
• rotação de keys e controle por projeto;
• caminhos de suporte e escalonamento de incidentes.

Para a BetterToken, use a página de preços atual e o Workspace, não um screenshot antigo nem uma tarifa copiada. O serviço é um gateway candidato, não prova de que todo workload do OpenRouter pode migrar sem alterações.

Checklist da decisão final

Permaneça no OpenRouter quando:

• não existe uma lacuna concreta de integração ou operação;
• o catálogo e o contrato atuais são necessários;
• o candidato não passou por um requisito rígido.

Adicione um backup quando:

• uma segunda rota tem valor independente;
• ela passou pelos mesmos testes de protocolo, erro, uso e recursos;
• as regras de fallback são limitadas e observáveis.

Migre quando:

• o candidato atende a todos os requisitos rígidos;
• o canário permanece dentro dos limites aceitos de erro e latência;
• os registros de uso e cobrança são reconciliados;
• o rollback foi testado e continua funcionando.

O rótulo OpenAI-compatible é o começo de um plano de testes, não evidência de equivalência completa. A migração mais segura é isolada, observável, incremental e reversível.

Se a BetterToken for candidata para sua integração, comece pela documentação atual da API, crie uma key de teste separada e execute o canário em cinco etapas antes de alterar o tráfego de produção.

Fontes

• OpenRouter quickstart
• OpenRouter errors and debugging
• OpenRouter model catalog
• BetterToken API reference