HappyOyster 是实时交互的开放式世界模型。输入一段自然语言 Prompt 和一张首帧图，即可生成一个可实时演绎、探索、互动的数字世界，输出为可进房的实时视频流。适用于互动剧、影视预演、AI 陪伴、可玩世界等场景。
简介
HappyOyster 提供世界探索（Adventure）模式：
| 模式 | 输入 | 交互方式 |
|---|---|---|
| 世界探索（Adventure） | Prompt + 首帧图（横屏） | 方向 / 视角 / 动作指令 |
整体架构
HappyOyster 采用服务端 + 客户端分离的集成方式：
- 您的服务端通过 HappyOyster Open API（使用主 API Key，标准 HTTPS REST）管理世界的全生命周期，包括创建 / 管理世界、换取凭证、查询历史与产物。
- 您的客户端通过 HappyOyster SDK（使用临时 API Key + ticket，走 RTC 实时音视频通道）进行实时体验，覆盖 Android、iOS、Web 三端。SDK 封装了 RTC 建连、视频播放、状态轮询与交互指令，无需直接对接底层实时通信协议。
Open API 与 SDK
分工概览
| 维度 | 服务端 HappyOyster Open API | 客户端 HappyOyster SDK |
|---|---|---|
| 调用方 | 您的后端服务 | 您的 App 或 Web 前端 |
| 鉴权凭证 | 主 API Key（长期有效，仅服务端持有） | 临时 API Key（token）+ 一次性 ticket（短时效） |
| 核心职责 | 世界管理（创建、状态轮询、查询、删除）、凭证换取、Travel 控制、产物查询 | RTC 建连与视频渲染、实时互动指令、状态回调 |
| 通信方式 | 标准 HTTPS REST 请求 | RTC 实时音视频通道（SDK 内部封装） |
| 适用平台 | 任意后端语言（Python、Java、Node.js 等） | Android、iOS、Web |
能力矩阵
| 能力 | Open API（服务端） | SDK（客户端） |
|---|---|---|
| 创建 / 管理 World | 支持 | 不支持 |
| 轮询世界构建状态 | 支持 | 不支持 |
| 换取 ticket | 支持 | 不支持（消费 ticket） |
| 注入 HTTP 鉴权 token | 不支持 | 支持（updateToken） |
| 进房 + RTC 建连 | 支持（SDK 内部调用） | 支持（Travel 启动，SDK 内部封装） |
| 实时视频播放 | 不支持 | 支持（挂载 SDK 提供的视频视图） |
| 状态轮询 | 支持（SDK 内部调用） | 支持（状态回调透出） |
| 世界探索操控指令 | 不支持 | 支持（sendCommand） |
| 结束体验 | 支持 | 支持（Travel 结束，SDK 内部封装） |
| 查询历史 Travel | 支持 | 不支持 |
| 获取视频产物 | 支持 | 不支持 |
SDK 不负责世界的创建与管理，仅负责客户端实时体验（推流、播放、交互指令、状态回调）。
适用场景
| 场景 | 服务端关键 API | 客户端关键 SDK 能力 |
|---|---|---|
| 互动游戏 / 可玩世界 | 创建世界 → 凭证换取 | sendCommand + 状态回调 |
| AI 陪伴 / 虚拟导游 | 首帧图 + prompt 创建 | 实时体验 + 视频 View |
| 教育模拟 | 首帧图 + prompt 搭建场景 | 快速进房体验 |
使用限制
- 画幅规则：世界探索必须上传首帧图，视频画幅按首帧图比例（横屏，宽高比 1.5–2.0）。
- 跨模型访问：World 与 Travel 严格属于其创建模型，跨模型访问会返回
403001（world）或404000（travel）。
术语速查
- World（世界）：一个完整的数字世界定义，包含角色、场景和剧本。World 可预制、可复用，是所有体验的基础。
- Travel（体验）：基于某个 World 发起的一次实时体验会话，通常经历「初始化 → 准备 → 运行 → 结束」几个阶段，各端具体状态取值请以对应 SDK API 参考为准。
- ticket：一次性进房凭证，由服务端换取后下发给客户端。
- token（临时 API Key）：客户端 SDK 的 HTTP 层鉴权凭证，由服务端签发后注入 SDK，需定期续期。
模型用量查询
当前控制台"模型用量"模块暂不支持世界模型的用量统计，请通过账单查询与费用管理查看。
下一步
- 快速开始：完成端到端接入流程。