Skip to main content

HappyOyster-Adventure-查詢 Travel 狀態 API 參考

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

適用範圍

查詢 Adventure Travel 生命週期、伺服器端推流狀態與目前世界的動作池，也可同時上報用戶端拉流或播放心跳。呼叫前請確認下列事項：
  • 驗證要求：不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。獲取方式請參閱獲取驗證憑證。
  • 前置條件：使用客戶端進入房間介面返回的 encryptedTravelId 查詢。
  • 呼叫方：您的伺服器端或客戶端均可呼叫。建議每 2–5 秒輪詢。

HTTP 呼叫

  • 新加坡
  • 华北2（北京）
  • 美国（維吉尼亞）
GET https://{WorkspaceId}.ap-southeast-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 stringTravel 生命週期狀態：
  • init：正在初始化工作階段資源
  • pending：排隊或等待服務資源
  • running：正在執行，可透過 SDK sendCommand 即時操控
  • failed：Travel 失敗
  • completed：Travel 已結束，可查詢產物
Adventure 產品功能沒有 paused 狀態，請勿圍繞暫停 / 恢復建構狀態機。rtcStatus string伺服器端 RTC 推流狀態；與客戶端上報的 clientStreamStatus 不同。updateTime string最近更新時間，ISO 8601 格式。userInstructions null | arrayAdventure 不支援 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：結束工作階段並處理產物。