接入流程

HappyOyster 采用服务端 + 客户端分离的接入方式：服务端通过 Open API 管理世界与产物，客户端 SDK 完成实时体验。开始前请先完成获取鉴权凭证。

​

一、准备世界（服务端 Open API）

1. 创建世界：定义一个可复用的 World。HappyOyster-Adventure-创建世界，perspective、prompt、firstFrameImage 必填。
2. 轮询构建状态（建议 3~5 秒间隔），直到状态为 ready：HappyOyster-Adventure-查询世界构建状态。
3. 下发凭证给客户端：按获取鉴权凭证所述，获取临时 API Key与ticket，一并下发给客户端。

​

二、实时体验（客户端 SDK）

客户端 SDK 使用服务端下发的临时 API Key 和 ticket 完成实时体验。SDK 封装了 RTC 建连、视频播放、状态轮询与交互指令，无需直接对接底层实时通信协议。Travel（体验会话）通常经历「初始化 → 准备 → 运行 → 结束」几个阶段，各端具体状态取值请以对应 SDK API 参考为准。 以下步骤描述通用动作。Web / Android / iOS 三端 API 名略有差异，具体方法签名与调用时序请查阅对应 SDK 参考。

1. 初始化 SDK：注入 API Host 与 model（happyoyster-1.0-adventure），再通过 updateToken 注入临时 API Key。
2. 启动会话：用 ticket 启动 Travel，SDK 自动进房并建立 RTC 实时连接。可选设 maxExperienceTimeSec（60 / 90 / 120 秒，默认 60）。
3. 挂载视频：获取 SDK 提供的视频视图并加入页面布局。
4. 实时互动：通过 sendCommand 发送方向 / 视角 / 动作控制指令与世界交互。
5. 结束体验：结束 Travel，SDK 自动断开 RTC 并释放资源；通过状态与错误事件监听感知会话终态。

​

三、获取产物（服务端 Open API）

体验结束后，服务端调用 HappyOyster Open API 获取合成视频。

1. 查询产物：使用主 API Key 轮询，直至 composeStatus 为 ready：HappyOyster-Adventure-查询Travel产物。
2. 获取视频：建议对外交付 video.withInstructionAndWatermark（指令 + 水印合成版）。

​

下一步

• 下载 SDK 与 Demo：各端 SDK 包、接入指南、API 参考与开源 Demo。