IPC摄像头视频关键事件提取API - 云原生数据仓库AnalyticDB

IPC摄像头视频事件抽取与理解服务提供视频内容的智能分析能力。用户提交OSS视频路径，服务自动完成事件片段抽取（关键帧抽取）、视频事件理解、生成Embedding等处理流程。本文介绍该API的请求参数、响应参数和使用示例。

接口说明

该接口为HTTP异步接口，包含两个子接口：

提交关键事件提取任务：提交视频分析任务，返回任务ID。
查询任务结果：通过任务ID查询处理结果。

接口一：提交关键事件提取任务

请求定义

URL：POST /api/v1/operators/video-event-extraction/tasks/submit

Content-Type：application/json

请求参数

必填参数

参数	类型	必填	说明
video_uri	string	是	OSS视频路径，格式如`oss://bucket/path/to/video.mp4`。

可选参数 - 鉴权配置

参数	类型	必填	说明
role_arn	string	否	RAM角色ARN，用于访问video_uri对应的OSS资源，需提前创建并授权。示例值：`acs:ram::${AliyunAccount}:role/adb-multimodal-oss-role`。

可选参数 - 模型配置

参数	类型	必填	说明
prompt	string	否	视频理解Prompt，不传则使用默认Prompt。
embedding_dim	int	否	Embedding维度，默认1024。

可选参数 - 视频处理配置

参数	类型	必填	默认值	说明
sample_fps	float	否	1.0	采样帧率，以1/sample_fps秒为间隔进行抽帧，用于场景变化检测。
merge_gap	float	否	3.0	事件合并间隔（秒），两个事件片段间隔小于此值则合并。
min_duration	float	否	2.55	事件最小长度（秒），短于此值的片段将被丢弃。
max_frames_per_segment	int	否	30	每个事件片段的最大关键帧数，同时也是发送给VL模型的最大帧数。
frame_short_side	int	否	480	关键帧短边缩放目标值（像素）。
frame_store_mode	string	否	none	关键帧存储模式。取值： `none`：不保存关键帧。 `user`：上传到用户指定的OSS目录。 `adb`：上传到AnalyticDB for MySQL内部临时存储，可通过HTTP URL下载。
frame_store_path	string	否	无	关键帧保存的OSS目录路径，格式如`oss://bucket/store/path`。仅当frame_store_mode为`user`时需要配置。

请求示例

基础请求（使用默认配置）

curl -X POST "http://amv-xxxxxx.ads.aliyuncs.com:8000/api/v1/operators/video-event-extraction/tasks/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "video_uri": "oss://my-bucket/videos/sample.mp4"
  }'

自定义模型配置

curl -X POST "http://amv-xxxxxx.ads.aliyuncs.com:8000/api/v1/operators/video-event-extraction/tasks/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "video_uri": "oss://my-bucket/videos/sample.mp4",
    "prompt": "请分析视频中的事件，识别人物行为和场景变化",
    "embedding_dim": 1024
  }'

自定义视频处理参数

curl -X POST "http://amv-xxxxxx.ads.aliyuncs.com:8000/api/v1/operators/video-event-extraction/tasks/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "video_uri": "oss://my-bucket/videos/sample.mp4",
    "prompt": "请分析视频中的事件，识别人物行为和场景变化",
    "sample_fps": 1.0,
    "merge_gap": 5.0,
    "min_duration": 3.0,
    "max_frames_per_segment": 25,
    "frame_short_side": 480,
    "frame_store_mode": "user",
    "frame_store_path": "oss://bucket/prefix"
  }'

响应参数

参数	类型	说明
status	string	任务提交状态。取值：`SUCCESS`（成功）、`FAILED`（失败）。
task_id	string	任务ID，用于后续查询任务结果。
message	string	错误信息，仅在提交失败时返回。

响应示例

提交成功

{
  "status": "SUCCESS",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": null
}

提交失败

{
  "status": "FAILED",
  "task_id": null,
  "message": "Task submission failed, please contact technical support."
}

接口二：查询任务结果

请求定义

URL：GET /api/v1/operators/video-event-extraction/tasks/results/{task_id}

请求示例

curl -X GET "http://amv-xxxxxx.ads.aliyuncs.com:8000/api/v1/operators/video-event-extraction/tasks/results/xxxxxxxx"

响应参数

参数	类型	说明
task_status	string	任务状态。取值：`NEW`（新建）、`PROCESSING`（处理中）、`SUCCESS`（成功）、`FAILED`（失败）。
video_uri	string	处理的视频OSS路径。
message	string	错误信息，仅在任务失败时返回。
data	array	事件抽取结果数组，仅在任务成功时返回。
data[].index	int	事件片段序号，从1开始递增。
data[].content	string	事件理解内容描述。
data[].embedding	array[float]	事件内容的向量表示。
data[].start_time	float	事件起始时间（毫秒）。
data[].end_time	float	事件终止时间（毫秒）。
data[].usage	array[object]	模型Token用量信息，包含model_name、input_tokens、output_tokens。
data[].frame_path	string	关键帧ZIP包的OSS路径，仅当frame_store_mode为`user`时返回。
data[].frame_vpc_url	string	关键帧ZIP包的临时签名链接，仅当frame_store_mode为`adb`时返回。

响应示例

任务处理中

{
  "task_status": "PROCESSING",
  "video_uri": "oss://my-bucket/videos/sample.mp4",
  "message": null,
  "data": null
}

任务成功

{
  "task_status": "SUCCESS",
  "message": null,
  "video_uri": "oss://my-bucket/videos/sample.mp4",
  "data": [
    {
      "index": 1,
      "start_time": 2000.0,
      "end_time": 9130.0,
      "content": "视频中第一个人进入室内，身穿蓝色外套，推门而入",
      "embedding": [0.0123, -0.0456, 0.0789, "..."],
      "usage": [
        {
          "model_name": "qwen3.5-flash",
          "input_tokens": 2521,
          "output_tokens": 84
        },
        {
          "model_name": "text-embedding-v4",
          "input_tokens": 90,
          "output_tokens": 0
        }
      ],
      "frame_path": "oss://xxx/xxx/20260408/a960fed4/event_001.zip",
      "frame_vpc_url": null
    },
    {
      "index": 2,
      "start_time": 9850.0,
      "end_time": 15380.0,
      "content": "人物在客厅走动，查看周围环境",
      "embedding": [0.0234, -0.0567, 0.0890, "..."],
      "usage": [
        {
          "model_name": "qwen3.5-flash",
          "input_tokens": 2556,
          "output_tokens": 112
        },
        {
          "model_name": "text-embedding-v4",
          "input_tokens": 134,
          "output_tokens": 0
        }
      ],
      "frame_path": "oss://xxx/xxx/20260408/a960fed4/event_002.zip",
      "frame_vpc_url": null
    }
  ]
}

任务失败

{
  "task_status": "FAILED",
  "video_uri": "oss://my-bucket/videos/sample.mp4",
  "message": "The video file does not exist or cannot be accessed.",
  "data": null
}