Video snapshot - OpenSearch - Alibaba Cloud Documentation Center

Extracts keyframes from a video as image snapshots. Combine with Optical Character Recognition (OCR), image parsing, or multimodal embedding to parse and structure video content.

Available services

Service name	Service ID	Description	QPS limit
Video Snapshot Service 001	ops-video-snapshot-001	Extracts keyframes from a video. Combine with multimodal embedding or image parsing to enable cross-modal retrieval.	5 (shared across your Alibaba Cloud account and RAM users). To request a higher limit, submit a ticket.

Prerequisites

Before you begin, make sure that you have:

Authentication credentials: an API key for authenticating API calls.
Service endpoint: the address for calling the service over the internet or through a virtual private cloud (VPC). See Get service access address.

Create an asynchronous task

Submits an asynchronous video snapshot task. After submission, poll Get async task status to retrieve results.

Method: POST

URL:

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

Path parameter	Description	Example
`host`	The service endpoint. See Get service access address.	`http://***-hangzhou.opensearch.aliyuncs.com`
`workspace_name`	The name of the workspace.	`default`
`service_id`	The service ID.	`ops-video-snapshot-001`

Request parameters

Headers

Parameter	Type	Required	Description	Example
`Content-Type`	String	Yes	The content type of the request body.	`application/json`
`Authorization`	String	Yes	The API key for authentication.	`Bearer OS-d1**2a`

Body

Parameter	Type	Required	Description
`input`	Object	Yes	The video to process.
`parameters`	Object	No	The extraction parameters.
`output`	Object	Yes	The output format and storage path.

input

Parameter	Type	Required	Description
`content`	String	No	The Base64-encoded video content. Supported formats: mp4, avi, mkv, mov, flv, and webm. Mutually exclusive with `input.oss` — specify one only. Format: `data:video/<FORMAT>;base64,<BASE64_VIDEO>`. Example: `data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...`
`oss`	String	No	The Object Storage Service (OSS) path of the input video. Mutually exclusive with `input.content` — specify one only. Format: `oss://<BUCKET_NAME>/xxx/xxx.mp4`
`file_name`	String	No	The video file name. If not specified, the name is parsed from `content`.

parameters

Parameter	Type	Required	Description
`interval`	Int	No	The keyframe extraction interval, in seconds. Default: `1`.
`format`	String	No	The image format for captured frames. Valid values: `jpg`, `png`. Default: `jpg`.

output

Parameter	Type	Required	Description
`type`	String	No	The output type. Valid values: `oss` (stores snapshot files in OSS; default), `base64` (returns image content as Base64-encoded strings; supported for synchronous calls only).
`oss`	String	No	The OSS path for output files. Required when `type` is `oss`. Format: `oss://<BUCKET_NAME>/result/path`

Response parameters

Parameter	Type	Description	Example
`result.task_id`	String	The ID of the asynchronous task.	`snapshot-xxxx-abc-123`
`result.status`	String	The initial task status. Value at submission: `PENDING`.	`PENDING`

Example

Request:

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:

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

Get the status of an asynchronous task

Queries the status and results of an asynchronous video snapshot task. Poll this endpoint after calling Create an asynchronous task until result.status is SUCCESS or FAIL.

Method: GET

URL:

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

Path parameter	Description	Example
`host`	The service endpoint. See Get service access address.	`http://***-hangzhou.opensearch.aliyuncs.com`
`workspace_name`	The name of the workspace.	`default`
`service_id`	The service ID.	`ops-video-snapshot-001`

Request parameters

Parameter	Type	Required	Description	Example
`service_id`	String	Yes	The ID of the video snapshot service.	`ops-video-snapshot-001`
`task_id`	String	Yes	The task ID returned by Create an asynchronous task.	`snapshot-xxxx-abc-123`

Response parameters

Parameter	Type	Description	Example
`result.task_id`	String	The task ID.	`snapshot-xxxx-abc-123`
`result.status`	String	The task status. Valid values: `PENDING` (in progress), `SUCCESS` (completed), `FAIL` (failed).	`PENDING`
`result.error`	String	The error message. Populated only when `result.status` is `FAIL`.
`result.data`	List	The snapshot results. See SnapshotResult below. Populated when `result.status` is `SUCCESS`.
`usage.image_count`	Int	The number of images extracted from the video.

SnapshotResult

Parameter	Type	Description
`frame_index`	Int	The index of the frame in the video.
`path`	String	The URL-encoded OSS path of the snapshot file. Returned when `output.type` is `oss`.
`content`	String	The Base64-encoded image content. Returned only for synchronous tasks. Only one of `path` or `content` is returned per frame.
`frame_time`	Float	The timestamp of the frame in the video, in seconds.

Example

Request:

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:

{
  "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 task

Submits a synchronous video snapshot task and returns results in a single response. Use this endpoint for short videos or when you need immediate results. For longer videos, use Create an asynchronous task instead.

Method: POST

URL:

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

Path parameter	Description	Example
`host`	The service endpoint. See Get service access address.	`http://***-hangzhou.opensearch.aliyuncs.com`
`workspace_name`	The name of the workspace.	`default`
`service_id`	The service ID.	`ops-video-snapshot-001`

Request parameters

Headers

Parameter	Type	Required	Description	Example
`Content-Type`	String	Yes	The content type of the request body.	`application/json`
`Authorization`	String	Yes	The API key for authentication.	`Bearer OS-d1**2a`

Body

Same as Create an asynchronous task — input, parameters, and output objects with identical fields.

For synchronous tasks, output.type supports both oss and base64. Set type to base64 to receive snapshot images directly in the response without writing to OSS.

Response parameters

Parameter	Type	Description	Example
`result.task_id`	String	The task ID.	`snapshot-xxxx-abc-123`
`result.status`	String	The task status. Valid values: `SUCCESS`, `FAIL`.	`SUCCESS`
`result.data`	List	The snapshot results. See SnapshotResult in Get the status of an asynchronous task.
`usage.image_count`	Int	The number of images extracted from the video.

Example

Request:

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:

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

Error codes

When a request fails, the response includes code and message fields indicating the cause.

{
  "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	—	The request succeeded. Note that HTTP 200 does not indicate task success — check `result.status` for the actual task outcome.
404	`BadRequest.TaskNotExist`	The specified task does not exist.
400	`InvalidParameter`	The request parameters are invalid.
500	`InternalServerError`	An internal server error occurred.

For the full list of status codes, see Status code descriptions.