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

用戶端使用 ticket 建立實際 Travel，並獲取 RTC 入會設定、Acting 能力版本和播放器畫面比例。呼叫成功即建立 Travel。

適用範圍

用戶端使用 ticket 建立實際 Travel，並獲取 RTC 入會設定、Acting 能力版本和播放器畫面比例。呼叫前請確認以下事項：

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

HTTP 呼叫

新加坡

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

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

美国（維吉尼亞）

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/enter-travel

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

請求參數	用戶端進入房間 `curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/enter-travel' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "ticket": "{ticket}" }'`
Content-Type`string`（必選）請求內容類型。此參數必須設定為 `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`。

說明Acting 進房不消耗 maxExperienceTimeSec，請勿傳入。若仍傳入非法檔位，會在模型分流前返回 400000。

回應參數

進房成功

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 3,
        "creationModel": "simple",
        "playUrl": null,
        "firstFrame": "https://cdn.happyoyster.com/frames/acting_world_xyz789.jpg",
        "rtcConfig": {
            "channelId": "stream_abc123",
            "appId": "18bca2e3218c46aebf8ff3a32fb12311",
            "token": "007eJxTYOh...",
            "userId": "user_1"
        },
        "version": "actingV2",
        "aspectRatio": "9:16",
        "noStreamAutoEndTimeoutSec": 30,
        "maxExperienceTimeSec": null
    }
}

code integer

返回碼。0 表示成功，非 0 為錯誤碼。

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedTravelId string

新建立的加密 Travel ID。後續查詢 Travel 狀態、暫停、恢復、結束、產物查詢均使用此值。

encryptedWorldId string

當前 Travel 對應的加密 World ID。

mode integer

Acting 恆為 3。

creationModel string

Acting 恆為 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

Acting 進房版本，固定為 actingV2。須按此版本呼叫控制介面。

aspectRatio string

畫面比例。用戶端須在拉流前據此設定播放器方向：

9:16（直式）
16:9（橫式）

noStreamAutoEndTimeoutSec integer

無推流自動結束逾時秒數，預設為 30，以實際回應為準。進房後若在此時間內 rtcStatus 未進入推流狀態，應呼叫結束 Travel並傳入 failCode=TRAVEL_NO_STREAM_AUTO_END。

maxExperienceTimeSec null

Acting 不使用最大體驗時長，固定返回 null。

前置狀態與呼叫注意事項

ticket 對應的 World 必須為 ready，且 ticket 未過期、未使用。
呼叫成功即建立 Travel；同一 ticket 再次使用將返回 401011。
Acting 功能或規格未開通時返回 403007，且不會建立 Travel。
version 必須按 actingV2 處理；請勿按其他能力版本呼叫控制介面。
用戶端應在建立拉流或渲染容器前讀取 aspectRatio：9:16 使用直式容器，16:9 使用橫式容器。
請勿傳送 maxExperienceTimeSec。Acting 不會按該欄位自動結束，用戶端不能據此進行倒數計時。
rtcConfig=null 表示當前沒有可用推流頻道，用戶端不能據此開始播放。

錯誤碼

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

下一步

進房成功後：

查詢 Travel 狀態：每 2–5 秒輪詢，當 Travel 為 running 或 paused 時可傳送指令。
傳送文字過程指令：驅動後續角色表演。
暫停 Travel / 恢復 Travel：按需控制執行節奏。
結束 Travel：結束時進入 completed，開始處理產物。

適用範圍

HTTP 呼叫

新加坡

美国（維吉尼亞）

請求參數

用戶端進入房間

請求主體（Request Body）

回應參數

進房成功

前置狀態與呼叫注意事項

錯誤碼

下一步