Skip to content

API.md

Latest commit

 

History

History
332 lines (244 loc) · 9.01 KB

API.md

File metadata and controls

332 lines (244 loc) · 9.01 KB
Raw

Hardware Pi API

所有接口默认与手机页面同源。当前 Orange Pi 首次部署使用 HARDWARE_PI_AUTH_MODE=off，在可信局域网内不要求网页令牌。不要把服务直接暴露到公网。

需要令牌鉴权时将 HARDWARE_PI_AUTH_MODE=token，并配置：

  • HARDWARE_PI_ADMIN_TOKEN：修改 Provider 和路由；
  • HARDWARE_PI_DEVICE_TOKEN：手机对话与读取会话；
  • HARDWARE_PI_SERVICE_TOKEN：ReHoYo 工作台和大型项目调用 Gateway。

以下示例中的鉴权 Header 在 off 模式下可以省略。

健康检查

GET /api/v1/health

不需要令牌，只返回 Provider 是否配置、鉴权模式和模块端口，不返回密钥。

控制面板

GET /api/v1/control/settings
X-Admin-Token: <admin-token>
PUT /api/v1/control/settings
X-Admin-Token: <admin-token>
Content-Type: application/json

{
  "providers": {
    "deepseek": {
      "enabled": true,
      "base_url": "https://api.deepseek.com",
      "model": "deepseek-v4-flash",
      "api_key": "..."
    }
  },
  "routing": {
    "workbench_generation": "deepseek",
    "companion_chat": "deepseek"
  }
}

api_key 留空或省略时保留现有密钥。设置 clear_api_key: true 才会清除。

手机对话

POST /api/v1/chat
Authorization: Bearer <device-token>
Content-Type: application/json

{
  "session_id": "phone-01",
  "message": "今天去哪里拍照？",
  "history": []
}

实时事件入口：

WS /api/v1/chat/ws?token=<device-token>

发送与 HTTP 相同的请求对象。服务端依次发送：

  • assistant.start
  • character.expression
  • assistant.final

已完成首次进入且开启个性化时，服务端会把玩家称呼加入角色上下文；只有同时满足“长期记忆已开启”“玩家已确认”“允许角色引用”的记忆才会加入模型上下文。暂停同行会立即停止个性化和记忆引用。

CosyVoice 语音

CosyVoice 使用三项独立配置：

  • 模型 ID：cosyvoice-v3.5-flash
  • 复刻音色 ID：cosyvoice-v3.5-flash-marchpet-eb86bcaeea5f40669b1798191950529a
  • DashScope API Key：保存在 Pi 控制面板，不会返回手机

该复刻音色 ID 是项目作者上传声音后制作并从正式版恢复的固定配置，服务端直接读取 shared/cosyvoice-config.json；不要把它替换成模型 ID。

读取不含密钥的手机语音设置：

GET /api/v1/tts/settings
Authorization: Bearer <device-token>

生成完整 WAV：

POST /api/v1/tts/synthesize
Authorization: Bearer <device-token>
Content-Type: application/json

{"text": "今天也一起拍照吧！", "mood": "bright"}

实时播放入口使用同一请求体：

POST /api/v1/tts/stream
Authorization: Bearer <device-token>
Content-Type: application/json

响应是 text/event-stream，依次包含 started、若干 audio 和 complete 事件；audio.data.audioBase64 是 16-bit little-endian 单声道 PCM，采样率见 sampleRate。失败时返回 error 事件。手机网页已内置 Web Audio 顺序播放、停止和取消旧请求。

管理端试听：

POST /api/v1/tts/test
X-Admin-Token: <admin-token>

语音必须同时满足：CosyVoice Provider 已启用且配置 Key、玩家已确认声音使用授权、语音输出已开启。测试接口允许输出开关关闭，但仍要求声音授权和有效 Key。撤销授权会自动关闭语音与自动朗读。

陪伴快照与首次进入

以下接口都使用设备令牌：

GET /api/v1/companion/snapshot
Authorization: Bearer <device-token>

返回同行资料、记忆、已审核通信和数量统计。新设备的 profile.onboarding_completed 为 false。

POST /api/v1/companion/onboarding
Authorization: Bearer <device-token>
Content-Type: application/json

{
  "display_name": "开拓者",
  "region": "china",
  "language": "zh-CN",
  "time_zone": "Asia/Shanghai",
  "allowed_content_types": ["daily", "photo", "postcard", "relationship"],
  "proactive_contact_enabled": false,
  "recall_enabled": false,
  "personalization_enabled": true,
  "memory_enabled": true,
  "quiet_hours": {"start": "22:00", "end": "09:00"},
  "weekly_contact_limit": 2,
  "accepted_concept": true,
  "accepted_data_flow": true,
  "first_join_choice": "take_photos",
  "consent_version": "hardware-pi-v1"
}

first_join_choice 可选值：

  • take_photos
  • explore_places
  • hear_stories
  • walk_slowly

完成后会创建一封欢迎通信；开启长期记忆并选择第一次同行时，还会创建一条玩家确认的共同记忆。重复提交不会重复创建这两条记录。

同行设置

PUT /api/v1/companion/profile
Authorization: Bearer <device-token>
Content-Type: application/json

{
  "display_name": "开拓者",
  "memory_enabled": true,
  "personalization_enabled": true,
  "proactive_contact_enabled": false,
  "quiet_hours": {"start": "22:00", "end": "09:00"},
  "weekly_contact_limit": 2,
  "paused": false
}

所有字段都可选。关闭长期记忆不会删除现有记录，只会停止模型引用；paused: true 会停止全部个性化上下文。

长期记忆与相册

创建玩家明确确认的共同记忆：

POST /api/v1/memories
Authorization: Bearer <device-token>
Content-Type: application/json

{
  "type": "photo",
  "title": "Pi 上的第一天",
  "summary": "第一次通过手机看到三月七。",
  "reusable_by_character": true,
  "user_confirmed": true
}

修改或关闭引用：

PATCH /api/v1/memories/<memory-id>
Authorization: Bearer <device-token>
Content-Type: application/json

{"reusable_by_character": false}

删除：

DELETE /api/v1/memories/<memory-id>
Authorization: Bearer <device-token>

角色通信

首次进入流程会创建一封已审核欢迎通信。ReHoYo 工作台发行消息通过共享目录自动进入 Pi；手机不能自行创建通信。Pi 会先执行交付校验、主动联系策略和发送前评审，合法且允许触达的消息才会显示。

PATCH /api/v1/communications/<message-id>
Authorization: Bearer <device-token>
Content-Type: application/json

{
  "read": true,
  "favorite": true,
  "liked": true,
  "remind_later": false
}

通信中心只返回 review_status=approved 且已经发送的消息。

管理端可以查看或立即检查发行队列：

GET /api/v1/release/status
X-Admin-Token: <admin-token>
POST /api/v1/release/scan
X-Admin-Token: <admin-token>

大型项目也可以绕过共享目录，通过服务令牌推送与工作台相同的不可变交付包：

POST /api/v1/release/deliveries
Authorization: Bearer <service-token>
Content-Type: application/json

请求必须包含 schemaVersion=1、deliveryId、region、plan 和以 compact JSON 计算的 SHA-256 checksum。同一 deliveryId 只处理一次；校验失败返回错误，目录入口的错误文件会移到 .data/bridge/quarantine/。

因玩家关闭主动联系、暂停同行、处于勿扰时段或超过频率限制的合法交付会保留为 deferred 并在之后重试，不会静默丢失。安全规则或语义评审明确拒绝的内容标记为 rejected。

导出与删除

GET /api/v1/companion/export
Authorization: Bearer <device-token>

导出资料、记忆和通信，不包含 API Key 和自由聊天记录。

合并正式桌面版 v4 隐私导出或记忆导出：

POST /api/v1/companion/import
Authorization: Bearer <device-token>
Content-Type: application/json

{
  "accepted_data_import": true,
  "payload": {
    "schemaVersion": 4,
    "scope": "rehoyo-companion-local-data",
    "data": {}
  }
}

请求上限 8 MB。导入不会清空 Pi 现有数据；原记录 ID 会转换为稳定的 legacy-v4-* ID，因此可安全重试。同行资料只在正式版已完成首次授权时合并；隐藏自动候选不会导入，未确认的显式候选不会提供给模型；通信必须同时具有 reviewStatus=approved 与 sentAt。

DELETE /api/v1/companion/data
Authorization: Bearer <device-token>

删除同行资料、记忆和通信，并回到首次进入状态。统一 Provider 配置、API Key 和访问令牌不会被删除。

OpenAI 兼容入口

POST /api/openai/v1/chat/completions
Authorization: Bearer <service-token>

请求和响应保持 OpenAI Chat Completions 结构。实际 Base URL、API Key 与模型由控制面板决定。

ReHoYo 可以这样配置：

AI_PROVIDER=deepseek
DEEPSEEK_API_KEY=<HARDWARE_PI_SERVICE_TOKEN>
DEEPSEEK_BASE_URL=http://orange-pi.local:8000/api/openai/v1

此时 ReHoYo 不再持有真实 DeepSeek Key。

工作台内部智谱入口

Hardware Pi 自带工作台使用以下服务令牌接口，手机和外部浏览器不应直接调用：

POST /api/zhipu/v1/web_search
POST /api/zhipu/v1/files/parser/create
GET  /api/zhipu/v1/files/parser/result/<task-id>/text
Authorization: Bearer <service-token>

它们分别承担区域联网研究和云端文件解析，真实智谱 API Key 仍只保存在统一控制面。