Skip to main content

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

查詢 Directing Travel 生命週期、服務端推流狀態、已執行文本指令和章節資訊，也可同時上報客戶端拉流或播放心跳。

適用範圍

查詢 Directing 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-directing/openapi/v1/travels/status呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

請求參數

  • 查詢 Travel 狀態
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/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 （必選）Directing 加密 Travel ID。由客戶端進入房間接口返回。
clientStreamStatus string （可選）客戶端 RTC 拉流或播放狀態，大小寫不敏感。無法識別的值會被忽略。可選值：
  • DISCONNECTED：未連線或已離開頻道
  • CONNECTING：正在連線 RTC 頻道
  • CONNECTED：已加入會議，尚未開始播放或首幀未到達
  • PLAYING：已收到遠端串流並正在渲染
  • BUFFERING：緩衝中
  • PAUSED：客戶端暫停播放，不等同於伺服器端 pause
  • RECONNECTING：重新連線中
clientStreamStatusTimeMs long （可選）客戶端狀態變更的毫秒時間戳記。與 clientStreamStatus 配套使用。

回應參數

  • Travel 執行中
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "rtcStatus": "PUSHING",
        "updateTime": "2026-06-04T00:02:00Z",
        "userInstructions": [
            {
                "instruction": "突然出现一只巨大的机器恐龙",
                "relativeStartTimeMs": 12000,
                "relativeEndTimeMs": 16000,
                "startTime": 12.0,
                "endTime": 16.0,
                "status": "executed"
            }
        ],
        "chapters": [
            {
                "chapterId": 1,
                "title": "第一章",
                "brief": "侦探进入赛博朋克城市",
                "actRange": [0, 10],
                "startTime": 4,
                "endTime": 20,
                "chapterImage": "https://cdn.happyoyster.com/chapters/ch1.jpg"
            }
        ],
        "characterActions": [],
        "environmentActions": []
    }
}
code integer返回碼。0 表示成功，非 0 為錯誤碼。
message string錯誤訊息。成功時為 null。
data object回應資料。失敗時為 null。

屬性

encryptedTravelId string加密 Travel ID。status stringTravel 生命週期狀態：
  • init：正在初始化工作階段資源
  • pending：排隊或等待服務資源
  • running：正在運行，可按創建子模式調用支持的控制接口
  • paused：已完成服務端暫停；可恢復或回溯
  • failed：Travel 失敗
  • completed：Travel 已結束，可查詢產物
rtcStatus string伺服器端 RTC 推流狀態；與客戶端上報的 clientStreamStatus 不同。updateTime string最近更新時間，ISO 8601 格式。userInstructions array文本指令列表；無數據時為 null。每項含 instruction、relativeStartTimeMs / relativeEndTimeMs（相對毫秒）、startTime / endTime（時間軸秒數）、status。chapters array章節列表；尚未觸發章節檢測時為 null。每項包含 chapterId、title、brief、actRange、startTime、endTime、chapterImage。characterActions arrayDirecting 模型固定為空陣列。environmentActions arrayDirecting 模型固定為空陣列。

前置狀態與呼叫注意事項

  • 建議每 2–5 秒輪詢。
  • running 狀態可按 creationModel 調用支持的控制接口：普通模式可 instruct、pause、resume、rewind、end；劇本模式可 update-script、pause、resume、rewind、end。
  • 本接口不返回 mode、aspectRatio、playUrl、bgmUrl 或 sessionId；播流配置以進入房間響應為準。
  • clientStreamStatus 是客戶端播放側心跳，rtcStatus 是伺服器端推流側狀態，兩者不可互相替代。

錯誤碼

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

下一步

Travel 為 running 或 paused 時：