Checklist di produzione API OpenRouter

Verifica la compatibilità API e gli endpoint

Utilizza gli endpoint standard compatibili con OpenAI per un'integrazione affidabile.

L'endpoint principale è POST /v1/chat/completions. Questo gestisce la generazione di testo per le cronologie delle chat. Un endpoint secondario, GET /v1/models, elenca i modelli disponibili. Non hai bisogno di endpoint per embeddings o generazione di immagini per attività solo testo. Molti sviluppatori assumono di avere bisogno di uno strato di routing complesso. OpenRouter semplifica questo esponendo un unico punto di ingresso. Invii un payload JSON con l'ID del modello e i prompt di sistema. Il servizio restituisce un JSON strutturato con contenuto e dati di utilizzo. Questo design corrisponde alle aspettative dell'SDK ufficiale OpenAI. Puoi scambiare i modelli senza modificare il codice del client. Aggiorna semplicemente l'ID del modello nella tua configurazione. Assicurati che il tuo client supporti lo schema JSON più recente. Le versioni più vecchie potrebbero rifiutare i nuovi parametri. Testa la tua connessione prima di distribuire in produzione. Verifica che il formato della risposta corrisponda al tuo parser.

Configura autenticazione e chiavi

Proteggi la tua chiave API nelle variabili d'ambiente immediatamente dopo la generazione.

Genera una chiave tramite la dashboard del provider. Memorizzala in una posizione sicura. Non inserirla mai hardcoded nel repository del codice sorgente. Trasmettila tramite Authorization: Bearer <key> header. Ogni chiave è associata a un account specifico. Puoi ruotare le chiavi se sospetti una perdita. Alcuni provider permettono più chiavi per account. Questo ti permette di separare il traffico di sviluppo e produzione. Monitora l'utilizzo per chiave per rilevare anomalie. Revoca regolarmente le chiavi non utilizzate. Utilizza chiavi a breve durata per script temporanei. Questo riduce il raggio d'azione di un compromesso. Assicurati che la tua versione SDK supporti l'autenticazione con token bearer. Le librerie più vecchie potrebbero richiedere un formato di header diverso. Controlla la documentazione per il tuo SDK specifico. Verifica che la chiave abbia un saldo sufficiente. Una chiave scaduta restituisce un errore 401. Una chiave con saldo zero restituisce un errore 402. Distingui tra questi due stati nella tua logica.

Gestisci lo streaming e l'utilizzo dei token

Abilita lo streaming per una latenza inferiore e feedback utente in tempo reale.

Imposta stream: true nel payload della richiesta. Il server invia una serie di Server-Sent Events (SSE). Ogni evento contiene un chunk parziale di testo. Devi assemblare questi chunk per formare la risposta completa. L'ultimo chunk include spesso le statistiche di utilizzo dei token. Questo ti consente di monitorare i costi in tempo reale. Senza lo streaming, attendi l'intera risposta. Questo aumenta significativamente la latenza percepita. Lo streaming è essenziale per le interfacce chat. Crea un effetto di digitazione che sembra reattivo. Fai attenzione alla gestione degli errori durante lo streaming. Se la connessione si interrompe, perdi il chunk corrente. La logica di riconnessione dovrebbe preservare lo stato della conversazione. Alcuni SDK gestiscono lo streaming automaticamente. Altri richiedono listener di eventi manuali. Scegli l'approccio che si adatta alla tua architettura. Assicurati che il tuo parser gestisca chunk JSON incompleti. Non assumere che ogni evento sia un oggetto completo. Memorizza nella cache i dati finché non hai una struttura valida.

Monitora limiti di velocità e concorrenza

Monitora le tue richieste al minuto per evitare interruzioni del servizio.

OpenRouter applica limiti di velocità rigorosi per ogni chiave API. Il superamento di questi limiti attiva un errore 429 Too Many Requests. È necessario implementare un backoff esponenziale nella logica di retry. Anche le richieste concorrenti contano verso i tuoi limiti. Controlla le intestazioni di risposta per la quota rimanente. Alcuni fornitori espongono queste intestazioni direttamente. Altri richiedono di dedurre i limiti dagli errori. L'alta concorrenza può esaurire il pool di connessioni. Assicurati che il tuo client gestisca le connessioni in modo efficiente. Usa il connection pooling per ridurre il sovraccarico. Monitora la profondità della coda durante i picchi di carico. Se raggiungi il limite, aspetta prima di ritentare. Randomizza il tempo di attesa per evitare problemi di stormo. Registra tutti gli eventi di limite di velocità per il debug. Questo aiuta a identificare i modelli nel tuo utilizzo. Regola le impostazioni di concorrenza in base a questi log. Non assumere che una singola chiave possa gestire traffico illimitato. Distribuisci il carico su più chiavi se necessario. Questo richiede una gestione attenta dello stato. Assicurati che ogni chiave mantenga il proprio contesto se necessario.

Gestisci fatturazione crypto e ricariche

Usa il credito prepagato per coprire l'utilizzo dei token senza canoni mensili.

Ricarica il tuo account con criptovaluta. Le reti supportate includono USDT su TRC20 e USDC su Base. I depositi minimi partono da $20. I bonus si applicano per importi più elevati. Ricevi un extra del 5% per $50, il 10% per $100 e il 15% per $200. Il credito non scade mai. Questo è ideale per progetti a lungo termine. Paghi solo per i token effettivamente utilizzati. Errori e rifiuti sono gratuiti. Questo protegge il tuo budget da costi imprevisti. I nuovi account ricevono $0.50 per i test. Non vengono emessi rimborsi per gli acquisti standard. I doppi addebiti vengono corretti tramite assistenza. Assicurati che il tuo wallet supporti le reti richieste. Verifica l'indirizzo del contratto prima di inviare. Reti errate possono comportare la perdita di fondi. Controlla il tuo saldo regolarmente. Saldi bassi possono interrompere il servizio in modo imprevisto. Automatizza le ricariche se possibile. Questo garantisce la disponibilità continua per le attività critiche.

Testa i filtri dei contenuti e i rifiuti

Verifica che il modello si comporti come previsto con i prompt non censurati.

I modelli uncensored potrebbero ancora applicare limiti rigidi. Controlla le restrizioni su specifici tipi di contenuto. Testa con frasi trigger note. Assicurati che il modello risponda in modo appropriato. Alcuni provider mantengono filtri per motivi legali. Verifica questi prima di fare affidamento sul modello per dati sensibili. Testa i casi limite nel tuo dominio. Invia prompt che tipicamente attivano i rifiuti. Osserva il formato della risposta. Restituisce un motivo per il rifiuto? O genera contenuti in silenzio? Documenta questi comportamenti nei tuoi test di integrazione. Questo previene sorprese in produzione. Se il modello cambia il suo comportamento, aggiorna i tuoi test. Notifica il tuo team di eventuali cambiamenti significativi. La coerenza è fondamentale per la fiducia degli utenti. Assicurati che la tua applicazione gestisca i rifiuti in modo elegante. Non assumere che ogni risposta sia valida. Convalida la struttura dell'output. Controlla le allucinazioni o gli errori di formattazione. Questo garantisce un'esperienza utente affidabile.

Implementare la gestione degli errori per le richieste gratuite

Gestisci gli errori in modo elegante per mantenere un'esperienza utente fluida.

Possono verificarsi errori di rete, timeout ed errori del server. Implementa una logica di retry con backoff esponenziale. Distingui tra errori transitori e permanenti. Un errore 429 è transitorio. Attendi e riprova. Un errore 400 è permanente. Controlla i tuoi dati di input. Un errore 500 è lato server. Riprova con cautela. Registra tutti gli errori per il debug. Includi il payload della richiesta e il corpo della risposta. Ciò aiuta a riprodurre rapidamente i problemi. Non esporre gli errori grezzi agli utenti. Formattali in messaggi adatti all'utente. Gestisci con cura gli errori di streaming. Disconnettiti dal flusso di eventi. Pulisci le risorse. Assicurati che la tua applicazione non perda memoria. Testa accuratamente gli scenari di errore. Simula le cadute di rete. Simula i timeout del server. Verifica che la tua logica di recupero funzioni. Ciò garantisce l'affidabilità in condizioni avverse.

Scala con la Modalità JSON e il Tool Calling

Usa gli output strutturati per un'estrazione affidabile dei dati e l'esecuzione delle funzioni.

Abilita la modalità JSON impostando response_format: {type: "json_object"}. Questo forza il modello a restituire JSON valido. Usalo per l'analisi dei dati o la generazione di configurazioni. Il tool calling permette al modello di eseguire funzioni. Definisci i tuoi strumenti nel payload della richiesta. Il modello decide quando chiamarli. Passa i risultati al modello. Può generare una risposta finale basata sull'output. Questo crea un ciclo per attività complesse. Assicurati che le definizioni degli strumenti siano chiare. Strumenti ambigui portano a chiamate errate. Convalida l'output JSON prima dell'analisi. Questo previene errori di runtime nel tuo codice. Usa il tool calling per le attività di estrazione dei dati. Migliora significativamente l'accuratezza. Testa con vari formati di input. Assicurati che il modello gestisca i casi limite. Documenta gli strumenti disponibili per il tuo team. Questo garantisce un utilizzo coerente tra i progetti.

Rivedi le Politiche sulla Privacy e l'Utilizzo dei Dati

Comprendere come il provider memorizza e utilizza i tuoi dati.

Controlla l'informativa sulla privacy per i dettagli sulla conservazione dei dati. Alcuni provider utilizzano i tuoi dati per l'addestramento. Altri li mantengono privati. Assicurati che i tuoi dati non vengano utilizzati per il miglioramento del modello se ciò è importante per te. Verifica gli standard di crittografia. I dati dovrebbero essere crittografati in transito e a riposo. Controlla se vengono conservati i log. I log potrebbero contenere i tuoi prompt. Assicurati che questi log siano sicuri. Rivedi i termini di servizio per le clausole di responsabilità. Comprendi chi detiene i diritti sui contenuti generati. Alcuni provider rivendicano diritti sui tuoi output. Assicurati che ciò sia in linea con le tue esigenze. Elimina il tuo account se non utilizzi più il servizio. Verifica che i tuoi dati siano rimossi. Contatta il supporto se hai dubbi. Documenta le tue impostazioni sulla privacy per scopi di audit. Ciò garantisce la conformità alle policy interne.