Skip to main content

HappyOyster-Adventure-用戶端進入房間 API參考

用戶端使用 ticket 建立實際 Travel，並取得 RTC 入會設定和 Adventure 能力版本。maxExperienceTimeSec 僅在 Adventure 模型中生效。

適用範圍

用戶端使用 ticket 建立實際 Travel，並取得 RTC 入會設定。maxExperienceTimeSec 僅在 Adventure 模型中生效。呼叫前請確認以下事項：
  • 驗證要求：不強制主 API Key，使用 ticket 完成進房驗證。獲取方式請參閱獲取驗證憑證。
  • 前置條件：ticket 由獲取體驗憑證介面換取，未過期且未使用，對應 World 狀態為 ready。
  • 呼叫方：由您的用戶端呼叫。

HTTP 呼叫

  • 新加坡
  • 华北2（北京）
  • 美国（維吉尼亞）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travel呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

請求參數

  • 用戶端進入房間
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travel' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "ticket": "{ticket}",
    "maxExperienceTimeSec": 90
}'
Content-Typestring（必選）請求內容類型。此參數必須設定為 application/json。
Authorization string （必選）API Key 驗證。不強制使用主 API Key，主 API Key 或臨時 API Key 均可呼叫。
  • 主 API Key：以 sk- 開頭，如 sk-xxx。
  • 臨時 API Key：以 st- 開頭，如 st-xxx。
請求主體（Request Body）
ticket string （必選）未過期且未使用的一次性憑證。由獲取體驗憑證介面換取。同一 ticket 再次使用將返回 401011。
maxExperienceTimeSec integer （可選）最大體驗時長，單位秒，必須是 JSON 整數。預設 60。可選值：
  • 60
  • 90
  • 120
不接受字串或其它數值（如 "60" 不是合法值）；非法檔位返回 400000。服務端在達到該時長後自動結束 Travel。

回應參數

  • 進房成功
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 1,
        "creationModel": "simple",
        "playUrl": null,
        "firstFrame": "https://cdn.happyoyster.com/frames/world_xyz789.jpg",
        "rtcConfig": {
            "channelId": "stream_abc123",
            "appId": "18bca2e3218c46aebf8ff3a32fb12311",
            "token": "007eJxTYOh...",
            "userId": "user_1"
        },
        "version": "wanderV2",
        "aspectRatio": null,
        "noStreamAutoEndTimeoutSec": 30,
        "maxExperienceTimeSec": 90
    }
}
code integer返回碼。0 表示成功，非 0 為錯誤碼。
message string錯誤訊息。成功時為 null。
data object回應資料。失敗時為 null。

屬性

encryptedTravelId string新建立的加密 Travel ID。後續查詢Travel狀態、結束、產物查詢均使用此值。encryptedWorldId string當前 Travel 對應的加密 World ID。mode integerAdventure 恆為 1。creationModel stringAdventure 恆為 simple。playUrl null暫不可用，固定為 null。firstFrame stringWorld 首幀 URL。rtcConfig objectRTC 入會設定；沒有可用推流頻道時為 null，用戶端不能據此開始播放。
  • channelId：RTC 頻道 ID
  • appId：平台分配的 RTC 應用程式 ID
  • token：RTC 入會 Token
  • userId：RTC 入會使用者 ID，固定為 user_1
version stringAdventure 進房版本，固定為 wanderV2。須按此版本透過 SDK sendCommand 傳送控制資料。aspectRatio nullAdventure 固定為 null；播放器畫幅不從本欄位讀取，跟隨首幀圖比例。noStreamAutoEndTimeoutSec integer無推流自動結束逾時秒數，預設為 30，以實際回應為準。進房後若在此時間內 rtcStatus 未進入推流狀態，應呼叫結束 Travel並傳入 failCode=TRAVEL_NO_STREAM_AUTO_END。maxExperienceTimeSec integer服務端實際採用的體驗時長，只會是 60 / 90 / 120。達到該時長後服務端自動結束 Travel。

前置狀態與呼叫注意事項

  • ticket 對應的 World 必須為 ready，且 ticket 未過期、未使用。
  • 呼叫成功即建立 Travel；同一 ticket 再次使用將返回 401011。
  • version 必須按 wanderV2 處理，不能按其它模型的互動協定傳送控制資料。
  • 服務端在達到 maxExperienceTimeSec 後結束體驗，用戶端應處理隨後到達的終態。
  • Adventure 的方向、視角和動作控制不是服務端 HTTP Open API，用戶端必須使用對應平台 SDK 的 sendCommand，由 SDK 經 RTC DataChannel 傳送。
  • rtcConfig=null 表示當前沒有可用推流頻道，用戶端不能據此開始播放。

錯誤碼

如果模型呼叫失敗並返回錯誤訊息，請參閱 HappyOyster 錯誤碼進行解決。

下一步

進房成功後：
  • 查詢Travel狀態：每 2–5 秒輪詢，讀取可用動作池。
  • Travel 為 running 後，用戶端透過 SDK sendCommand 傳送方向、視角和動作控制。
  • 結束Travel：結束工作階段並處理產物。