HappyOyster-Adventure-用戶端進入房間 API參考 - Alibaba Cloud Model Studio

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

適用範圍

用戶端使用 ticket 建立實際 Travel，並取得 RTC 入會設定。maxExperienceTimeSec 僅在 Adventure 模型中生效。呼叫前請確認以下事項：

驗證要求：不強制主 API Key，使用 ticket 完成進房驗證。獲取方式請參閱獲取驗證憑證。
前置條件：ticket 由獲取體驗憑證介面換取，未過期且未使用，對應 World 狀態為 ready。
呼叫方：由您的用戶端呼叫。

HTTP 呼叫

新加坡

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travel

呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

华北2（北京）

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travel

呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

美国（維吉尼亞）

POST https://{WorkspaceId}.us-east-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 integer

Adventure 恆為 1。

creationModel string

Adventure 恆為 simple。

playUrl null

暫不可用，固定為 null。

firstFrame string

World 首幀 URL。

rtcConfig object

RTC 入會設定；沒有可用推流頻道時為 null，用戶端不能據此開始播放。

channelId：RTC 頻道 ID
appId：平台分配的 RTC 應用程式 ID
token：RTC 入會 Token
userId：RTC 入會使用者 ID，固定為 user_1

version string

Adventure 進房版本，固定為 wanderV2。須按此版本透過 SDK sendCommand 傳送控制資料。

aspectRatio null

Adventure 固定為 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：結束工作階段並處理產物。