Skip to main content

HappyOyster-Adventure-結束Travel API參考

主動結束 Adventure Travel。正常結束後進入 completed；無推流超時結束時進入 failed，且不產生回放產物。達到 maxExperienceTimeSec 時服務端也會自動結束。

適用範圍

主動結束 Adventure Travel。正常結束後 Travel 進入 completed；無推流超時結束時進入 failed。呼叫前請確認以下事項：
  • 驗證要求：不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。獲取方式請參閱獲取驗證憑證。
  • 前置條件：Travel 必須尚未進入終態，並處於伺服器端可結束的狀態。可透過查詢 Travel 狀態介面确认。
  • 呼叫方：您的伺服器端或用戶端均可呼叫。

HTTP 呼叫

  • 新加坡
  • 华北2（北京）
  • 美国（維吉尼亞）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/end呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

請求參數

  • 正常結束
  • 無推流逾時結束
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/end' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedTravelId": "{encryptedTravelId}",
    "userAgent": "HappyOyster-Web/0.1.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 （必選）要結束的 Adventure 加密 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",
        "errorCode": null,
        "errorMessage": null,
        "endedAt": "2026-06-04T00:03:00Z",
        "durationSec": 90
    }
}
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。

前置狀態與呼叫注意事項

  • encryptedTravelId 必須屬於目前主帳號和 Adventure 模型。
  • 省略 failCode 時按正常結束處理；傳入未支援的值則返回 400000。
  • 達到 maxExperienceTimeSec 後服務端會自動結束 Travel；用戶端應以狀態回調或狀態查詢結果收斂本機狀態。
  • 正常結束的 durationSec 優先使用可用成片的實際時長；成片時長尚無法解析時可能為 null。
  • 正常結束狀態為 completed 後，合成產物仍可能繼續處理，應按查詢 Travel 產物進行查詢並輪詢。

錯誤碼

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

下一步

Travel 進入 completed 後：