IT ▾
Ottieni la chiave API

Endpoint compatibile con OpenAI per client OpenRouter

Un endpoint compatibile con OpenAI di OpenRouter è semplicemente un URL di base che parla il formato chat di OpenAI, quindi sostituirlo con un altro richiede poche righe. Ecco i valori esatti, le forme delle richieste e gli errori che potresti incontrare.

Aggiornato

Un singolo cavo che collega un terminale a un cubo modello luminoso, che rappresenta un endpoint API sostituito

Punti chiave

  • L'URL di base è https://api.openrouteralternativeapi.com/v1 e l'ID del modello è uncensored.
  • L'autenticazione è un header Bearer standard; esistono solo POST /v1/chat/completions e GET /v1/models.
  • Streaming, strumenti e modalità JSON funzionano, ma i campi specifici del router non sono supportati.
  • Su HTTP 429, leggi il codice di errore per distinguere un limite di richieste da un limite di concorrenza.

I valori di cui hai bisogno

Qualsiasi strumento che ti permette di modificare un endpoint in stile OpenAI richiede tre valori. Copiali dalla tabella e nulla altro cambierà in una configurazione tipica.

ImpostazioneValore
URL di basehttps://api.openrouteralternativeapi.com/v1
Chiave APICreato nella pagina delle chiavi API
ID modellouncensored
Intestazione di autenticazioneAuthorization: Bearer YOUR_API_KEY
Endpoint chatPOST /v1/chat/completions
Route dell'elenco dei modelliGET /v1/models

La base URL termina già con /v1. La maggior parte degli SDK aggiunge /chat/completions da soli, quindi non aggiungerlo due volte. Alcuni strumenti richiedono la route chat completa; in quel caso usa la base URL seguita da /chat/completions.

Cosa è e cosa non è l'endpoint

Dietro l'URL si trova un unico modello a pesi aperti, gestito da un provider indipendente e ottimizzato per rispondere senza rifiuti di contenuto per l'uso adulto lecito. Non è un router, quindi una richiesta non viene mai inoltrata a un fornitore diverso. Non è nemmeno l'API ufficiale di alcun creatore di modelli. Questo è importante per la configurazione: non c'è un elenco di slug di modelli tra cui scegliere, nessun campo di preferenza del provider e nessuna catena di fallback. Invii uncensored e ottieni quel modello.

Il servizio è solo testo. Generazione di immagini, audio, video, embeddings e fine-tuning non sono offerti, quindi un client che chiama /v1/embeddings o una route per le immagini fallirà su questa base URL. Mantieni quelle chiamate puntate verso qualsiasi servizio tu usi già per esse e imposta la base URL per funzionalità piuttosto che globalmente se la tua applicazione ne mescola diverse.

Un altro punto di compatibilità riguarda l'elenco dei modelli. Un client che chiama GET /v1/models all'avvio, per popolare un menu a discesa o per convalidare un'impostazione, riceverà l'unico modello. È previsto. Se il tuo codice verifica che un nome di modello configurato appaia nell'elenco, imposta il nome a uncensored e il controllo supera. Se la tua applicazione codifica hardcoded un nome di modello di un fornitore da qualche parte in profondità in un file di configurazione, cerca nel repository prima della prima esecuzione, perché una stringa residua è la ragione più comune per cui un'app migrata fallisce ancora dopo che l'URL è stato modificato.

Prima richiesta, tre modi

Inizia con una richiesta dal terminale. Essa dimostra la chiave, l'URL e l'ID del modello prima che qualsiasi framework sia coinvolto.

curl https://api.openrouteralternativeapi.com/v1/models   -H "Authorization: Bearer $API_KEY"

curl https://api.openrouteralternativeapi.com/v1/chat/completions   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 10
  }'

La stessa chiamata con l'SDK Python. Nota che nulla oltre a base_url e api_key differisce dal codice OpenAI standard.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.openrouteralternativeapi.com/v1",
    api_key="YOUR_API_KEY",
)

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Reply with the word ready."}],
    max_tokens=10,
)
print(r.choices[0].message.content)
print(r.usage)

E con Node, leggendo la chiave da una variabile d'ambiente:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.openrouteralternativeapi.com/v1",
  apiKey: process.env.API_KEY,
});

const r = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Reply with the word ready." }],
  max_tokens: 10,
});
console.log(r.choices[0].message.content);

Molti strumenti leggono le variabili d'ambiente invece degli argomenti del costruttore. Gli SDK ufficiali onorano comunemente OPENAI_BASE_URL e OPENAI_API_KEY, il che ti permette di reindirizzare uno script non modificato. Controlla la documentazione della tua versione SDK per confermare i nomi.

Streaming, strumenti e modalità JSON

Le funzionalità su cui la maggior parte dei client dipende sono presenti. Imposta stream: true per ricevere eventi inviati dal server; l'utilizzo viene segnalato alla fine dello stream. La chiamata di funzioni accetta tools e tool_choice, trasmette tool_calls delta e si aspetta risultati indietro come messaggi con role: "tool". La modalità JSON è abilitata con response_format: {"type":"json_object"}. I campi di campionamento temperature, top_p, stop, seed e le penalità di frequenza e presenza sono passati attraverso.

Un esempio di streaming in Python:

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write three short taglines for a coffee cart."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

E la modalità JSON, che vale la pena abbinare a un'istruzione nel prompt che nomina le chiavi che ti aspetti:

r = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Return JSON with keys title and tags (array of strings)."},
        {"role": "user", "content": "Summarise: a guide to brewing cold coffee at home."},
    ],
    response_format={"type": "json_object"},
)
print(r.choices[0].message.content)

Analizza sempre il risultato comunque in un blocco try. La modalità JSON aumenta le probabilità di output valido ma il tuo codice dovrebbe comunque gestire una risposta malformata, ad esempio ritentando una volta.

Chat multi-turno e chiamate di funzioni

L'endpoint è stateless, come la route chat di OpenAI. Non ricorda le chiamate precedenti, quindi ogni richiesta deve contenere la conversazione che vuoi che il modello veda. Tieni un elenco di messaggi, aggiungi la risposta dell'assistente dopo ogni turno e invia di nuovo l'elenco intero. Attento al totale: la finestra da 100.000 token copre prompt più completamento, e le cronologie lunghe sono anche ciò che guida il costo di input.

history = [{"role": "system", "content": "You answer in two sentences."}]

def chat(text):
    history.append({"role": "user", "content": text})
    r = client.chat.completions.create(model="uncensored", messages=history)
    reply = r.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

Per la chiamata di funzioni, descrivi le tue funzioni in tools, esegui qualsiasi cosa il modello chieda e invia l'output indietro come un messaggio role: "tool" che trasporta il matching tool_call_id. Una definizione minimale sembra così:

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up an order by its number",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Where is order 1042?"}],
    tools=tools,
    tool_choice="auto",
)
call = r.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)

Convalida gli argomenti prima di eseguire qualsiasi cosa. Il modello propone una chiamata; il tuo codice decide se è sicuro eseguire, specialmente quando la funzione tocca denaro, file o dati di altre persone.

Campi da rimuovere dalle richieste in stile OpenRouter

I client scritti per un router spesso aggiungono extra al corpo della richiesta o agli header. Gli esempi tipici sono l'ordinamento dei provider, gli array di fallback del modello, le preferenze di routing e gli header di attribuzione. Questa API non li usa. Campi sconosciuti potrebbero essere ignorati o potrebbero causare un errore, a seconda del campo, quindi rimuovili piuttosto che fare affidamento su uno dei due esiti.

  • Sostituisci qualsiasi slug del modello che include un prefisso vendor con uncensored.
  • Elimina gli elenchi di fallback. Se il modello singolo non è disponibile, gestiscilo nella tua logica di retry.
  • Non inviare parti di contenuto immagine o audio. Il modello legge testo.
  • Mantieni il corpo della richiesta totale sotto 8 MB.

La pagina docs mostra i parametri che sono supportati, ed è il posto dove controllare quando un campo si comporta in modo diverso da quanto si aspetta il tuo client.

Limiti e risposte 429

Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto; una chiave trial permette 2 e 60. Ogni risposta trasporta X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency. Registra l'ID della richiesta con ogni fallimento, perché è la prima cosa che il supporto chiederà.

Ci sono tre tipi di HTTP 429. Il codice di errore rate_limited significa che hai superato le richieste al minuto: rallenta. Il codice concurrency significa che troppe richieste sono in corso simultaneamente: accodale. Un 429 con un header Retry-After: 5 significa sovraccarico temporaneo: aspetta cinque secondi e riprova. Ricorda che una richiesta streaming mantiene il suo slot di concorrenza fino alla fine dello stream, quindi un client bloccato che non legge fino alla fine consumerà capacità.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.openrouteralternativeapi.com/v1",
    api_key="YOUR_API_KEY",
    max_retries=0,
)

def ask(prompt, tries=4):
    for i in range(tries):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            wait = 5 if i == 0 else 5 * (i + 1)
            time.sleep(wait)
    raise RuntimeError("still rate limited")

Imposta anche un semaforo di 8 o meno attorno alle chiamate se esegui worker in parallelo. È più economico che imparare il limite dagli errori. Aggiungi un piccolo jitter casuale all'attesa in modo che diversi worker che hanno fallito insieme non ritentino tutti nello stesso secondo. Se vedi risposte 429 ripetute a basso traffico, cerca stream che vengono aperti ma mai chiusi, o un loop di retry che si attiva senza attendere, poiché entrambi possono riempire gli slot disponibili da soli.

Verifica dei costi prima di puntare la produzione

I prezzi sono $0,15 per 1M token di input e $0,50 per 1M token di output dal credito prepagato. Prendi una richiesta con 2.000 token di input e 500 token di output. L'input costa 2.000 / 1.000.000 x $0,15 = $0,0003. L'output costa 500 / 1.000.000 x $0,50 = $0,00025. La richiesta costa $0,00055, quindi 1.000 tali richieste costano $0,55. Le richieste fallite o rifiutate non sono addebitate. Vedi la pagina dei prezzi per importi di ricarica e bonus; il credito trial di $0,50 copre circa 900 richieste di quelle dimensioni (0,50 / 0,00055).

Domande e risposte

Qual è l'URL di base per l'endpoint compatibile con OpenAI?

Usa https://api.openrouteralternativeapi.com/v1 come URL di base e invia la tua chiave come token Bearer. L'ID del modello è uncensored.

Quali route sono disponibili?

POST /v1/chat/completions per la generazione e GET /v1/models per l'elenco dei modelli. Non ci sono route per embedding, immagini, audio o fine-tuning.

Devo modificare il codice oltre all'URL e alla chiave?

Di solito solo la stringa del modello. Rimuovi i campi specifici del router come le preferenze del provider o gli elenchi di fallback dai corpi delle richieste.

Perché ottengo HTTP 429?

Controlla il codice di errore. rate_limited indica troppe richieste al minuto, concurrency indica troppe richieste simultanee e un header Retry-After: 5 indica un sovraccarico temporaneo.

La tua chiave è a un modulo di distanza

Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.