HappyOyster-Adventure-查詢 Travel 狀態 API 參考 - Alibaba Cloud Model Studio

查詢 Adventure Travel 生命週期、伺服器端推流狀態與目前世界的動作池，也可同時上報用戶端拉流或播放心跳。

適用範圍

查詢 Adventure Travel 生命週期、伺服器端推流狀態與目前世界的動作池，也可同時上報用戶端拉流或播放心跳。呼叫前請確認下列事項：

驗證要求：不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。獲取方式請參閱獲取驗證憑證。
前置條件：使用客戶端進入房間介面返回的 encryptedTravelId 查詢。
呼叫方：您的伺服器端或客戶端均可呼叫。建議每 2–5 秒輪詢。

HTTP 呼叫

新加坡

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

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

华北2（北京）

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

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

美国（維吉尼亞）

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/status

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

請求參數

查詢 Travel 狀態

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/status?encryptedTravelId={encryptedTravelId}&clientStreamStatus=PLAYING&clientStreamStatusTimeMs=1788940800000' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Authorization string （必選）

API Key 驗證。不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。

主 API Key：以 sk- 開頭，如 sk-xxx。
臨時 API Key：以 st- 開頭，如 st-xxx。

Query 參數

encryptedTravelId string （必選）

Adventure 加密 Travel ID。由用戶端進入房間介面返回。

clientStreamStatus string （可選）

客戶端 RTC 拉流或播放狀態，大小寫不敏感。無法識別的值會被忽略。可選值：

DISCONNECTED：未連線或已離開頻道
CONNECTING：正在連線 RTC 頻道
CONNECTED：已加入會議，尚未開始播放或首幀未到達
PLAYING：已收到遠端串流並正在渲染
BUFFERING：緩衝中
PAUSED：用戶端暫停播放，不代表 Adventure Travel 支援伺服器端暫停
RECONNECTING：重新連線中

clientStreamStatusTimeMs long （可選）

客戶端狀態變更的毫秒時間戳記。與 clientStreamStatus 配套使用。

回應參數

Travel 執行中

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "rtcStatus": "PUSHING",
        "updateTime": "2026-06-04T00:02:00Z",
        "userInstructions": null,
        "chapters": null,
        "characterActions": [
            "dash",
            "jump",
            "crouch",
            "attack"
        ],
        "environmentActions": [
            "ride_motorcycle",
            "enter_exit_car"
        ]
    }
}

code integer

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

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedTravelId string

加密 Travel ID。

status string

Travel 生命週期狀態：

init：正在初始化工作階段資源
pending：排隊或等待服務資源
running：正在執行，可透過 SDK sendCommand 即時操控
failed：Travel 失敗
completed：Travel 已結束，可查詢產物

Adventure 產品功能沒有 paused 狀態，請勿圍繞暫停 / 恢復建構狀態機。

rtcStatus string

伺服器端 RTC 推流狀態；與客戶端上報的 clientStreamStatus 不同。

updateTime string

最近更新時間，ISO 8601 格式。

userInstructions null | array

Adventure 不支援 HTTP instruct，探索動作也不會回顯至該欄位；通常為 null 或 []，請忽略。

chapters array

章節清單；未產生章節資料時為 null。

characterActions array

目前角色 / 主體可用動作 ID；無推薦時為 []。通常傳回 2–4 個。常見動作：

dash：前衝
jump：跳躍
crouch：下蹲 / 趴下
attack：攻擊

environmentActions array

目前場景可用環境互動動作 ID；無推薦時為 []。伺服器端依場景從固定動作池中選擇 0–3 個，可返回空陣列。常見動作：

ride_horse：騎馬
ride_bicycle：騎自行車
ride_motorcycle：騎機車
enter_exit_car：上下車
open_close_door：開 / 關門
take_cover：尋找掩體
car_light：開車燈；僅當同時傳回 enter_exit_car 時才可能出現
car_horn：按喇叭；僅當同時傳回 enter_exit_car 時才可能出現

前置狀態與呼叫注意事項

建議每 2–5 秒輪詢。
Adventure 產品功能沒有 paused 狀態，請勿圍繞暫停 / 恢復建構狀態機。
characterActions 與 environmentActions 為可用動作提示；實際操控仍須透過 SDK sendCommand 傳送。
本介面不返回 mode、playUrl、bgmUrl 或 sessionId；播流設定以進入房間回應為準。
clientStreamStatus 是客戶端播放側心跳，rtcStatus 是伺服器端推流側狀態，兩者不可互相替代。
Adventure 不支援 HTTP instruct、pause、resume、rewind、update-script；請勿將以下路徑視為可用的 HTTP 功能進行整合：/travels/instruct、/travels/pause、/travels/resume、/travels/rewind、/travels/update-script。

錯誤碼

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

下一步

Travel 為 running 後：

用戶端透過 SDK sendCommand 傳送方向、視角與動作控制（可先讀取本介面傳回的動作池）。
結束Travel：結束工作階段並處理產物。