调用视频截帧API执行同步与异步任务-智能开放搜索 OpenSearch-阿里云-智能开放搜索 OpenSearch(Open Search)-阿里云帮助中心

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	内部错误。

更多状态码说明，请参见状态码说明。