全部產品
Search

搜尋本產品

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

    文件中心

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

    更新時間：Sep 23, 2026

    用戶端使用 ticket 建立實際 Travel，並獲取 RTC 入會配置和 Directing 能力版本。creationModel 決定 Travel 可呼叫的控制介面。

    適用範圍

    用戶端使用 ticket 建立實際 Travel，並獲取 RTC 入會配置。呼叫前請確認以下事項：

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

    HTTP 呼叫

    新加坡

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

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

    美国（維吉尼亞）

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

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

    請求參數

    用戶端進入房間

    curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/enter-travel' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "ticket": "{ticket}"
}'

    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。

    說明Directing 進房不消耗

    maxExperienceTimeSec，請勿傳入。該欄位僅 Adventure 生效；若仍傳入非法檔位，會在模型分流前返回 400000。成功回應仍為 null。

    回應參數 

    {
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 2,
        "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": "storyV2",
        "aspectRatio": null,
        "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

    Directing 恆為 2。

    creationModel string

    simple 或 scriptlist；決定 Travel 可呼叫的控制介面：

    • simple：instruct、pause、resume、rewind、end
    • scriptlist：update-script、pause、resume、rewind、end（不支援 instruct）

    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

    Directing 進房版本，固定為 storyV2。

    aspectRatio null

    Directing 模型固定為 null。

    noStreamAutoEndTimeoutSec integer

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

    maxExperienceTimeSec null

    Directing 模型固定為 null。

    前置狀態與呼叫注意事項

    • ticket 對應的 World 必須為 ready，且 ticket 未過期、未使用。
    • 不要傳 maxExperienceTimeSec。Directing 不按該欄位限制體驗時長。
    • 呼叫成功即建立 Travel；同一 ticket 再次使用返回 401011。
    • creationModel=scriptlist 時不要呼叫 instruct，應使用劇本全量更新。
    • rtcConfig=null 表示當前沒有可用推流頻道，用戶端不能據此開始播放。

    錯誤碼

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

    下一步

    進房成功後：