HappyOyster 是即時互動的開放式世界模型。輸入一段自然語言 Prompt 和一張首幀圖，即可生成一個可即時演繹、探索、互動的數位世界，輸出為可進房的即時視訊流。適用於互動劇、影視預演、AI 陪伴、可玩世界等場景。
模型效果展示和提示詞編寫請參閱HappyOyster 使用指南。
HappyOyster 簡介
HappyOyster 提供三種體驗模式，各自獨立部署，涵蓋不同業務場景：
| 模式 | 輸入 | 互動方式 |
|---|---|---|
| 世界探索（Adventure） | Prompt + 首影格圖（橫螢幕） | 方向 / 視角 / 動作指令（sendCommand） |
| 即時導演（Directing） | Prompt 或結構化劇本 + 首影格圖（橫螢幕），可選參考圖（用於劇本產生與角色參考） | 文字指令（sendInstruct）/ 劇本清單；支援暫停、回溯、恢復 |
| 角色演繹（Acting） | Prompt + 首影格圖（預設直螢幕 9:16，也支援 16:9） | 文字指令（sendInstruct）；支援暫停、恢復；不支援回溯 |
整體架構
HappyOyster 採用伺服器端 + 用戶端分離的整合方式：
- 您的伺服器端透過 HappyOyster Open API（使用主 API Key，標準 HTTPS REST）管理世界的完整生命週期，包括建立 / 管理世界、換取憑證、查詢歷史與產物。Open API 按體驗模式拆分為 Adventure / Directing / Acting 三套獨立介面。
- 您的用戶端透過 HappyOyster SDK（使用臨時 API Key + ticket，走 RTC 即時音視訊通道）進行即時體驗，涵蓋 Android、iOS、Web 三端。SDK 封裝了 RTC 建連、影片播放、狀態輪詢與互動指令，無需直接對接底層即時通訊協定。
流程中的參與方是終端使用者、您的用戶端 App/Web、您的伺服器端、HappyOyster Open API 和 HappyOyster SDK。請依下列順序整合：
- 伺服器端建立世界並取得憑證。 您的伺服器端使用主 API Key，向 HappyOyster Open API 發送
POST /worlds建立世界，接著以GET /worlds/build-status輪詢建置狀態，並以POST /worlds/get-travel-credential換取體驗憑證。伺服器端將token和ticket下發給用戶端。 - 用戶端啟動即時體驗。 用戶端使用 SDK、臨時 API Key 和
ticket，先呼叫initialize和updateToken，再呼叫startTravel(ticket)。SDK 隨後透過 Open API 進入體驗並建立 RTC 連線，向用戶端返回影片 View 和狀態回呼。 - 用戶端互動。 用戶端透過 SDK 發出
sendInstruct、sendCommand、pause或end；SDK 對 Open API 呼叫對應的控制介面。 - 體驗結束後取得產物。 您的伺服器端向 Open API 發送
GET /travels/artifacts取得產物。
所有介面透過阿里雲百煉平台閘道驗證，憑證體系及取得方式詳見取得驗證憑證。
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 提供的視訊視圖；Acting 按回包 aspectRatio 定直式 / 橫式螢幕） |
| 狀態輪詢 | 支援（SDK 內部呼叫） | 支援（狀態回調透出） |
| 即時導演 / 角色演繹文字指令 | 支援（instruct） | 支援（sendInstruct） |
| 世界探索操控指令 | 不支援 | 支援（sendCommand；Acting 不可用） |
| 暫停 / 恢復 | 支援 | 支援（Directing 與 Acting；Adventure 呼叫被 SDK 以 103003 拒絕） |
| 回溯 | 支援（rewind；僅 Directing） | 支援（僅 Directing；其他模式以 103003 拒絕） |
| 結束體驗 | 支援 | 支援（Travel 結束，SDK 內部封裝） |
| 更新劇本（ScriptList） | 支援（update-script；僅 Directing scriptlist。Acting 與 Directing simple 呼叫返回 409000） | 不支援 |
| 查詢歷史 Travel | 支援 | 不支援 |
| 獲取視訊產物 | 支援 | 不支援 |
說明SDK 不負責世界的建立與管理；即時導演的劇本（Script List）模式僅在伺服器端接入，SDK 僅參與推流、播放與文字指令輸入。
適用場景
| 場景 | 推薦模式 | 伺服器端關鍵 API | 用戶端關鍵 SDK 能力 |
|---|---|---|---|
| 互動遊戲 / 可玩世界 | 世界探索（Adventure） | 建立世界 → 憑證換取 | sendCommand + 狀態回調 |
| AI 陪伴 / 虛擬導遊 | 世界探索（Adventure） | 首幀圖 + prompt 建立 | 即時體驗 + 視訊 View |
| 互動短劇 / 影視預演 | 即時導演(Directing) | simple prompt 或 scriptlist 結構化劇本 | sendInstruct + 暫停 / 回溯 |
| 視訊通話 / 直式螢幕陪伴 | 角色演繹(Acting) | 必填 prompt + firstFrameImage，可選 aspectRatio | sendInstruct + 暫停 / 恢復（不含回溯） |
| 內容平台 / 二創 | 即時導演(Directing) | 結束後 artifacts 匯出 | 體驗 + 伺服器端取產物 |
| 教育模擬 | 世界探索(Adventure) | 首幀圖 + prompt 搭建場景 | 快速進房體驗 |
使用限制
- 畫幅規則：
- 世界探索（Adventure）：必須上傳首影格圖，影片畫幅按首影格圖比例。
- 即時導演（Directing）：
simple子模式可選上傳首影格圖，scriptlist子模式必填首影格圖；上傳首影格圖時須為橫螢幕（寬高比 1.5–2.0），畫幅按首影格圖；建立時傳入的aspectRatio會被忽略。 - 角色演繹（Acting）：必須上傳首影格圖；畫幅由建立時的
aspectRatio控制，預設9:16（直螢幕），可顯式傳16:9。進房 / 世界詳情會回顯該欄位，用戶端應據此設定播放器方向。首影格寬高比須與目標畫幅相符，否則返回400000。
- 跨模型存取：World 與 Travel 嚴格屬於其建立模型，跨模型存取會返回
403001（world）或404000（travel）。 - 模式差異：角色演繹（Acting）不支援回溯（
rewind）與sendCommand；世界探索（Adventure）呼叫暫停 / 恢復會傳回103003。
術語速查
- World（世界）：一個完整的數位世界定義，包含角色、場景和劇本。World 可預製、可複用，是所有體驗的基礎。
- Travel（體驗）：基於某個 World 發起的一次即時體驗會話，通常經歷「初始化 → 準備 → 執行 →（可暫停 / 回溯）→ 結束」幾個階段，各端具體狀態取值請以對應 SDK API 參考為準。
- ticket：一次性進房憑證，由伺服器端換取後下發給用戶端。
- token（臨時 API Key）：用戶端 SDK 的 HTTP 層驗證憑證，由伺服器端簽發後注入 SDK，需定期續期。
模型用量查詢
目前主控台「模型用量」模組暫不支援世界模型的用量統計，請透過帳單檢視。
下一步
-
快速開始：完成端到端接入流程。