調用視頻截幀API執行同步與非同步任務-智能OpenSearch OpenSearch-阿里雲 - OpenSearch

AI搜尋開放平台支援通過API的方式調用視頻截幀服務，可從視頻中提取主要畫面格畫面，並結合文字識別（OCR）、映像解析或多模態向量服務，實現對視頻內容的深度解析與結構化處理。

服務列表

服務名稱	服務ID	服務描述	API調用QPS限制（含主帳號與RAM子帳號）
視頻截幀服務001	ops-video-snapshot-001	視頻截幀服務001（ops-video-snapshot-001）提供視頻內容提取能力，可從視頻中捕獲主要畫面格畫面。結合多模態向量服務或圖片解析能力，實現跨模態檢索。	5 說明如需擴充QPS，請通過工單聯絡支援人員協助。

擷取身份鑒權資訊

通過API調用AI搜尋開放平台服務時，需要對調用者身份進行鑒權，如何擷取鑒權資訊請參見擷取API-KEY。
擷取服務調用地址

支援通過公網和VPC兩種方式調用服務，詳情請參見擷取服務接入地址。

建立非同步任務

請求方式：POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/async

host：調用服務的地址，支援通過公網和VPC兩種方式調用API服務，可參見擷取服務接入地址。

在控制台左側導覽列單擊API Keys，頁面訪問網域名稱地區展示公網API網域名稱（支援HTTPS）和私網API網域名稱（適用於VPC網路環境）。左上方通過空間下拉框切換目標空間。

workspace_name：工作空間名稱，例如default。
service_id：系統內建服務ID，例如ops-video-snapshot-001。

請求參數

Header參數

API-KEY認證

參數	類型	必填	描述	樣本值
Content-Type	String	是	請求類型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body參數

參數	類型	必填	描述
input	Object(input)	是	指定待處理的多媒體檔案。
parameters	Object	否	指定服務的參數。
output	Object(output)	是	控制輸出的格式及檔案存放路徑。

input

參數	類型	必填	描述
content	String	否	視頻內容的base64編碼資料，支援mp4、avi、mkv、mov、flv、webm。說明 input.content 和 input.oss 參數互斥，只能二選一。使用BASE64資料：將編碼後的BASE64資料傳遞給`content`參數，格式為`data:video/<FORMAT>;base64,<BASE64_VIDEO>`，其中： `video/<FORMAT>`：視頻的格式，例如視頻為mp4格式，則設定為`video/mp4`。 `<BASE64_VIDEO>`：映像的BASE64資料。樣本：data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	否	輸入檔案的OSS路徑，例如 oss://<BUCKET_NAME>/xxx/xxx.mp4。
file_name	String	否	視頻檔案的名稱，如果沒有設定，則從內容的檔案名稱中解析。

Parameters

參數	類型	必填	描述
interval	Int	否	切幀間隔（秒），預設1秒。
format	String	否	切幀輸出的格式，支援jpg和png，預設jpg。

output

參數

類型

必填

描述

type

String

否

base64：以base64的格式將圖片內容返回，僅同步調用下支援。

oss：截幀檔案放在OSS中（預設）。

oss

String

否

輸出檔案的OSS路徑，在type為oss的情況下必須填寫。

樣本：oss://<BUCKET_NAME>/result/path

返回參數

參數	類型	描述	樣本值
result.task_id	String	視頻提取任務的唯一標識ID。	snapshot-xxxx-abc-123

Curl請求樣本

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <您的API-KEY>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/async"
  --data '{
    "input":{
        "oss" : "oss://<BUCKET_NAME>/test.mp4"
    },
    "parameters" : {
    },
    "output": {
        "type":"oss",
        "oss" :"oss://<BUCKET_NAME>/result/path"
    }
  }' \

響應樣本

{
  "request_id":"de81e152284a2d3b1f4315d*******",
  "latency":21,
  "usage":{},
  "result":{
        "task_id":"snapshot-20250617102142-110841*******-*******",
        "status":"PENDING"
            }
 }

擷取非同步任務的狀態

請求方式：GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/async/task-status?task_id={task_id}

host：調用服務的地址，支援通過公網和VPC兩種方式調用API服務，可參見擷取服務接入地址。

workspace_name：工作空間名稱，例如default。
service_id：系統內建服務ID，例如ops-video-snapshot-001。

請求參數

參數名	類型	必填	描述	樣本
service_id	String	是	服務ID。	ops-video-snapshot-001
task_id	String	是	建立非同步視頻截幀任務響應中的任務標識。	snapshot-xxxx-abc-123

返回參數

參數	類型	描述	樣本值
result.task_id	String	視頻提取任務的唯一標識ID。	snapshot-xxxx-abc-123
result.status	String	任務狀態： PENDING：待處理 SUCCESS：任務成功完成 FAIL：任務失敗終止	PENDING
result.error	String	status=FAIL時的錯誤資訊內容，正常情況為空白。
result.data	List(SnapshotResult)	視頻處理的結果。
usage.image_count	Int	截幀輸出的圖數。

SnapshotResult

參數	類型	描述
frame_index	Int	視頻中的第幾幀。
path	String	檔案的OSS路徑, 使用者指定輸出為OSS的時候，截幀的結果在OSS的存放路徑，URL編碼後的內容。
content	String	圖片的base64編碼後的內容。和path兩者只會有一個存在，並且僅在執行同步任務的時候才會返回。
frame_time	Float	當前截幀在視頻中的時間戳記，單位是s。

Curl請求樣本

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <您的API-KEY>" \
"http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/async/task-status?task_id=snapshot-20250617102142-1108418170738252-******" \

響應樣本

{
  "request_id":"83b423e2e63613a878c369c20******",
  "latency":11,
  "usage":{
      "image":64
          },
  "result":{
      "task_id":"snapshot-20250617102142-1108418170738252-******",
      "status":"SUCCESS",
       "data":[
                {
                  "frame_index": 0,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_0.jpg",
                  "frame_time": 0.0
                },
                ......
                {
                  "frame_index": 1890,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_63.jpg",
                  "frame_time": 63.0
                }                
              ]
            }
}

建立視頻截幀同步任務

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/sync

host：調用服務的地址，支援通過公網和VPC兩種方式調用API服務，可參見擷取服務接入地址。

workspace_name：工作空間名稱，例如default。
service_id：系統內建服務ID，例如ops-video-snapshot-001。

請求參數

Header參數

API-KEY認證

參數	類型	必填	描述	樣本值
Content-Type	String	是	請求類型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body參數

參數	類型	必填	描述
input	Object(input)	是	指定待處理的多媒體檔案。
parameters	Object	否	指定服務的參數。
output	Object(output)	是	控制輸出的格式及檔案存放路徑。

input

參數	類型	必填	描述
content	String	否	視頻內容的base64編碼資料，支援mp4、avi、mkv、mov、flv、webm。說明 input.content 和 input.oss 參數互斥，只能二選一。使用BASE64資料：將編碼後的BASE64資料傳遞給`content`參數，格式為`data:video/<FORMAT>;base64,<BASE64_VIDEO>`，其中： `video/<FORMAT>`：視頻的格式，例如視頻為mp4格式，則設定為`video/mp4`。 `<BASE64_VIDEO>`：映像的BASE64資料。樣本：data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	否	輸入檔案的OSS路徑，例如 oss://<BUCKET_NAME>/xxx/xxx.mp4。
file_name	String	否	視頻檔案的名稱，如果沒有設定，則從內容的檔案名稱中解析。

Parameters

參數	類型	必填	描述
interval	Int	否	切幀間隔（秒），預設1秒。
format	String	否	切幀輸出的格式，支援jpg和png，預設jpg。

output

參數

類型

必填

描述

type

String

否

base64：以base64的格式將圖片內容返回，僅同步調用下支援。

oss：截幀檔案放在OSS中（預設）。

oss

String

否

輸出檔案的OSS路徑，在type為oss的情況下必須填寫。

樣本：oss://<BUCKET_NAME>/result/path

返回參數

參數	類型	描述	樣本值
result.task_id	String	視頻提取任務的唯一標識ID。	snapshot-xxxx-abc-123

Curl請求樣本

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <您的API-KEY>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/sync"
  --data '{
    "input":{
        "oss" : "oss://<BUCKET_NAME>/test.mp4"
    },
    "parameters" : {
    },
    "output": {
        "type":"oss",
        "oss" :"oss://<BUCKET_NAME>/result/path"
    }
  }' \

響應樣本

{
  "request_id":"83b423e2e63613a878c369c20******",
  "latency":11,
  "usage":{
      "image":64
          },
  "result":{
      "task_id":"snapshot-20250617102142-1108418170738252-b******",
      "status":"SUCCESS",
       "data":[
                {
                  "frame_index": 0,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_0.jpg",
                  "frame_time": 0.0
                },
                ......
                {
                  "frame_index": 1890,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_63.jpg",
                  "frame_time": 63.0
                }                
              ]
            }
}

狀態代碼說明

在訪問請求出錯的情況下，輸出結果中會通過code和message指明出錯原因。

{
    "request_id": "6F33AFB6-A35C-4DA7-AFD2-9EA16CCF****",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\"
}

HTTP 狀態代碼	錯誤碼	描述
200	-	請求成功，包括任務失敗情境，實際任務狀態需從result.status中判斷。
404	BadRequest.TaskNotExist	任務不存在。
400	InvalidParameter	不合法請求。
500	InternalServerError	內部錯誤。

更多狀態代碼說明，請參見狀態代碼說明。