全部產品
Search

搜尋本產品

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

    文件中心

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

    更新時間：Sep 23, 2026

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

    美国（維吉尼亞）

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

    Travel 生命週期狀態：

    • 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 array

    Directing 模型固定為空陣列。

    environmentActions array

    Directing 模型固定為空陣列。

    前置狀態與呼叫注意事項

    • 建議每 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 時：