Skip to main content

HappyOyster-Directing-查詢Travel產物 API參考

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

適用範圍

查詢已完成 Directing Travel 的錄製原片及三個合成版本。原片可用是返回產物響應的前提；合成版本可以仍在處理中。對外交付推薦使用 withInstructionAndWatermark。呼叫前請確認以下事項：
  • 驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼 403003）。
  • 前置條件：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。

請求參數

  • 查詢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 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 錯誤碼進行解決。

下一步