Skip to main content

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

查詢 Acting Travel 生命週期、伺服器端推流狀態、已傳送文字指令和章節資訊，也可同時上報用戶端拉流或播放心跳。

適用範圍

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

請求參數

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

回應參數

  • Travel 執行中
  • Travel 失敗
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "rtcStatus": "PUSHING",
        "updateTime": "2026-09-09T08:30: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/acting_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 失敗；原因見 errorCode / errorMessage
  • 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 array<string> | nullActing 不支援 SDK 動作控制，返回空陣列；failed 時為 null。environmentActions array<string> | nullActing 不支援 SDK 環境動作控制，返回空陣列；failed 時為 null。errorCode string僅 status=failed 時返回；結構化失敗原因代碼，取值見錯誤碼。errorMessage string與 errorCode 同時返回；英文失敗說明。請按 errorCode 分支處理，請勿匹配 errorMessage 文案。

前置狀態與呼叫注意事項

  • 建議每 2–5 秒輪詢。
  • running 和 paused 都允許呼叫傳送文字過程指令；在 paused 狀態傳送指令不會自動恢復 Travel。
  • 本介面不返回 mode、aspectRatio、playUrl、bgmUrl 或 sessionId；播流設定與播放器方向以進入房間回應為準。
  • clientStreamStatus 是客戶端播放側心跳，rtcStatus 是伺服器端推流側狀態，兩者不可互相替代。
  • Acting 不支援 SDK sendCommand，請勿根據兩個空動作陣列建構方向或動作控制。
  • failed 是終態，不會再產生成片；請按 errorCode 顯示失敗原因，請勿顯示為「尚未完成」。

錯誤碼

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

下一步

Travel 為 running 或 paused 時：
HappyOyster-Acting-查詢 Travel 狀態 API 參考 - Alibaba Cloud Model Studio