Video segmentation-OpenSearch(Open Search)-阿里云帮助中心

Analyzes the semantics and scenes in a video to automatically segment it into multiple segments. For each segment, the service outputs the time range, keyframes, and transcript. This feature is suitable for video index creation, content understanding, and multimodal RAG scenarios.

Service name	Service ID	Service description	API call QPS limit (including root accounts and RAM users)
Video segmentation	ops-video-segment-001	Analyzes video scenes and semantics to segment the video and outputs the time range, keyframes, and transcript for each segment.	5 Note To increase your QPS limit, submit a ticket.

Prerequisites

Obtain authentication credentials
API calls to OpenSearch services must be authenticated. To get your credentials, see Get API-KEY.
Obtain the service endpoint
You can call the service over the public network or a VPC. For details, see Get Service Endpoint.

Request specifications

General notes

Video segmentation supports only asynchronous calls. You must first create an asynchronous task and then use the task ID to query the processing result.
The request body cannot exceed 8 MB.

Create an asynchronous task

Request method

POST

URL

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

Parameters:

host: The service endpoint. For details, see Get Service Endpoint.
workspace_name: The name of the workspace. For example, default.
service_id: The built-in service ID. Currently, only ops-video-segment-001 is supported.

Get the status of an asynchronous task

Request method

GET

URL

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

Parameters:

host: The service endpoint.
workspace_name: The name of the workspace. For example, default.
service_id: The built-in service ID. Currently, only ops-video-segment-001 is supported.
task_id: The task ID returned when you create the asynchronous task.

Request parameters

Header parameters

API key authentication

Parameter	Type	Required	Description	Example value
Content-Type	String	Yes	`application/json`	application/json
Authorization	String	Yes	Your API key, prefixed with `Bearer` .	Bearer OS-d1**2a

Body parameters (create asynchronous task)

Parameter	Type	Required	Description
input	InputObject	Yes	The video file to process.
output	OutputObject	Yes	The output configuration.

InputObject

Parameter	Type	Required	Description	Example value
oss	String	No	The OSS path of the input file. You must specify either `oss` or `url`.	oss://bucket-name/example/test.mp4
url	String	No	The URL of the input file. You must specify either `oss` or `url`.	http://path/to/video.mp4
file_name	String	No	The name of the video file. If omitted, the name is automatically parsed from the file path.	test.mp4

OutputObject

Parameter	Type	Required	Description	Example value
type	String	No	The output type. The default value is `oss`, which saves the result file to OSS.	oss
oss	String	Yes	The OSS path for the output file. This parameter is required when `type` is `oss`.	oss://bucket-name/dump/result/path

Query parameters (get asynchronous task status)

Parameter	Type	Required	Description	Example value
task_id	String	Yes	The ID of the task to query.	0a98da55-9379-43bb-a309-ff165243****

Response parameters

Response parameters (create asynchronous task)

Parameter	Type	Description	Example value
request_id	String	The request ID.	81B80931-E040-5735-85A4-F2826F3A****
latency	Integer	The request latency, in milliseconds.	244
task_id	String	The ID of the created task. You can use this ID to query the task status and result.	0a98da55-9379-43bb-a309-ff165243****

Response parameters (get asynchronous task status)

Parameter	Type	Description	Example
request_id	String	The unique ID that the system assigns to an API call.	A5B25952-4406-45BF-99EC-E8020246****
latency	Float/Int	The request latency in ms.	10
usage.image_token	Int	The number of image tokens consumed.	100
usage.audio_token	Int	The number of audio tokens consumed.	50
result.task_id	String	The unique ID of the asynchronous task.	segment-xxxx-abc-123
result.status	String	The status of the task. Valid values: PENDING, SUCCESS, and FAIL.	SUCCESS
result.error	String	The error message returned if the task fails. This parameter is empty if the task is successful.
result.data	List<VideoChunk>	The result of the video segmentation.

VideoChunk

Parameter	Type	Description
chunk_index	Int	The index of the chunk, starting from 0.
start_time	Float	The start time of the chunk, in seconds.
end_time	Float	The end time of the chunk, in seconds.
snapshots	List<Snapshot>	A list of keyframes in the chunk.
transcript	String	The transcript of the chunk.

Snapshot

Parameter	Type	Description
frame_index	Int	The index of the keyframe in the current clip. The value starts from 0.
path	String	The Object Storage Service (OSS) storage path for the keyframe image.
frame_time	Float	The absolute time of the keyframe in the video, in seconds.

cURL request examples

Create an asynchronous task

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-segmentation/ops-video-segment-001/async' \
--header 'Authorization: Bearer your-api-key' \
--header 'Content-Type: application/json' \
--data '{
  "input": {
    "oss": "oss://my-bucket-name/example/test.mp4"
  },
  "output": {
    "type": "oss",
    "oss": "oss://my-bucket-name/dump/result/path"
  }
}'

Get the status of an asynchronous task

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-segmentation/ops-video-segment-001/async/task-status?task_id=segment-xxxx-abc-123' \
--header 'Authorization: Bearer your-api-key'

Response examples

Create an asynchronous task

{
  "request_id": "bbdf4b6b3798ba144c83571ff2d037be",
  "latency": 30,
  "usage": {},
  "result": {
    "task_id": "video_split-2026031309xxxx-xxxxxxxxxxxxxxxxxx-d677b8b2",
    "status": "PENDING"
  }
}

Get the status of an asynchronous task (task completed)

{
  "request_id": "1",
  "latency": 0,
  "usage": {
    "audio_token": 50,
    "image_token": 100
  },
  "result": {
    "task_id": "split_task_12345",
    "status": "SUCCESS",
    "data": [
      {
        "chunk_index": 0,
        "start_time": 0,
        "end_time": 10,
        "snapshots": [
          {
            "frame_index": 0,
            "path": "oss://bucket-name/path/to/frame0.jpg",
            "frame_time": 0
          },
          {
            "frame_index": 1,
            "path": "oss://bucket-name/path/to/frame1.jpg",
            "frame_time": 5
          }
        ],
        "transcript": "This is the transcript for the first video segment."
      },
      {
        "chunk_index": 1,
        "start_time": 10,
        "end_time": 20,
        "snapshots": [
          {
            "frame_index": 0,
            "path": "oss://bucket-name/path/to/frame2.jpg",
            "frame_time": 10
          }
        ],
        "transcript": "This is the transcript for the second video segment."
      }
    ]
  }
}

Status code description

For more information, see the Status code description for OpenSearch.