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

查詢 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。

美国（維吉尼亞）

GET https://{WorkspaceId}.us-east-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 執行中

{
    "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": []
    }
}

Travel 失敗

errorCode 取值見錯誤碼。

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "failed",
        "rtcStatus": null,
        "updateTime": null,
        "userInstructions": null,
        "chapters": null,
        "characterActions": null,
        "environmentActions": null,
        "errorCode": "TRAVEL_SESSION_INIT_FAILED",
        "errorMessage": "Failed to allocate inference resources."
    }
}

code integer

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

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedTravelId string

加密 Travel ID。

status string

Travel 生命週期狀態：

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> | null

Acting 不支援 SDK 動作控制，返回空陣列；failed 時為 null。

environmentActions array<string> | null

Acting 不支援 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 時：

傳送文字過程指令：驅動後續角色表演。
暫停 Travel / 恢復 Travel。
結束Travel：結束後查詢產物。