HappyOyster-Directing-結束Travel API參考 - Alibaba Cloud Model Studio

結束 Directing Travel。正常結束時狀態變為 completed 並進入產物處理；無推流超時結束時變為 failed，且不生成回放產物。

適用範圍

結束 Directing Travel。正常結束時狀態變為 completed 並進入產物處理；無推流超時結束時變為 failed，且不生成回放產物。呼叫前請確認以下事項：

驗證要求：不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。獲取方式請參閱獲取驗證憑證。
前置條件：Travel 必須尚未進入終態，並處於伺服器端可結束的狀態。可透過查詢 Travel 狀態介面确认。
呼叫方：您的伺服器端或用戶端均可呼叫。

HTTP 呼叫

新加坡

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

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

美国（維吉尼亞）

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

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

請求參數

正常結束

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/end' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedTravelId": "{encryptedTravelId}",
    "userAgent": "your-client/1.2.0"
}'

無推流逾時結束

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/end' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedTravelId": "{encryptedTravelId}",
    "failCode": "TRAVEL_NO_STREAM_AUTO_END",
    "userAgent": "your-client/1.2.0"
}'

Content-Typestring（必選）

請求內容類型。此參數必須設定為 application/json。

Authorization string （必選）

API Key 驗證。不強制使用主 API Key，主 API Key 或臨時 API Key 均可呼叫。

主 API Key：以 sk- 開頭，如 sk-xxx。
臨時 API Key：以 st- 開頭，如 st-xxx。

請求主體（Request Body）

encryptedTravelId string （必選）

要結束的 Directing 加密 Travel ID。由用戶端進入房間介面返回。

failCode string （可選）

失敗結束原因。省略時按正常結束處理。目前僅支援：

TRAVEL_NO_STREAM_AUTO_END：用於進入房間後超過 noStreamAutoEndTimeoutSec 仍未收到推流的場景，此結束方式不會產生回放產物

若傳入未支援的值，將返回返回 400000。

userAgent string （可選）

SDK 或用戶端版本識別碼。非空字串，優先於 HTTP User-Agent。

回應參數

正常結束

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "completed",
        "endedAt": "2026-06-04T00:03:00Z",
        "durationSec": 180
    }
}

無推流逾時結束

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "failed",
        "errorCode": "TRAVEL_NO_STREAM_AUTO_END",
        "errorMessage": "Something went wrong.",
        "endedAt": "2026-06-04T00:03:00Z",
        "durationSec": null
    }
}

code integer

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

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedTravelId string

已結束的加密 Travel ID。

status string

結束狀態：completed（正常結束）/ failed（帶受支援 failCode 時的失敗結束）。

errorCode string

失敗原因代碼；正常結束時為 null。

errorMessage string

失敗說明；正常結束時為 null。

endedAt string

結束時間，ISO 8601 格式。

durationSec integer

有效視訊時長秒數；無推流失敗結束或時長尚無法解析時為 null。

前置狀態與呼叫注意事項

用戶端應在進房後輪詢查詢Travel狀態。如果在 noStreamAutoEndTimeoutSec 內 rtcStatus 未進入推流態，使用 TRAVEL_NO_STREAM_AUTO_END 結束。
傳入 TRAVEL_NO_STREAM_AUTO_END 後 Travel 為 failed，不能查詢到回放產物。
正常結束後，durationSec 優先使用最終視訊檔案時長；最終視訊尚不可用時，使用目前最新可用生成結果的 durationMs。兩者均不可用時為 null。
正常結束進入 completed 後，產物合成仍可能進行中；按查詢Travel產物的返回狀態決定是否繼續輪詢。

錯誤碼

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

下一步

Travel 進入 completed 後：

查詢 Travel 產物：輪詢獲取錄製原片與合成變體。
查詢 Travel 清單：檢視歷史 Travel。