SearchMedia - ApsaraVideo VOD - Alibaba Cloud Documentation Center

This operation searches for media assets in ApsaraVideo VOD, such as videos, audio, and images. You can call this operation and use the media search protocol to perform multi-dimensional searches. You can specify the fields to return, perform exact matches, fuzzy queries, multi-value queries, and range queries, and specify the fields for sorting.

Operation description

For fields that support both exact match and fuzzy query, the results for other query types are based on the supported query method. For example, if a field supports only fuzzy query, a multi-value query on that field also returns results based on a fuzzy match.

The limits on the number of search results that you can retrieve are as follows:

Method 1: Paging

You can traverse up to 5,000 search results by setting the PageNo (page number) and PageSize (number of records per page) parameters. If the number of search results exceeds 5,000, you must adjust the search conditions to narrow the result set. Note that this method cannot traverse the entire dataset. To traverse more data, see Method 2.
Method 2: Full traversal (for audio and video search only)

This method applies only to audio and video searches and supports traversing all search results, up to a maximum of 2 million records. If the number of search results exceeds 2 million, you must add more filter conditions to reduce the result set. When you use this method, you must use the ScrollToken parameter in addition to the PageNo and PageSize parameters for paging. Note that you can traverse a maximum of 100 records backward at a time. The following example shows the paging logic when PageSize is set to 20:
- 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.

You must set the paging parameters properly for your search and select the appropriate traversal method based on the size of the result set. 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 the media asset to search for. 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 meets the search criteria, 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 more fields to return. For more information, see Examples.	Title,CoverURL
Match	string	No	The filter condition. For more information about the syntax, see Search protocol syntax.	field = value
SortBy	string	No	The sorting field and 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 more information about sorting fields, see Sorting fields. When you retrieve the first 5,000 data records that meet the search criteria, you can specify up to three sorting fields. When you retrieve all data that meets the search criteria, you can specify only one sorting field.	CreationTime:Desc
PageNo	integer	No	The page number. The default value is 1. Note If the value of this parameter exceeds 200, we recommend that you also set the ScrollToken parameter.	1
PageSize	integer	No	The number of data records to return on each page. The default value is 10. The maximum value is 100.	10
ScrollToken	string	No	The pagination token. It is a 32-character string. You do not need to set this parameter for the first search request. The server-side returns this parameter to mark the current position in the search results. Record the returned value. For the next search, set this parameter as required or recommended: If the SearchType parameter is set to video or audio and you need to traverse all data that meets the search criteria, you must set this parameter. If the value of the PageNo parameter exceeds 200, we recommend that you set this parameter to optimize search performance.	24e0fba7188fae707e146esa54****

Response elements

Element	Type	Description	Example
	object	The response.
RequestId	string	The request ID.	3E0CEF83-FB09-4E34-BA1451814B03****
Total	integer	The total number of media assets that meet the search criteria.	10
ScrollToken	string	The pagination token.	24e0fba7188fae707e146esa54****
MediaList	array<object>	The list of media assets.
	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 in UTC.	2018-07-19T03:45:25Z
MediaType	string	The type of the media asset. Valid values: video: video. audio: audio. image: image. attached: auxiliary media asset.	video
MediaId	string	The ID of the media asset.	a82a2cd7d4e147bbed6c1ee372****
Video	object	The 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	The 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	The 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	The 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

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.