Open API

Reverie espone un endpoint Chat Completions compatibile con OpenAI. Punta qualunque client OpenAI su di esso, passa una chiave API Reverie e usa il campo model per indicare un personaggio o uno scenario invece di un LLM. Reverie tiene dalla sua parte la conversazione, i ricordi e i riassunti, così ogni richiesta ha bisogno solo del tuo messaggio nuovo.

Può usarlo qualsiasi account con l'accesso fatto. Non c'è un livello di abbonamento né una lista d'attesa: serve una chiave API, e basta. Creane una →

URL di base e autenticazione

https://www.reverie.im/api/device/v1
Authorization: Bearer rk_...

Impostazioni → Altro → Chiavi API mostra l'URL di base esatto nella scheda API Endpoint, con un pulsante per copiarlo.

Avvio rapido

curl --no-buffer https://www.reverie.im/api/device/v1/chat/completions \
  -H "Authorization: Bearer $REVERIE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
  "model": "Luna [abc12345]",
  "messages": [
    {
      "role": "user",
      "content": "Hi"
    }
  ],
  "stream": true,
  "temperature": 0.8
}'

Impostazioni → Altro → Chiavi API ha anche un costruttore di richieste che genera questi tre frammenti usando una delle tue chiavi vere e un personaggio vero.

Il campo model indica un personaggio

Dettagli che decidono se un ID breve si risolve:

• Il [...] deve stare alla fine della stringa.
• Un suffisso di 8 caratteri o meno viene confrontato solo con i personaggi con cui hai già una chat, sul web o tramite API. L'ID breve di un personaggio mai aperto fallisce in silenzio.
• La ricerca dello scenario parte solo quando la chiave è fissata a un personaggio. Con una chiave globale, un ID breve di scenario non si risolve mai.
• Oltre gli 8 caratteri viene trattato come ID completo.

Elencare con chi puoi parlare

curl https://www.reverie.im/api/device/v1/models \
  -H "Authorization: Bearer $REVERIE_API_KEY"

Una chiave globale restituisce i tuoi personaggi recenti. Una chiave fissata a un personaggio restituisce invece gli scenari di quel personaggio, o il personaggio stesso se non ne ha. Ogni voce è fatta così:

{
	"id": "Luna [abc12345]",
	"object": "model",
	"created": 1759200000,
	"owned_by": "character",
	"permission": [],
	"root": "<full character id>",
	"parent": null
}

Copia id così com'è dentro model. Gli errori di questo endpoint usano una forma d'errore semplice invece dell'involucro OpenAI.

Cosa legge il corpo della richiesta

Vengono letti quattro campi. Tutto il resto è accettato e scartato in silenzio.

Ignorati senza avviso: max_tokens, top_p, n, stop, presence_penalty, frequency_penalty, logit_bias, seed, user, response_format, tools, tool_choice, logprobs, stream_options.

Come viene trattato messages:

• I messaggi system vengono scartati. Personalità e comportamento vengono dai campi del personaggio, non dalla richiesta. Campi del prompt →
• Non c'è supporto per le immagini. Il contenuto può essere una stringa o un array di parti, ma si leggono solo le parti text; le parti immagine sono ignorate.
• Alla conversazione viene aggiunto solo l'ultimo messaggio user. I messaggi utente precedenti sono ignorati.
• I messaggi dell'assistente servono solo a sincronizzare la cronologia (vedi sotto).
• Un ultimo messaggio utente vuoto o fatto di soli spazi restituisce missing_user_message.

Risposte

Una risposta senza streaming è un normale oggetto chat.completion. finish_reason è sempre stop — le chiamate interne agli strumenti non vengono mai esposte — e i contatori di usage sono a zero, quindi misura i token dalle statistiche d'uso nella pagina delle chiavi API, non dalla risposta.

Una risposta in streaming è un text/event-stream:

1. Blocchi di contenuto: oggetti chat.completion.chunk con delta.content. Non viene inviato un blocco iniziale delta: {"role": "assistant"}.
2. Un blocco di chiusura, con finish_reason pari a stop, length o content_filter. Le chiusure dovute a chiamate di strumenti sono riportate come stop.
3. Un blocco d'uso con l'array choices vuoto.
4. data: [DONE].

Se la generazione fallisce a metà stream, lo stream emette data: {"error": {...}} e poi [DONE].

Stato della conversazione

La conversazione la conserva Reverie. Esiste una chat per ogni coppia chiave-personaggio, compare nell'app web accanto alle tue altre chat, e ogni turno è costruito con il prompt di sistema e lo scenario del personaggio, il canone dei world book, i ricordi a lungo termine, i riassunti via via aggiornati, lo stile narrativo del personaggio, la lunghezza della risposta e le impostazioni NSFW, un blocco della lingua preso dalla lingua del tuo account, e tutta la cronologia recente che la finestra di contesto del modello riesce a contenere. Gli strumenti di memoria girano quando il modello li supporta.

Dato che la cronologia la tiene il server, non devi rimandarla.

Quale LLM risponde

Decide il personaggio, non la richiesta — a meno che tu non indichi un LLM. Precedenza, dalla più bassa alla più alta: il modello di chat predefinito, poi l'impostazione di modello del personaggio, poi un ID di modello Reverie passato come model, e infine la preferenza di modello che hai impostato per quella chat nell'app web, che batte tutte le altre. Modelli →

Errori

Gli errori di /chat/completions usano l'involucro OpenAI: {"error": {"message", "type", "param": null, "code"}}.

Due casi restano fuori da quell'involucro: gli errori di GET /models e i corpi di richiesta respinti dalla validazione (una temperature fuori intervallo, per esempio) — entrambi restituiscono una forma d'errore semplice.

Limiti di frequenza e quote

Questa API non ha limiti di frequenza per chiave, né un tetto di concorrenza, né una quota di richieste. A limitare il tuo uso sono due cose sole:

La finestra dei modelli gratuiti è condivisa con la chat web, le storie, i romanzi e i bot: è un'unica dotazione per account, non una per ciascun posto. Modelli gratuiti →

Reverie non invia webhook in uscita; non c'è nulla a cui iscriversi per sapere quando una generazione è finita.

Importare personaggi

Un secondo endpoint, POST /api/v1/characters/import, crea un personaggio da una scheda personaggio. Richiede una chiave con l'ambito di importazione, che non è il tipo di chiave creato dalla pagina delle impostazioni. Chiavi API → e Importare personaggi →

Correlati

• Chiavi API — creare, fissare, far scadere e tenere d'occhio le chiavi
• Modelli — ID dei modelli e moltiplicatori di crediti
• Limiti — gli altri tetti del prodotto
• Crediti — come vengono tariffate le richieste