HappyOyster-Directing-查詢Travel產物 API參考 - Alibaba Cloud Model Studio

查詢已完成 Directing Travel 的錄製原片和三個合成變體。原片可用是返回產物響應的前提；對外交付推薦使用 withInstructionAndWatermark。

適用範圍

查詢已完成 Directing Travel 的錄製原片及三個合成版本。原片可用是返回產物響應的前提；合成版本可以仍在處理中。對外交付推薦使用 withInstructionAndWatermark。呼叫前請確認以下事項：

驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼 403003）。
- 取得主 API Key：取得與設定 API Key。
前置條件：Travel 狀態為 completed。原片可用是返回產物響應的前提。可透過查詢Travel狀態介面确认。
呼叫方：您的伺服器端呼叫。

HTTP 呼叫

新加坡

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/artifacts

呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

美国（維吉尼亞）

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/artifacts

呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

請求參數	查詢Travel產物 `curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/artifacts?encryptedTravelId={encryptedTravelId}' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY"`
Authorization `string` （必選） API Key 驗證。僅支援主 API Key，以 `sk-` 開頭，如 `sk-xxx`。通常設定為環境變數 `$DASHSCOPE_API_KEY`。臨時 API Key（`st-` 開頭）呼叫會返回 `403003`。
Query 參數
encryptedTravelId `string` （必選）狀態為 `completed` 的 Directing 加密 Travel ID。由用戶端進入房間介面返回。

回應參數

四路產物全部就緒

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "composeStatus": "ready",
        "video": {
            "original": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_raw.mp4?v=2",
                "status": "ready",
                "resolution": "720p",
                "durationSec": 180
            },
            "withWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_wm.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            },
            "withInstruction": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_overlay.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            },
            "withInstructionAndWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_all.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            }
        }
    }
}

合成仍在處理中

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "composeStatus": "processing",
        "video": {
            "original": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_raw.mp4?v=2",
                "status": "ready",
                "resolution": "720p",
                "durationSec": 180
            },
            "withWatermark": {
                "url": null,
                "status": "processing",
                "resolution": null,
                "durationSec": null
            },
            "withInstruction": {
                "url": null,
                "status": "processing",
                "resolution": null,
                "durationSec": null
            },
            "withInstructionAndWatermark": {
                "url": null,
                "status": "processing",
                "resolution": null,
                "durationSec": null
            }
        }
    }
}

code integer

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

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedTravelId string

加密 Travel ID。

composeStatus string

三個合成變體的聚合狀態：

ready：withWatermark、withInstruction、withInstructionAndWatermark 均為 ready
partial：至少一個合成變體為 ready，但尚未全部就緒
processing：三個合成變體均非 ready

僅聚合三個合成變體，不包含 original。

video object

四類主線視訊產物，欄位結構固定。每項含 url、status、resolution、durationSec。

original：錄製原片，優先選擇 720p
withWatermark：僅新增浮水印的合成版
withInstruction：僅新增用戶指令字幕的合成版
withInstructionAndWatermark：用戶指令字幕與浮水印合成版，推薦用於對外交付

video.*.url string

視訊 URL；status=processing 時為 null。

video.*.status string

單項狀態：

ready：該視訊已就緒，URL 可存取
processing：正在處理；URL 為 null
unavailable：合成失敗或 URL 暫不可用

video.*.resolution string

原片命中 720p 時 video.original.resolution 為 "720p"；其它情況為 null。

video.*.durationSec integer

統一解析取得的影片時長秒數；可解析時所有 ready 變體均填寫此值，processing / unavailable 或時長暫不可解析時可為 null。

前置狀態與呼叫注意事項

Travel 不是 completed、不存在、不歸屬或不是 Directing、原片不可用時，均返回 404000；原片可用是返回產物響應的前提。
需要全部合成版本時，可在 composeStatus != ready 時繼續輪詢。
video.withInstructionAndWatermark 是推薦的對外交付版本。
四個影片變體共用同一時長解析結果，因此同一次回應中已就緒且時長可解析的變體會返回一致的 durationSec。

錯誤碼

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

下一步

查詢Travel列表：檢視其他歷史 Travel。
結束Travel：結束新的 Travel 後再查詢產物。