开放 API

Reverie 提供一个与 OpenAI 兼容的 Chat Completions 接口。把任意 OpenAI 客户端指向它，带上一个 Reverie API 密钥，然后用 model 字段填角色或情景，而不是某个大模型。对话、记忆和摘要都由 Reverie 保存在它那一侧，所以每次请求只需要带上你的新消息。

任何已登录的账号都能用。不需要什么订阅档位，也没有等候名单——你只需要一个 API 密钥，仅此而已。去创建 →

基址与鉴权

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

设置 → 更多 → API 密钥里的 API Endpoint 卡片会显示准确的基址，旁边有复制按钮。

快速上手

curl --no-buffer https://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
}'

设置 → 更多 → API 密钥里还有一个请求构建器，会用你真实的某个密钥和一个真实角色生成上面这三段代码。

model 字段填的是角色

决定短 ID 能不能解析出来的几个细节：

• [...] 必须在字符串的末尾。
• 长度不超过 8 个字符的后缀，只会在你已经和它有过聊天的角色里匹配，无论是在网页上还是通过 API。你从没打开过的角色，它的短 ID 会悄悄落空。
• 只有当密钥绑定了某个角色时，才会去查情景。用全局密钥时，短情景 ID 永远解析不出来。
• 超过 8 个字符会被当成完整 ID。

列出你能对话的对象

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

全局密钥返回你最近的角色。绑定了角色的密钥则返回那个角色的情景，如果它一个情景都没有，就返回角色本身。每一条看起来是这样：

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

把 id 原样复制进 model 就行。这个接口的报错用的是朴素的错误结构，而不是 OpenAI 的外壳。

请求体里哪些字段会被读取

只有四个字段会被读取。其余的都会被接受，然后悄悄丢掉。

会被忽略且不提示的字段： max_tokens, top_p, n, stop, presence_penalty, frequency_penalty, logit_bias, seed, user, response_format, tools, tool_choice, logprobs, stream_options.

messages 是怎么处理的：

• system 消息会被丢掉。 人设和行为来自角色自己的字段，而不是请求。提示词字段 →
• 不支持视觉。 内容可以是字符串，也可以是分块数组，但只有 text 块会被读取；图片块会被忽略。
• 只有最后一条 user 消息会被加进对话。更早的用户消息会被忽略。
• 助手消息只用于同步历史（见下文）。
• 最后一条用户消息如果为空或只有空白，会返回 missing_user_message。

响应

非流式响应是一个普通的 chat.completion 对象。finish_reason 永远是 stop——内部的工具调用从不暴露出来——而且 usage 计数全是零，所以请从 API 密钥页面上的用量统计来衡量 token，而不是看响应。

流式响应是 text/event-stream：

1. 内容块：带 delta.content 的 chat.completion.chunk 对象。不会发送开头那个 delta: {"role": "assistant"} 块。
2. 一个结束块，finish_reason 是 stop、length 或 content_filter。因工具调用而结束的情况会报成 stop。
3. 一个 choices 为空数组的用量块。
4. data: [DONE].

如果生成过程中出错，流会先发出 data: {"error": {...}}，然后是 [DONE]。

对话状态

对话由 Reverie 保存。每一对「密钥 + 角色」对应一个聊天，它会和你其他的聊天一起出现在网页应用里；每一轮都由角色的系统提示词和情景、世界书设定、长期记忆、滚动摘要、角色的叙述风格、回复长度和 NSFW 设置、来自你账号语言的语言锁定，以及模型上下文窗口容得下的那部分近期历史拼成。当模型支持工具时，记忆工具会运行。

既然历史由服务端保管，你就不需要把它重放一遍。

由哪个大模型作答

由角色决定，而不是由请求决定——除非你在请求里点名某个大模型。优先级从低到高：默认聊天模型，然后是角色自己的模型设置，然后是作为 model 传进来的 Reverie 模型 ID，最后是你在网页应用里为这个聊天单独设定的模型偏好，它压过前面所有。模型 →

错误

/chat/completions 的错误使用 OpenAI 的外壳： {"error": {"message", "type", "param": null, "code"}}.

有两类情况不走这个外壳：GET /models 的错误，以及被校验拒掉的请求体（比如超出范围的 temperature）——这两种都返回朴素的错误结构。

速率限制与配额

这个 API 没有按密钥的速率限制、没有并发上限，也没有请求配额。约束你的只有两样东西：

免费模型的时段配额和网页聊天、故事、小说以及机器人共用——它是每个账号一份，而不是每个入口各一份。免费模型 →

Reverie 不会向外发送 webhook；没有什么可以订阅来接收生成完成的事件。

导入角色

还有第二个接口 POST /api/v1/characters/import，用角色卡创建一个角色。它需要带导入权限的密钥，而那不是设置页面能创建的那种密钥。API 密钥 → 以及 导入角色 →

相关

• API 密钥 — 创建、绑定、设过期和查看密钥用量
• 模型 — 模型 ID 和积分倍率
• 限制 — 产品里其他的上限
• 积分 — 请求是怎么计价的