Lista de Verificação de Produção da API OpenRouter

Verificar Compatibilidade da API e Endpoints

Use os endpoints padrão compatíveis com OpenAI para uma integração confiável.

O endpoint principal é POST /v1/chat/completions. Isso trata a geração de texto para históricos de chat. Um endpoint secundário, GET /v1/models, lista os modelos disponíveis. Você não precisa de endpoints de embeddings ou geração de imagens para tarefas apenas de texto. Muitos desenvolvedores assumem que precisam de uma camada de roteamento complexa. A OpenRouter simplifica isso expondo um único ponto de entrada. Você envia um payload JSON com o ID do modelo e prompts do sistema. O serviço retorna JSON estruturado com conteúdo e dados de uso. Este design corresponde às expectativas do SDK oficial da OpenAI. Você pode trocar modelos sem alterar o código do seu cliente. Basta atualizar o ID do modelo na sua configuração. Certifique-se de que seu cliente suporte o esquema JSON mais recente. Versões mais antigas podem rejeitar novos parâmetros. Teste sua conexão antes de implantar em produção. Verifique se o formato da resposta corresponde ao seu parser.

Configure Autenticação e Chaves

Armazene sua chave de API nas variáveis de ambiente imediatamente após a geração.

Gere uma chave através do painel do provedor. Armazene-a em um local seguro. Nunca a codifique no seu repositório de código-fonte. Passe-a via Authorization: Bearer <key> Cabeçalho. Cada chave está vinculada a uma conta específica. Você pode rotacionar as chaves se suspeitar de um vazamento. Alguns provedores permitem várias chaves por conta. Isso permite que você separe o tráfego de desenvolvimento e produção. Monitore o uso por chave para detectar anomalias. Revogue chaves não utilizadas regularmente. Use chaves de curta duração para scripts temporários. Isso reduz o impacto de um comprometimento. Certifique-se de que sua versão do SDK suporte autenticação com token Bearer. Bibliotecas mais antigas podem exigir um formato de cabeçalho diferente. Verifique a documentação do seu SDK específico. Verifique se a chave possui saldo suficiente. Uma chave expirada retorna um erro 401. Uma chave com saldo zero retorna um erro 402. Diferencie esses dois estados na sua lógica.

Trate Streaming e Uso de Tokens

Ative o streaming para menor latência e feedback do usuário em tempo real.

Definir stream: true na carga útil da sua solicitação. O servidor envia uma série de Eventos Enviados pelo Servidor (SSE). Cada evento contém um chunk parcial de texto. Você deve montar esses chunks para formar a resposta completa. O último chunk frequentemente inclui estatísticas de uso de tokens. Isso permite que você rastreie os custos em tempo real. Sem streaming, você aguarda toda a resposta. Isso aumenta significativamente a latência percebida. O streaming é essencial para interfaces de chat. Ele cria um efeito de digitação que parece responsivo. Tenha cuidado com o tratamento de erros durante o streaming. Se a conexão cair, você perde o chunk atual. A lógica de reconexão deve preservar o estado da conversa. Alguns SDKs lidam com streaming automaticamente. Outros exigem listeners de eventos manuais. Escolha a abordagem que se adapta à sua arquitetura. Certifique-se de que seu analisador lide com chunks de JSON incompletos. Não assuma que cada evento é um objeto completo. Armazene os dados em buffer até ter uma estrutura válida.

Monitorar Limites de Taxa e Concorrência

Acompanhe suas solicitações por minuto para evitar interrupções no serviço.

A OpenRouter impõe limites de taxa rigorosos por chave de API. Exceder esses limites aciona um erro 429 Too Many Requests. Você deve implementar backoff exponencial na lógica de retry. Solicitações simultâneas também contam contra seus limites. Verifique os cabeçalhos de resposta para ver a cota restante. Alguns provedores expõem esses cabeçalhos diretamente. Outros exigem que você infira os limites a partir de erros. Alta concorrência pode esgotar seu pool de conexões. Certifique-se de que seu cliente gerencie conexões de forma eficiente. Use pooling de conexão para reduzir a sobrecarga. Monitore a profundidade da fila durante picos de carga. Se você atingir o limite, aguarde antes de tentar novamente. Randomize seu tempo de espera para evitar problemas de rebanho. Registre todos os eventos de limite de taxa para depuração. Isso ajuda a identificar padrões no seu uso. Ajuste suas configurações de concorrência com base nesses logs. Não assuma que uma única chave pode lidar com tráfego ilimitado. Distribua a carga entre várias chaves, se necessário. Isso requer gerenciamento de estado cuidadoso. Certifique-se de que cada chave mantenha seu próprio contexto, se necessário.

Gerencie Faturamento Cripto e Recargas

Use crédito pré-pago para cobrir o uso de tokens sem taxas mensais.

Recarregue sua conta com criptomoeda. As redes suportadas incluem USDT na TRC20 e USDC na Base. Os depósitos mínimos começam em $20. Os bônus são aplicados para valores maiores. Você recebe 5% extras para $50, 10% para $100 e 15% para $200. O crédito nunca expira. Isso é ideal para projetos de longo prazo. Você paga apenas pelos tokens realmente usados. Erros e recusas são gratuitos. Isso protege seu orçamento de custos inesperados. Contas novas recebem $0.50 para testes. Reembolsos não são emitidos para compras padrão. Cobranças duplicadas são corrigidas via suporte. Certifique-se de que sua carteira suporta as redes necessárias. Verifique o endereço do contrato antes de enviar. Redes incorretas podem resultar em perda de fundos. Verifique seu saldo regularmente. Saldos baixos podem interromper o serviço inesperadamente. Automatize os recarregamentos, se possível. Isso garante disponibilidade contínua para tarefas críticas.

Teste Filtros de Conteúdo e Recusas

Verifique se o modelo se comporta conforme o esperado com prompts sem censura.

Modelos sem censura ainda podem aplicar limites rígidos. Verifique restrições em tipos específicos de conteúdo. Teste com frases gatilho conhecidas. Certifique-se de que o modelo responda adequadamente. Alguns provedores mantêm filtros por motivos legais. Verifique isso antes de confiar no modelo para dados sensíveis. Teste casos extremos no seu domínio. Envie prompts que normalmente acionam recusas. Observe o formato da resposta. Ele retorna um motivo para a recusa? Ou gera conteúdo silenciosamente? Documente esses comportamentos em seus testes de integração. Isso evita surpresas em produção. Se o modelo mudar seu comportamento, atualize seus testes. Notifique sua equipe sobre quaisquer mudanças significativas. A consistência é fundamental para a confiança do usuário. Certifique-se de que seu aplicativo lide com recusas de forma graciosa. Não assuma que cada resposta é válida. Valide a estrutura da saída. Verifique alucinações ou erros de formatação. Isso garante uma experiência de usuário confiável.

Implementar Tratamento de Erros para Solicitações Gratuitas

Trate os erros com elegância para manter uma experiência de usuário suave.

Erros de rede, tempos limite e erros do servidor podem ocorrer. Implemente lógica de nova tentativa com backoff exponencial. Distinja entre erros transitórios e permanentes. Um erro 429 é transitório. Aguarde e tente novamente. Um erro 400 é permanente. Verifique seus dados de entrada. Um erro 500 é do lado do servidor. Tente novamente com cautela. Registre todos os erros para depuração. Inclua o payload da solicitação e o corpo da resposta. Isso ajuda a reproduzir problemas rapidamente. Não exponha erros brutos aos usuários. Formate-os em mensagens amigáveis ao usuário. Lidere erros de streaming com cuidado. Desconecte-se do fluxo de eventos. Limpe os recursos. Certifique-se de que sua aplicação não vazie memória. Teste cenários de erro minuciosamente. Simule quedas de rede. Simule tempos limite do servidor. Verifique se sua lógica de recuperação funciona. Isso garante confiabilidade sob condições adversas.

Escale com JSON Mode e Tool Calling

Use saídas estruturadas para extração confiável de dados e execução de funções.

Habilite o modo JSON definindo response_format: {type: "json_object"}. Isso força o modelo a gerar JSON válido. Use isso para analisar dados ou gerar configurações. O uso de ferramentas permite que o modelo execute funções. Defina suas ferramentas no payload da requisição. O modelo decide quando chamá-las. Passe os resultados de volta para o modelo. Ele pode gerar uma resposta final com base na saída. Isso cria um loop para tarefas complexas. Certifique-se de que as definições das ferramentas sejam claras. Ferramentas ambíguas levam a chamadas incorretas. Valide a saída JSON antes de analisá-la. Isso evita erros de tempo de execução no seu código. Use chamadas de ferramentas para tarefas de extração de dados. Isso melhora significativamente a precisão. Teste com vários formatos de entrada. Certifique-se de que o modelo lide com casos extremos. Documente as ferramentas disponíveis para sua equipe. Isso garante o uso consistente em todos os projetos.

Revisar Políticas de Privacidade e Uso de Dados

Entenda como seus dados são armazenados e usados pelo provedor.

Verifique a política de privacidade para detalhes sobre retenção de dados. Alguns provedores usam seus dados para treinamento. Outros mantêm seus dados privados. Certifique-se de que seus dados não sejam usados para melhorar o modelo, se isso for importante para você. Verifique os padrões de criptografia. Os dados devem ser criptografados em trânsito e em repouso. Verifique se os logs são armazenados. Os logs podem conter seus prompts. Certifique-se de que esses logs estejam seguros. Revise os termos de serviço para cláusulas de responsabilidade. Entenda quem é proprietário do conteúdo gerado. Alguns provedores reivindicam direitos sobre sua saída. Certifique-se de que isso esteja alinhado com suas necessidades. Exclua sua conta se você não usar mais o serviço. Verifique se seus dados foram removidos. Entre em contato com o suporte se tiver dúvidas. Documente suas configurações de privacidade para fins de auditoria. Isso garante a conformidade com as políticas internas.