HappyOyster-Directing-回溯 Travel API 參考 - Alibaba Cloud Model Studio

將 Travel 回溯到指定視頻時間點，並從實際落點恢復運行。Travel 必須先進入 paused 狀態。

適用範圍

將 Travel 回溯到指定視頻時間點，並從實際落點恢復運行。調用前請確認以下事項：

驗證要求：不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。獲取方式請參閱獲取驗證憑證。
前置條件：Travel 必須先進入 paused 狀態，不能在 running 時直接回溯。可透過查詢 Travel 狀態接口确认。
呼叫方：您的伺服器端或用戶端均可呼叫。

HTTP 呼叫

新加坡

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

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

美国（維吉尼亞）

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

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

請求參數

回溯 Travel

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/rewind' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedTravelId": "{encryptedTravelId}",
    "rewindToSec": 84.0,
    "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。由客戶端進入房間接口返回。

rewindToSec number （必選）

目標視頻時間，單位秒。大於或等於 0，建議為 4 的倍數（如 4、8、12）。服務端按 Math.round(rewindToSec / 4) × 4 四捨五入到最近的 4 秒邊界。實際落點以響應中的 resumedAtSec / actualRewindToSec 為準。

userAgent string （可選）

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

回應參數

回溯成功

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "resumedAtSec": 84.0,
        "actualRewindToSec": 84.0
    }
}

code integer

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

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedTravelId string

加密的 Travel ID。

status string

回溯完成後的狀態，返回 running。

resumedAtSec number

實際恢復播放的秒數，可能與請求值略有偏差。

actualRewindToSec number

實際回溯落點，與 resumedAtSec 相同。

前置狀態與呼叫注意事項

Travel 必須先進入 paused；不能在 running 時直接回溯。
暫停 Travel存在約 3 秒的異步確認屏障。收到 pause 響應後，仍應輪詢查詢 Travel 狀態，確認對外狀態已經是 paused 再調用本接口。
劇本按 4 秒 Block 組織，rewindToSec 建議使用 4、8、12 等 4 的倍數（如 6 → 8）。
實際落點以 resumedAtSec / actualRewindToSec 為準。

錯誤碼

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

下一步

回溯後 Travel 回到 running：

查詢 Travel 狀態：確認運行狀態。
普通模式：傳送過程指令。
暫停 Travel：再次暫停以進行下一次回溯。
結束Travel：結束工作階段並處理產物。