Video snapshot - OpenSearch - Alibaba Cloud Documentation Center

The AI Search Open Platform supports calling the video snapshot service through an API. This service extracts keyframes from videos and combines them with OCR, image parsing, or multimodal embedding services to enable deep analysis and structured processing of video content.

Services

Service Name	Service ID	Service Description	API Call QPS Limit (Includes Root Account and RAM Users)
Video Snapshot Service 001	ops-video-snapshot-001	Video Snapshot Service 001 (ops-video-snapshot-001) extracts content from videos by capturing keyframes. Combined with multimodal embedding or image parsing capabilities, it enables cross-modal retrieval.	5 Note To request a higher API QPS limit, submit a ticket to technical support.

Get authentication credentials

The AI Search open platform requires an API key for authentication. For instructions, see Get an API key.
Get the service endpoint

You can call the service via the public network or a VPC. For details, see Get the service endpoint.

Create an Asynchronous Task

Request method: POST

URL

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

host: The service endpoint. You can call the API over the Internet or through a VPC. For details, see Get Service Endpoint.

In the console, click API Keys in the navigation pane on the left. Under Endpoints, you will see the Public API Domain (supports HTTPS) and the Private API Domain (for VPC environments). Use the workspace dropdown in the top-left corner to switch to your target workspace.

workspace_name: The workspace name, such as default.
service_id: The built-in service ID, such as ops-video-snapshot-001.

Request Parameters

Header Parameters

API key authentication

Parameter	Type	Required	Description	Example Value
Content-Type	String	Yes	Request type: application/json	application/json
Authorization	String	Yes	API key	Bearer OS-d1**2a

Body Parameters

Parameter	Type	Required	Description
input	Object(input)	Yes	Specifies the multimedia file to process.
parameters	Object	No	Specifies service parameters.
output	Object(output)	Yes	Controls the output format and file storage path.

input

Parameter	Type	Required	Description
content	String	No	Base64-encoded video data. Supports mp4, avi, mkv, mov, flv, and webm. Note The input.content and input.oss parameters are mutually exclusive. Specify only one. Use Base64 data: Pass the encoded Base64 string to the `content` parameter in the format `data:video/<FORMAT>;base64,<BASE64_VIDEO>`, where: `video/<FORMAT>`: The video format. For example, for an MP4 video, use `video/mp4`. `<BASE64_VIDEO>`: The Base64-encoded video data. Example: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	No	The OSS path of the input file, for example, oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	No	The video file name. If not specified, the name is parsed from the file content.

Parameters

Parameter	Type	Required	Description
interval	Int	No	Frame extraction interval in seconds. Default is 1 second.
format	String	No	Output frame format. Supports jpg and png. Default is jpg.

output

Parameter

Type

Required

Description

type

String

base64: Returns image content in Base64 format. Supported only for synchronous calls.

oss: Stores extracted frames in OSS (default).

oss

String

The OSS path for output files. Required when type is oss.

Example: oss://<BUCKET_NAME>/result/path

Response Parameters

Parameter	Type	Description	Example Value
result.task_id	String	The unique ID of the video extraction task.	snapshot-xxxx-abc-123

Curl Request Example

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your 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"
    }
  }' \

Response Example

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

Get Asynchronous Task Status

Request method: GET

URL

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

host: The service endpoint. You can call the API over the Internet or through a VPC. For details, see Get Service Endpoint.

workspace_name: The workspace name, such as default.
service_id: The built-in service ID, such as ops-video-snapshot-001.

Request Parameters

Parameter Name	Type	Required	Description	Example
service_id	String	Yes	Service ID.	ops-video-snapshot-001
task_id	String	Yes	The task ID returned when creating the asynchronous video snapshot task.	snapshot-xxxx-abc-123

Response Parameters

Parameter	Type	Description	Example Value
result.task_id	String	The unique ID of the video extraction task.	snapshot-xxxx-abc-123
result.status	String	Task status: PENDING: Waiting to be processed SUCCESS: Task completed successfully FAIL: Task failed and stopped	PENDING
result.error	String	Error message when status is FAIL. Empty under normal conditions.
result.data	List(SnapshotResult)	Video processing results.
usage.image_count	Int	Number of extracted frames.

SnapshotResult

Parameter	Type	Description
frame_index	Int	Frame number in the video.
path	String	The OSS path of the file. When output is set to OSS, this field shows the URL-encoded storage path of the extracted frame in OSS.
content	String	Base64-encoded image content. Only one of content or path is present, and this field appears only for synchronous tasks.
frame_time	Float	Timestamp of the extracted frame in the video, in seconds.

Curl Request Example

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Your 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-******" \

Response Example

{
  "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
                }                
              ]
            }
}

Create a Synchronous Video Snapshot Task

URL

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

host: The service endpoint. You can call the API over the Internet or through a VPC. For details, see Get Service Endpoint.

workspace_name: The workspace name, such as default.
service_id: The built-in service ID, such as ops-video-snapshot-001.

Request Parameters

Header Parameters

API key authentication

Parameter	Type	Required	Description	Example Value
Content-Type	String	Yes	Request type: application/json	application/json
Authorization	String	Yes	API key	Bearer OS-d1**2a

Body Parameters

Parameter	Type	Required	Description
input	Object(input)	Yes	Specifies the multimedia file to process.
parameters	Object	No	Specifies service parameters.
output	Object(output)	Yes	Controls the output format and file storage path.

input

Parameter	Type	Required	Description
content	String	No	Base64-encoded video data. Supports mp4, avi, mkv, mov, flv, and webm. Note The input.content and input.oss parameters are mutually exclusive. Specify only one. Use Base64 data: Pass the encoded Base64 string to the `content` parameter in the format `data:video/<FORMAT>;base64,<BASE64_VIDEO>`, where: `video/<FORMAT>`: The video format. For example, for an MP4 video, use `video/mp4`. `<BASE64_VIDEO>`: The Base64-encoded video data. Example: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	No	The OSS path of the input file, for example, oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	No	The video file name. If not specified, the name is parsed from the file content.

Parameters

Parameter	Type	Required	Description
interval	Int	No	Frame extraction interval in seconds. Default is 1 second.
format	String	No	Output frame format. Supports jpg and png. Default is jpg.

output

Parameter

Type

Required

Description

type

String

base64: Returns image content in Base64 format. Supported only for synchronous calls.

oss: Stores extracted frames in OSS (default).

oss

String

The OSS path for output files. Required when type is oss.

Example: oss://<BUCKET_NAME>/result/path

Response Parameters

Parameter	Type	Description	Example Value
result.task_id	String	The unique ID of the video extraction task.	snapshot-xxxx-abc-123

Curl Request Example

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your 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"
    }
  }' \

Response Example

{
  "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
                }                
              ]
            }
}

Status Code Reference

If a request fails, the response includes a code and message that explain the error.

{
    "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 Status Code	Error Code	Description
200	-	Request succeeded. This includes cases where the task itself failed. Check result.status for the actual task status.
404	BadRequest.TaskNotExist	Task does not exist.
400	InvalidParameter	Invalid request.
500	InternalServerError	Internal error.

For more information about status codes, see Status Code Reference.