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

查詢已完成 Acting Travel 的錄製原片和三個合成變體。對外交付建議使用 withInstructionAndWatermark。

適用範圍

查詢已完成 Acting Travel 的錄製原片和三個合成變體。withInstruction 是使用者過程指令的疊加版本；對外交付建議使用 withInstructionAndWatermark。呼叫前請確認以下事項：

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

HTTP 呼叫

新加坡

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

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

美国（維吉尼亞）

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

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

請求參數	查詢Travel產物 `curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/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` 的 Acting 加密 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；processing 或 unavailable 時為 null。

video.*.status string

單項狀態：

ready：已就緒，url 可存取
processing：仍在合成，url=null
unavailable：合成失敗或 URL 暫不可用，url=null

video.*.resolution string

original 命中 720p 時為 "720p"；其它情況可能為 null。

video.*.durationSec integer

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

前置狀態與呼叫注意事項

用戶端可在 composeStatus != ready 時按受控間隔輪詢。
video.withInstruction 是過程指令疊加版，並非無指令原片。
對外交付建議讀取 video.withInstructionAndWatermark；若業務僅需原片，可繼續讀取 video.original.url。
四個影片變體共用同一時長解析結果，因此同一次回應中已就緒且時長可解析的變體會返回一致的 durationSec。
使用 TRAVEL_NO_STREAM_AUTO_END 結束的 Travel 為 failed，不會生成可查詢產物。
收到 404000 時請勿一律顯示為「尚未完成」：請先透過查詢Travel狀態或查詢Travel列表讀取 status 與 errorCode，failed 的 Travel 應顯示失敗原因。

404000 情境

場景	介面行為
Travel 仍在進行中（`init` / `pending` / `running` / `paused`）	返回業務碼 `404000`，`message` 為 `Video is still being generated, please try again once the process is complete`
Travel 已 `failed`	返回業務碼 `404000`，`message` 為 `Experience failed and no video was produced (errorCode=<errorCode>): <errorMessage>`；失敗為終態，不會再有成片
Travel 不存在、不歸屬或不是 Acting	返回業務碼 `404000`
原片 URL 不可用	返回業務碼 `404000`；原片是整個介面的硬性門檻
原片已就緒、合成仍在處理中	HTTP 200；對應合成項目 `status=processing`、`url=null`
合成失敗或 URL 暫不可用	HTTP 200；對應合成項目 `status=unavailable`、`url=null`

錯誤碼

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

下一步

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