视频切割-智能开放搜索 OpenSearch(Open Search)-阿里云帮助中心

对视频进行语义理解和场景分析，自动将视频按内容切割为多个片段，输出每个片段的时间范围、关键帧截图和字幕信息，适用于视频索引构建、内容理解和多模态 RAG 场景。

服务名称	服务ID	服务描述	API调用QPS限制（含主账号与RAM子账号）
视频切割	ops-video-segment-001	对视频进行场景分析和语义切割，输出片段的时间范围、关键帧和字幕信息。	5 说明如需扩充QPS，请通过工单联系技术支持协助。

前提条件

获取身份鉴权信息

通过API调用AI搜索开放平台服务时，需要对调用者身份进行鉴权，如何获取鉴权信息请参见获取API-KEY。
获取服务调用地址

支持通过公网和VPC两种方式调用服务，详情请参见获取服务接入地址。

重要

使用OSS输入文件或保存结果时，相关Bucket均需与服务处于同一地域，并添加标签（Key和Value均为opensearch）。操作方法请参见管理存储空间标签。

请求说明

公共说明

视频切割仅支持异步调用方式，需要先创建异步任务，再通过任务ID查询处理结果。
请求body最大不能超过8MB。

创建异步任务

请求方式

POST

URL

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

参数说明：

host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。
workspace_name：工作空间名称，例如default。
service_id：系统内置服务ID，当前仅支持ops-video-segment-001。

获取异步任务状态

请求方式

GET

URL

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

参数说明：

host：调用服务的地址。
workspace_name：工作空间名称，例如default。
service_id：系统内置服务ID，当前仅支持ops-video-segment-001。
task_id：创建异步任务时返回的任务ID。

请求参数

Header参数

API-KEY认证

参数	类型	必填	描述	示例值
Content-Type	String	是	请求类型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body参数（创建异步任务）

参数	类型	必填	描述
input	InputObject	是	待处理的视频文件信息。
output	OutputObject	是	处理结果的输出配置。

InputObject

参数	类型	必填	描述	示例值
OSS	String	否	输入文件的OSS路径。与URL二选一。	OSS://bucket-name/example/test.mp4
URL	String	否	输入文件的HTTP地址。与OSS二选一。	http://path/to/video.mp4
file_name	String	否	视频文件名称。未设置时从文件路径中自动解析。	test.mp4

OutputObject

参数	类型	必填	描述	示例值
type	String	否	输出类型。默认值为OSS，表示将结果文件存放到OSS。	OSS
OSS	String	是	输出文件的OSS路径，type为OSS时必填。	OSS://bucket-name/dump/result/path

Query参数（获取异步任务状态）

参数	类型	必填	描述	示例值
task_id	String	是	创建异步任务返回的任务ID。	segment-xxxx-abc-123

返回参数

创建异步任务

参数	类型	描述	示例值
request_id	String	系统对一次API调用赋予的唯一标识。	A5B25952-4406-45BF-99EC-E8020246****
latency	Float/Int	请求耗时，单位ms。	10
result.task_id	String	异步任务的唯一标识ID。	segment-xxxx-abc-123

获取异步任务状态

参数	类型	描述	示例值
request_id	String	系统对一次API调用赋予的唯一标识。	A5B25952-4406-45BF-99EC-E8020246****
latency	Float/Int	请求耗时，单位ms。	10
usage.image_token	Int	消耗的图片token数。	100
usage.audio_token	Int	消耗的音频token数。	50
result.task_id	String	异步任务的唯一标识ID。	segment-xxxx-abc-123
result.status	String	任务状态。取值：PENDING（待处理）、SUCCESS（成功）、FAIL（失败）。	SUCCESS
result.error	String	任务失败时的错误信息，成功时为空。
result.data	List<VideoChunk>	视频切割结果。

VideoChunk

参数	类型	描述
chunk_index	Int	片段序号，从0开始。
start_time	Float	片段起始时间，单位为秒。
end_time	Float	片段结束时间，单位为秒。
snapshots	List<Snapshot>	片段的关键帧列表。
transcript	String	片段的字幕文本。

Snapshot

参数	类型	描述
frame_index	Int	关键帧在当前片段中的序号，从0开始。
path	String	关键帧图片的OSS存储路径。
frame_time	Float	关键帧在视频中的绝对时间，单位为秒。

Curl请求示例

创建异步任务

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-segmentation/ops-video-segment-001/async' \
--header 'Authorization: Bearer 您的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"
  }
}'

获取异步任务状态

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 您的API-KEY'

响应示例

创建异步任务

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

获取异步任务状态（任务完成）

{
  "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": "这是第一个视频片段的转录文本"
      },
      {
        "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": "这是第二个视频片段的转录文本"
      }
    ]
  }
}

状态码说明

请参见AI搜索开放平台状态码说明。