IPC camera video event extraction API-AnalyticDB(AnalyticDB)-阿里云帮助中心

The IPC camera video event extraction service analyzes video content end to end. You submit an OSS video path, and the service extracts event segments through smart keyframe extraction, generates semantic descriptions with a vision language model, and produces vector embeddings. This topic describes the request parameters, response parameters, and usage examples for the API.

Overview

The API is asynchronous over HTTP and includes two operations:

Submit an extraction task: Submits a video for analysis and returns a task ID.
Query task results: Retrieves the processing result by task ID.

Operation 1: Submit an extraction task

Request definition

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

Content-Type: application/json

Request parameters

Required parameters

Parameter	Type	Required	Description
video_uri	string	Yes	The OSS path of the video, in the format `oss://bucket/path/to/video.mp4`.

Optional parameters — Authorization

Parameter	Type	Required	Description
role_arn	string	No	The RAM role ARN used to access the OSS resource referenced by video_uri. The role must be created and authorized in advance. Example: `acs:ram::${AliyunAccount}:role/adb-multimodal-oss-role`.

Optional parameters — Model configuration

Parameter	Type	Required	Description
prompt	string	No	The prompt used for video understanding. If omitted, the default prompt is used.
embedding_dim	int	No	The embedding dimension. Default: 1024.

Optional parameters — Video processing

Parameter	Type	Required	Default	Description
sample_fps	float	No	1.0	The sampling rate. Frames are extracted at intervals of 1/sample_fps seconds for scene change detection.
merge_gap	float	No	3.0	The event merge gap, in seconds. Two adjacent event segments separated by less than this value are merged.
min_duration	float	No	2.55	The minimum event length, in seconds. Segments shorter than this value are discarded.
max_frames_per_segment	int	No	30	The maximum number of keyframes per event segment. This is also the maximum number of frames sent to the VLM.
frame_short_side	int	No	480	The target size of the short side of the keyframes, in pixels.
frame_store_mode	string	No	none	The keyframe storage mode. Valid values: `none`: keyframes are not saved. `user`: keyframes are uploaded to the OSS path that you specify. `adb`: keyframes are uploaded to AnalyticDB for MySQL internal temporary storage and can be downloaded by HTTP URL.
frame_store_path	string	No	None	The OSS directory where keyframes are saved, in the format `oss://bucket/store/path`. Required only when frame_store_mode is set to `user`.

Sample requests

Basic request with default settings

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"
  }'

Custom model configuration

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": "Analyze the events in the video, identifying human behavior and scene changes.",
    "embedding_dim": 1024
  }'

Custom video processing parameters

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": "Analyze the events in the video, identifying human behavior and scene changes.",
    "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"
  }'

Response parameters

Parameter	Type	Description
status	string	The submission status. Valid values: `SUCCESS` and `FAILED`.
task_id	string	The task ID, used for querying task results.
message	string	The error message. Returned only when submission fails.

Sample responses

Submission succeeded

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

Submission failed

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

Operation 2: Query task results

Request definition

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

Sample request

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

Response parameters

Parameter	Type	Description
task_status	string	The task status. Valid values: `NEW`, `PROCESSING`, `SUCCESS`, and `FAILED`.
video_uri	string	The OSS path of the processed video.
message	string	The error message. Returned only when the task fails.
data	array	The array of event extraction results. Returned only when the task succeeds.
data[].index	int	The event segment index, starting from 1.
data[].content	string	The semantic description of the event.
data[].embedding	array[float]	The vector embedding of the event content.
data[].start_time	float	The event start time, in milliseconds.
data[].end_time	float	The event end time, in milliseconds.
data[].usage	array[object]	Token usage by model. Each object contains model_name, input_tokens, and output_tokens.
data[].frame_path	string	The OSS path of the keyframe ZIP archive. Returned only when frame_store_mode is set to `user`.
data[].frame_vpc_url	string	The temporary signed URL of the keyframe ZIP archive. Returned only when frame_store_mode is set to `adb`.

Sample responses

Task in progress

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

Task succeeded

{
  "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": "A person enters the room wearing a blue jacket and pushes the door open.",
      "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": "The person walks around the living room and inspects the surroundings.",
      "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 failed

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