Query VOD Media Assets at Scale with SearchMedia API - ApsaraVideo VOD - Alibaba Cloud - ApsaraVideo VOD

Searches for media asset information such as videos, audio files, and images produced by ApsaraVideo VOD. You can use this operation with the media asset search protocol to perform multi-dimensional searches in ApsaraVideo VOD, including specifying return fields, exact matching, fuzzy matching, multi-value queries, range queries, and sort fields.

Operation description

For fields that support exact matching and fuzzy matching, when other query methods are used, the returned results follow the query method supported by the field. For example, if a field supports only fuzzy matching, results obtained through multi-value queries are also based on fuzzy matching.

The following describes the limits on the number of data records that can be retrieved:

Method 1: Paged traversal

For matched search results, you can set the pagination parameters PageNo (page number) and PageSize (number of records per page) to traverse up to 5,000 records. If the search results exceed 5,000 records, adjust the search conditions to narrow the result range. This method cannot traverse the complete dataset. To traverse more data, refer to Method 2.
Method 2: Full traversal (for audio and video searches only)

This method applies to video and audio content searches and supports traversing up to 2 million search results. If the number of search results exceeds 2 million, add more filter conditions to reduce the result count. When using this method, in addition to PageNo and PageSize, you must use the ScrollToken parameter for pagination. Each request supports traversing up to 100 records forward. Using a PageSize of 20 as an example, the pagination logic is as follows:
- If PageNo is 1, you can query up to the next 5 pages of data.
- If PageNo is 2, you can query up to the next 6 pages of data.

Set pagination parameters properly and choose the appropriate traversal method based on the result set size. If you need to page through more than 1,000 records, use Method 2 for faster and more convenient data processing.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

vod:SearchMedia

list

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
SearchType	string	No	The type of media asset to search. Valid values: video (default): video. audio: audio. image: image. attached: auxiliary media asset. Note If this parameter is set to video or audio and you need to traverse all data that matches the search conditions, you must set the ScrollToken parameter.	video
Fields	string	No	The media asset fields to return in the search results. By default, only basic media asset fields are returned. You can specify additional media asset fields to return. For more information, see Usage examples.	Title,CoverURL
Match	string	No	The filter conditions. For syntax rules, see Search protocol syntax.	field = value
SortBy	string	No	The sort field and sort order. Separate multiple values with commas (,). Valid values: CreationTime:Desc (default): sorts by creation time in descending order. CreationTime:Asc: sorts by creation time in ascending order. Note For sort field examples, see Sort fields. When retrieving the first 5,000 records of search results, up to three sort fields are supported. When retrieving all data that matches the search conditions, only one sort field is supported.	CreationTime:Desc
PageNo	integer	No	The page number. Default value: 1. Note If this parameter exceeds 200, set the ScrollToken parameter as well.	1
PageSize	integer	No	The number of records per page. Default value: 10. Maximum value: 100.	10
ScrollToken	string	No	The pagination token. The value is a 32-character string. You do not need to set this parameter for the first search request. When the search request matches data, the server returns this parameter value, which records the current position of the search data. Record the returned value and set this parameter in the next search request based on the following requirements or recommendations: If SearchType is set to video or audio and you need to traverse all data that matches the search conditions, this parameter is required. If PageNo exceeds 200, set this parameter to optimize search performance.	24e0fba7188fae707e146esa54****

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	3E0CEF83-FB09-4E34-BA1451814B03****
Total	integer	The total number of media assets that match the search conditions.	10
ScrollToken	string	The pagination token.	24e0fba7188fae707e146esa54****
MediaList	array<object>	The list of media asset information.
	array<object>	The details of the media asset.
CreationTime	string	The time when the media asset was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).	2018-07-19T03:45:25Z
MediaType	string	The media type. Valid values: video: video. audio: audio. image: image. attached: auxiliary media asset.	video
MediaId	string	The media ID.	a82a2cd7d4e147bbed6c1ee372****
Video	object	Video information.
Status	string	The status. Valid values: Uploading: The video is being uploaded. UploadFail: The video failed to be uploaded. UploadSucc: The video was uploaded. Transcoding: The video is being transcoded. TranscodeFail: The video failed to be transcoded. Blocked: The video is blocked. Normal: The video is in a normal state.	UploadSucc
CreationTime	string	The time when the video information was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.	2018-07-19T03:45:25Z
StorageLocation	string	The storage region.	outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
CateId	integer	The category ID.	10000123
Tags	string	The video tags.	tag1
ModificationTime	string	The time when the video information was last updated. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.	2018-07-19T03:48:25Z
MediaSource	string	The source. Valid values: general: VOD upload. short_video: Short video SDK. editing: Video editing and production. live: Live stream recording.	general
Description	string	The video description.	Alibaba Cloud VOD video description
AppId	string	The application ID.	app-****
CoverURL	string	The thumbnail URL.	https://example.aliyundoc.com/image01.png
VideoId	string	The video ID.	a82a2asdasqadaf3faa0ed6c1ee372****
DownloadSwitch	string	The download switch. Offline download is allowed only when the switch is turned on. Valid values: on: The initial state. Offline download is allowed. off: Offline download is disabled.	on
CateName	string	The category name.	video1
TranscodeMode	string	The transcoding mode. Valid values: FastTranscode (Normal transcoding): The default mode. Transcoding starts immediately after the upload is complete. Playback is available after transcoding is complete. NoTranscode (Distribute without transcoding): No transcoding is performed after the upload is complete. Playback is available immediately. AsyncTranscode (Distribute upon upload and transcode asynchronously): Playback is available immediately after the upload is complete. Transcoding is performed asynchronously.	FastTranscode
PreprocessStatus	string	The pre-processing status. Valid values: UnPreprocess: Not pre-processed. Preprocessing: Pre-processing. PreprocessSucceed: Pre-processing succeeded. PreprocessFailed: Pre-processing failed.	Preprocessing
RestoreExpiration	string	The expiration time of the restored media asset.	2023-03-30T10:14:14Z
RestoreStatus	string	The restored state of the media asset. Valid values: Processing: Restoring. Success: Restored. Failed: Restoration failed.	Success
StorageClass	string	The storage class of the media asset. Valid values: Standard: Standard. IA: Infrequent Access (IA). Archive: Archive. ColdArchive: Cold Archive. SourceIA: Source IA. SourceArchive: Source Archive. SourceColdArchive: Source Cold Archive. Changing: The storage class is being changed. SourceChanging: The storage class of the source file is being changed.	Standard
Size	integer	The video size.	123
Duration	number	The video duration. Unit: seconds.	123
Title	string	The video title.	Alibaba Cloud VOD Video Title
SpriteSnapshots	array	The list of sprites.
	string	The list of sprites.	{“http://example.aliyundoc.com/image02.jpg”}
Snapshots	array	The list of automatically captured snapshots.
	string	The list of automatically captured snapshots.	{“http://example.aliyundoc.com/image03.jpg”}
ReferenceId	string	The custom ID. It can contain lowercase letters, uppercase letters, digits, hyphens (-), and underscores (_). The ID must be 6 to 64 characters in length and unique for each user.	123-123
Audio	object	Audio information.
Status	string	The status. Valid values: Uploading: The audio is being uploaded. Normal: The audio is in a normal state. UploadFail: The audio failed to be uploaded. Deleted: The audio is deleted.	Normal
CreationTime	string	The time when the audio was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.	2018-07-19T03:45:25Z
StorageLocation	string	The storage region.	outin-aaa*****aa.oss-cn-shanghai.aliyuncs.com
CateId	integer	The category ID.	10000123
Tags	string	The tags.	tag1,tag2
ModificationTime	string	The time when the audio was last updated. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.	2018-07-19T03:48:25Z
MediaSource	string	The source. Valid values: general (VOD upload): The file is uploaded using a normal method. short_video (Short video SDK): The file is uploaded to VOD using a short video SDK. For more information, see Short video SDK. editing (Online editing): The file is uploaded to VOD after it is synthesized using online editing. For more information, see Video synthesis. live (Live stream recording): The file is uploaded to VOD after it is recorded from a live stream.	general
Description	string	The description.	Alibaba Cloud VOD Audio Description
AppId	string	The application ID.	app-****
CoverURL	string	The thumbnail URL.	http://example.com/image04.jpg
AudioId	string	The audio ID.	a82a2cd7d4e147bbed6c1ee372****
DownloadSwitch	string	The download switch. Offline download is allowed only when the switch is turned on. Valid values: on: The initial state. Offline download is allowed. off: Offline download is disabled.	on
CateName	string	The category name.	cate1
TranscodeMode	string	The transcoding mode. Valid values: FastTranscode (Normal transcoding, default): Transcoding starts immediately after the upload is complete. Playback is available after transcoding is complete. NoTranscode (Distribute without transcoding): No transcoding is performed after the upload is complete. Playback is available immediately. AsyncTranscode (Distribute upon upload and transcode asynchronously): Playback is available immediately after the upload is complete. Transcoding is performed asynchronously.	FastTranscode
PreprocessStatus	string	The pre-processing status. Only pre-processed audio files can be used for live stream directing. Valid values: UnPreprocess: Not pre-processed. Preprocessing: Pre-processing. PreprocessSucceed: Pre-processing succeeded. PreprocessFailed: Pre-processing failed.	UnPreprocess
RestoreExpiration	string	The expiration time of the restored media asset.	2023-03-30T10:14:14Z
RestoreStatus	string	The restored state of the media asset. Valid values: Processing: Restoring. Success: Restored. Failed: Restoration failed.	Success
StorageClass	string	The storage class of the media asset. Valid values: Standard: Standard. IA: IA. Archive: Archive. ColdArchive: Cold Archive. SourceIA: Source IA. SourceArchive: Source Archive. SourceColdArchive: Source Cold Archive. Changing: The storage class is being changed.	Standard
Size	integer	The size.	123
Duration	number	The duration.	123
Title	string	The title.	Alibaba Cloud VOD Audio Title
SpriteSnapshots	array	The list of sprites.
	string	The list of sprites.	{“http://example.aliyundoc.com/image02.jpg”}
Snapshots	array	The list of automatically captured snapshots.
	string	The list of automatically captured snapshots.	{“http://example.aliyundoc.com/image03.jpg”}
ReferenceId	string	The custom ID. It can contain lowercase letters, uppercase letters, digits, hyphens (-), and underscores (_). The ID must be 6 to 64 characters in length and unique for each user.	123-123
Image	object	Image information.
StorageLocation	string	The storage region.	outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
CreationTime	string	The time when the image was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.	2018-07-19T03:45:25Z
Status	string	The image status. Uploading: The initial state. The image is being uploaded. Normal: The image was uploaded. UploadFail: The image failed to be uploaded.	Uploading
CateId	integer	The category ID.	1000123
Tags	string	The tags.	tag1
ModificationTime	string	The time when the image was last updated. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.	2018-07-19T03:48:25Z
CateName	string	The category name.	cate1
Description	string	The description.	Alibaba Cloud VOD Image Description
AppId	string	The application ID.	app-****
URL	string	The image URL.	https://example.com/****.png
Title	string	The title.	Alibaba Cloud VOD Image Title
ImageId	string	The image ID.	11130843741se99wqmoes****
AttachedMedia	object	Auxiliary media asset information.
CreationTime	string	The time when the asset was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.	2018-07-19T03:45:25Z
Status	string	The status. Valid values: Uploading: The initial state. The auxiliary media asset is being uploaded. Normal: The auxiliary media asset was uploaded. UploadFail: The auxiliary media asset failed to be uploaded.	Normal
StorageLocation	string	The storage region.	outin-bfefbb90a47c11*****7426.oss-cn-shanghai.aliyuncs.com
Tags	string	The tags.	tag1
ModificationTime	string	The time when the asset was last updated. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.	2018-07-19T03:48:25Z
MediaId	string	The auxiliary media asset ID.	a82a2cd7d4e147ba0ed6c1ee372****
BusinessType	string	The business type. Valid values: watermark: watermark. subtitle: subtitle. material: material.	watermark
Description	string	The description.	Alibaba Cloud VOD-assisted media asset description
AppId	string	The application ID.	app-****
URL	string	The URL of the auxiliary media asset.	https://example.com/****.png
Title	string	The title.	Alibaba Cloud VOD-assisted media asset Title
Categories	array<object>	The list of category IDs.
	object	The category details.
ParentId	integer	The parent node ID.	-1
CateName	string	The category name.	cate1
CateId	integer	The category ID.	10027394
Level	integer	The category level.	1
AiData		The AI details.
AiRoughData		The AI summary data.

Examples

Success response

JSON format

{
  "RequestId": "3E0CEF83-FB09-4E34-BA1451814B03****",
  "Total": 10,
  "ScrollToken": "24e0fba7188fae707e146esa54****",
  "MediaList": [
    {
      "CreationTime": "2018-07-19T03:45:25Z",
      "MediaType": "video",
      "MediaId": "a82a2cd7d4e147bbed6c1ee372****",
      "Video": {
        "Status": "UploadSucc",
        "CreationTime": "2018-07-19T03:45:25Z",
        "StorageLocation": "outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com",
        "CateId": 10000123,
        "Tags": "tag1",
        "ModificationTime": "2018-07-19T03:48:25Z",
        "MediaSource": "general",
        "Description": "Alibaba Cloud VOD video description",
        "AppId": "app-****",
        "CoverURL": "https://example.aliyundoc.com/image01.png",
        "VideoId": "a82a2asdasqadaf3faa0ed6c1ee372****",
        "DownloadSwitch": "on",
        "CateName": "video1",
        "TranscodeMode": "FastTranscode",
        "PreprocessStatus": "Preprocessing",
        "RestoreExpiration": "2023-03-30T10:14:14Z",
        "RestoreStatus": "Success",
        "StorageClass": "Standard",
        "Size": 123,
        "Duration": 123,
        "Title": "Alibaba Cloud VOD Video Title",
        "SpriteSnapshots": [
          "{“http://example.aliyundoc.com/image02.jpg”}"
        ],
        "Snapshots": [
          "{“http://example.aliyundoc.com/image03.jpg”}"
        ],
        "ReferenceId": "123-123"
      },
      "Audio": {
        "Status": "Normal",
        "CreationTime": "2018-07-19T03:45:25Z",
        "StorageLocation": "outin-aaa*****aa.oss-cn-shanghai.aliyuncs.com",
        "CateId": 10000123,
        "Tags": "tag1,tag2",
        "ModificationTime": "2018-07-19T03:48:25Z",
        "MediaSource": "general",
        "Description": "Alibaba Cloud VOD Audio Description",
        "AppId": "app-****",
        "CoverURL": "http://example.com/image04.jpg",
        "AudioId": "a82a2cd7d4e147bbed6c1ee372****",
        "DownloadSwitch": "on",
        "CateName": "cate1",
        "TranscodeMode": "FastTranscode",
        "PreprocessStatus": "UnPreprocess",
        "RestoreExpiration": "2023-03-30T10:14:14Z",
        "RestoreStatus": "Success",
        "StorageClass": "Standard",
        "Size": 123,
        "Duration": 123,
        "Title": "Alibaba Cloud VOD Audio Title",
        "SpriteSnapshots": [
          "{“http://example.aliyundoc.com/image02.jpg”}"
        ],
        "Snapshots": [
          "{“http://example.aliyundoc.com/image03.jpg”}"
        ],
        "ReferenceId": "123-123"
      },
      "Image": {
        "StorageLocation": "outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com",
        "CreationTime": "2018-07-19T03:45:25Z",
        "Status": "Uploading",
        "CateId": 1000123,
        "Tags": "tag1",
        "ModificationTime": "2018-07-19T03:48:25Z",
        "CateName": "cate1",
        "Description": "Alibaba Cloud VOD Image Description",
        "AppId": "app-****",
        "URL": "https://example.com/****.png",
        "Title": "Alibaba Cloud VOD Image Title",
        "ImageId": "11130843741se99wqmoes****"
      },
      "AttachedMedia": {
        "CreationTime": "2018-07-19T03:45:25Z",
        "Status": "Normal",
        "StorageLocation": "outin-bfefbb90a47c11*****7426.oss-cn-shanghai.aliyuncs.com",
        "Tags": "tag1",
        "ModificationTime": "2018-07-19T03:48:25Z",
        "MediaId": "a82a2cd7d4e147ba0ed6c1ee372****",
        "BusinessType": "watermark",
        "Description": "Alibaba Cloud VOD-assisted media asset description",
        "AppId": "app-****",
        "URL": "https://example.com/****.png",
        "Title": "Alibaba Cloud VOD-assisted media asset Title",
        "Categories": [
          {
            "ParentId": -1,
            "CateName": "cate1",
            "CateId": 10027394,
            "Level": 1
          }
        ]
      }
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.