Guida alla risoluzione dei problemi API OpenRouter

Comprendere l'URL di base

L'URL di base definisce dove il tuo client invia le richieste. Un disallineamento qui causa immediati fallimenti di connessione o risposte del modello impreviste. Molti sviluppatori assumono che l'URL standard di OpenAI funzioni universalmente, ma i fornitori senza censure utilizzano spesso endpoint distinti per instradare il traffico verso pool di modelli specifici.

Verifica che la tua configurazione punti a https://api.openrouterabliteratedmodels.com/v1 per il nostro servizio. Se stai utilizzando un aggregatore di terze parti, assicurati che l'URL di base corrisponda esattamente alla loro documentazione. URL errati spesso risultano in errori 404 o risposte da modelli predefiniti invece della variante non censurata intesa.

• Verifica le variabili d'ambiente per BASE_URL o API_HOST.
• Assicurati che il percorso includa /v1 per la compatibilità standard.
• Testa la connettività con una semplice richiesta dell'elenco dei modelli prima di un utilizzo intensivo.

Gestione dei limiti di frequenza

I limiti di frequenza restringono il numero di richieste che puoi inviare entro un intervallo di tempo specifico. La nostra API impone un limite di 300 richieste al minuto per chiave. Il superamento di questa soglia genera errori HTTP 429, bloccando temporaneamente le richieste successive fino al reset della finestra.

Inoltre, esiste un limite alle richieste concorrenti di 8 richieste contemporanee per chiave. Se invii più di 8 richieste simultanee, l'eccesso verrà accodato o fallirà a seconda della tua libreria client. Monitora la concorrenza della tua applicazione per evitare di superare questi limiti rigidi. Utilizza strategie di backoff esponenziale nel tuo codice per gestire gli errori 429 in modo elegante senza sovraccaricare il server.

Ricorda che ogni chiave è unica per il tuo account. Condividere le chiavi tra più servizi può accelerare il raggiungimento di questi limiti. Genera una nuova chiave se hai bisogno di pool di limiti di velocità separati per diverse parti della tua applicazione.

Risposte: streaming vs non-streaming

Lo streaming restituisce dati in modo incrementale man mano che i token vengono generati, mentre il non-streaming attende la risposta completa. Lo streaming è essenziale per le esperienze utente in tempo reale ma richiede una gestione attenta di Server-Sent Events (SSE).

Quando esegui lo streaming, l'ultimo chunk contiene le statistiche sull'utilizzo dei token. Se interrompi l'elaborazione in anticipo, potresti perdere questi dati. Assicurati che il tuo client analizzi l'ultimo messaggio SSE per recuperare con precisione i conteggi dei token di input e output. Le risposte non in streaming sono più semplici ma possono causare elevata latenza per output lunghi.

Scegli lo streaming per le interfacce chat dove gli utenti vedono il testo apparire carattere per carattere. Usa il non-streaming per l'elaborazione in batch o quando hai bisogno della risposta completa prima di procedere. La nostra API supporta entrambe le modalità tramite stream il parametro nel corpo della richiesta.

Errori modalità JSON

La modalità JSON garantisce che il modello produca JSON valido, fondamentale per l'integrazione programmatica. Gli errori in questo ambito derivano spesso da header errati o mismatch degli schema. L'API richiede response_format: {"type": "json_object"} per imporre un output JSON rigoroso.

Se ricevi JSON non valido, controlla la definizione del tuo schema. Il modello potrebbe includere blocchi di codice markdown o testo esplicativo al di fuori della struttura JSON. Utilizza un parser robusto in grado di rimuovere i marcatori markdown o di convalidare l'output rispetto allo schema previsto. Evita schemi troppo complessi che potrebbero confondere il modello.

Testa prima con strutture semplici. Aggiungi gradualmente complessità per identificare dove il modello fatica. Assicurati che la tua temperatura sia impostata in modo appropriato, poiché temperature più elevate possono aumentare la casualità e ridurre la validità del JSON.

Errori di Calcolo del Conteggio dei Token

I conteggi dei token determinano la tua fatturazione e l'utilizzo della finestra di contesto. Calcoli errati possono portare a addebiti imprevisti o risposte troncate. La nostra API addebita $0.15 per 1M di token di input e $0.50 per 1M di token di output.

Utilizza una libreria di tokenizzazione affidabile che corrisponda allo schema di tokenizzazione del modello. Modelli diversi possono tokenizzare spazi bianchi o punteggiatura in modo diverso, portando a discrepanze tra il conteggio locale e quello dell'API. Affidati sempre all'utilizzo dei token restituito nella risposta per una fatturazione accurata.

Tieni d'occhio la tua finestra di contesto, che è di 100.000 token in totale. Superare questo limite causerà errori. Tronca i messaggi o i riassunti più vecchi per rimanere entro i limiti. Monitora l'utilizzo dei token nel tempo per ottimizzare la struttura dei prompt e ridurre i costi.

Ritardi nei pagamenti con criptovalute

Le ricariche in criptovaluta tramite USDT (TRC20) o USDC (Base) vengono elaborate istantaneamente dal nostro lato. Tuttavia, la congestione della rete può talvolta causare lievi ritardi nella conferma. Assicurati di inviare l'importo corretto e sulla rete giusta per evitare perdite.

Le ricariche vanno da $20 a $500 in importi interi. I crediti bonus si applicano automaticamente: +5% da $50, +10% da $100 e +15% da $200. Verifica l'hash della transazione per confermare il pagamento. Se i crediti non appaiono entro pochi minuti, controlla l'esploratore della blockchain per lo stato della transazione.

Il credito non scade mai, quindi non c'è fretta di utilizzarlo immediatamente. Errori come le addebiti doppi vengono risolti tramite la pagina Supporto. Conserva i record delle transazioni per un facile riferimento in caso di problemi.

Configurazione ID modello

L'ID del modello identifica quale versione del modello uncensored stai utilizzando. Per il nostro servizio, l'ID del modello è uncensored. Usare un ID errato può causare errori o comportamenti imprevisti.

Assicurati che le tue richieste specifichino model: "uncensored" nel corpo della richiesta. Questo ID punta al nostro modello open-weight specifico ottimizzato per risposte non filtrate. Non è un identificatore generico ma un puntatore specifico alla nostra istanza ospitata.

Verifica la documentazione della tua libreria client per sapere come impostare l'ID del modello. Alcune librerie usano un model campo, mentre altri potrebbero utilizzare un parametro diverso. La coerenza nell'uso dell'ID del modello nella tua applicazione evita confusione e garantisce che tu stia sempre chiamando il modello uncensored previsto.

Superamenti della finestra di contesto

La finestra di contesto limita il numero totale di token che puoi inviare in una singola richiesta. La nostra API supporta una finestra di 100.000 token, inclusi prompt e completamento. Il superamento di questo limite restituisce un errore.

Per gestire il contesto, implementa una strategia a finestra scorrevole. Rimuovi i messaggi più vecchi o riassumili per liberare spazio. Monitora il conteggio dei token del tuo input per assicurarti che rimanga entro il limite di 100.000 token. Se superi il limite, l'API rifiuterà la richiesta.

Usa il max_tokens parametro per controllare la lunghezza dell'output. Il massimo output per richiesta è 16.000 token. Impostare questo parametro aiuta a prevenire un utilizzo eccessivo di token e mantiene le risposte entro limiti gestibili per la tua applicazione.

Supporto e politica sui rimborsi

Il credito non viene rimborsato una volta utilizzato, ma non scade mai. Se riscontri problemi con i pagamenti o il servizio, contatta il Support tramite la pagina dedicata. Errori come gli addebiti doppi vengono risolti dal team di Support.

Per problemi tecnici, controlla prima la documentazione. La nostra API è semplice, ma possono verificarsi casi limite. Fornisci la tua chiave API e i dettagli della richiesta quando cerchi assistenza. I tempi di risposta variano, ma ci impegniamo a risolvere i problemi rapidamente.

Ricorda che il credito è prepagato. Paghi ciò che consumi, con errori e rifiuti gratuiti. Questo modello garantisce trasparenza nella fatturazione. Usa la pagina Supporto per eventuali discrepanze o domande sul tuo account.