Open API

A Reverie oferece um endpoint de Chat Completions compatível com OpenAI. Aponte qualquer cliente da OpenAI para ele, passe uma chave de API da Reverie e use o campo model para nomear um personagem ou cenário em vez de um LLM. A Reverie guarda a conversa, as memórias e os resumos do lado dela, então cada requisição só precisa da sua mensagem nova.

Qualquer conta com login pode usar. Não há faixa de assinatura nem lista de espera — você precisa de uma chave de API, e é só. Criar uma →

URL base e autenticação

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

Configurações → Mais → Chaves de API mostra a URL base exata no cartão API Endpoint, com um botão de copiar.

Começando rápido

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
}'

Configurações → Mais → Chaves de API também tem um construtor de requisições que gera esses três trechos com uma das suas chaves reais e um personagem real.

O campo model nomeia um personagem

Detalhes que decidem se um ID curto resolve:

• O [...] precisa estar no fim da string.
• Um sufixo de 8 caracteres ou menos só é comparado com personagens com quem você já tem conversa, na web ou pela API. O ID curto de um personagem que você nunca abriu falha em silêncio.
• A busca de cenário só roda quando a chave está presa a um personagem. Com uma chave global, um ID curto de cenário nunca resolve.
• Mais de 8 caracteres é tratado como ID completo.

Listar com quem você pode falar

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

Uma chave global devolve os seus personagens recentes. Uma chave presa a um personagem devolve os cenários daquele personagem, ou o próprio personagem se ele não tiver nenhum. Cada entrada se parece com isto:

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

Copie o id direto para model. Os erros deste endpoint usam um formato de erro simples, não o envelope da OpenAI.

O que o corpo da requisição lê

Quatro campos são lidos. Todo o resto é aceito e descartado em silêncio.

Ignorados sem aviso: max_tokens, top_p, n, stop, presence_penalty, frequency_penalty, logit_bias, seed, user, response_format, tools, tool_choice, logprobs, stream_options.

Como messages é tratado:

• Mensagens system são descartadas. Personalidade e comportamento vêm dos campos do próprio personagem, não da requisição. Campos do prompt →
• Não há suporte a visão. O conteúdo pode ser uma string ou um array de partes, mas só as partes text são lidas; partes de imagem são ignoradas.
• Só a última mensagem user é acrescentada à conversa. Mensagens de usuário anteriores são ignoradas.
• Mensagens de assistente servem apenas para sincronizar o histórico (abaixo).
• Uma última mensagem de usuário vazia ou só com espaços devolve missing_user_message.

Respostas

Uma resposta sem streaming é um objeto chat.completion comum. finish_reason é sempre stop — chamadas internas de ferramenta nunca aparecem — e os contadores de usage vêm zerados, então meça tokens pelas estatísticas de uso da página de chaves de API, não pela resposta.

Uma resposta em streaming é text/event-stream:

1. Trechos de conteúdo: objetos chat.completion.chunk com delta.content. Nenhum trecho inicial delta: {"role": "assistant"} é enviado.
2. Um trecho de encerramento, com finish_reason igual a stop, length ou content_filter. Encerramentos por chamada de ferramenta são relatados como stop.
3. Um trecho de uso com o array choices vazio.
4. data: [DONE].

Se a geração falhar no meio do stream, o stream emite data: {"error": {...}} e depois [DONE].

Estado da conversa

A Reverie guarda a conversa. Existe uma conversa para cada par de chave e personagem, ela aparece no app web junto das suas outras conversas, e cada turno é montado com o prompt de sistema e o cenário do personagem, o cânone dos world books, as memórias de longo prazo, os resumos que vão se acumulando, o estilo de narração do personagem, o tamanho de resposta e os ajustes NSFW, uma trava de idioma vinda do idioma da sua conta, e tanto do histórico recente quanto couber na janela de contexto do modelo. As ferramentas de memória rodam quando o modelo aceita ferramentas.

Como o servidor guarda o histórico, você não precisa mandá-lo de novo.

Qual LLM responde

Quem decide é o personagem, não a requisição — a não ser que você nomeie um LLM. Precedência, da mais fraca à mais forte: o modelo de conversa padrão, depois a configuração de modelo do próprio personagem, depois um ID de modelo da Reverie passado em model, e por fim a preferência de modelo que você definiu para aquela conversa no app web, que ganha de todas. Modelos →

Erros

Os erros de /chat/completions usam o envelope da OpenAI: {"error": {"message", "type", "param": null, "code"}}.

Dois casos ficam fora desse envelope: os erros do GET /models e os corpos de requisição rejeitados pela validação (uma temperature fora da faixa, por exemplo) — ambos devolvem um formato de erro simples.

Limites de uso e cotas

Esta API não tem limite de requisições por chave, nem teto de concorrência, nem cota de requisições. Duas coisas limitam o seu uso:

A janela de modelos gratuitos é dividida com a conversa na web, as histórias, os romances e os bots — é uma cota por conta, não uma por lugar. Modelos gratuitos →

A Reverie não manda webhooks para fora; não há nada a que se inscrever para saber quando a geração terminou.

Importar personagens

Um segundo endpoint, POST /api/v1/characters/import, cria um personagem a partir de uma ficha de personagem. Ele exige uma chave com escopo de importação, que não é o tipo de chave que a página de configurações cria. Chaves de API → e Importar personagens →

Relacionado

• Chaves de API — criar, prender, expirar e acompanhar chaves
• Modelos — IDs de modelo e multiplicadores de créditos
• Limites — os outros tetos do produto
• Créditos — como as requisições são cobradas