SearchMedia-阿里云帮助中心

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: uploading. UploadFail: upload failed. UploadSucc: upload complete. Transcoding: transcoding. TranscodeFail: transcoding failed. Blocked: blocked. Normal: normal.	UploadSucc
CreationTime	string	The time when the video information was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format (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 modified. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).	2018-07-19T03:48:25Z
MediaSource	string	The source. Valid values: general: ApsaraVideo VOD upload. short_video: the short video SDK. editing: online editing. live: live 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 enabled. Valid values: on (enabled): the initial state. Offline download is allowed. off (disabled): offline download is disabled.	on
CateName	string	The category name.	video1
TranscodeMode	string	The transcoding mode. Valid values: FastTranscode (standard transcoding): the default mode. Transcoding starts after the upload is complete, and the video can be played only after transcoding is complete. NoTranscode (distribution without transcoding): the video can be played immediately after the upload is complete without transcoding. AsyncTranscode (distribution and transcoding upon upload): the video can be played immediately after the upload is complete, and transcoding is performed asynchronously.	FastTranscode
PreprocessStatus	string	The preprocessing status. Valid values: UnPreprocess: not preprocessed. Preprocessing: preprocessing. PreprocessSucceed: preprocessing complete. PreprocessFailed: preprocessing failed.	Preprocessing
RestoreExpiration	string	The expiration time of the media asset restoration.	2023-03-30T10:14:14Z
RestoreStatus	string	The media asset restoration status. Valid values: Processing: restoring. Success: restoration successful. Failed: restoration failed.	Success
StorageClass	string	The storage class of the media asset. Valid values: Standard: standard. IA: Infrequent Access (media asset). Archive: Archive (media asset). ColdArchive: Cold Archive (media asset). SourceIA: Infrequent Access (source file). SourceArchive: Archive (source file). SourceColdArchive: Cold Archive (source file). Changing: the storage class of the media asset 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 automatic snapshots.
	string	The list of automatic snapshots.	{“http://example.aliyundoc.com/image03.jpg”}
ReferenceId	string	The custom ID. Only lowercase letters, uppercase letters, digits, hyphens, and underscores are supported. The value must be 6 to 64 characters in length and is unique at the user level.	123-123
Audio	object	Audio information.
Status	string	The status. Valid values: Uploading: uploading. Normal: normal. UploadFail: upload failed. Deleted: deleted.	Normal
CreationTime	string	The creation time. The time is in the yyyy-MM-ddTHH:mm:ssZ format (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 last modification time. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).	2018-07-19T03:48:25Z
MediaSource	string	The source. Valid values: general (ApsaraVideo VOD upload): standard upload. short_video (the short video SDK): files uploaded to ApsaraVideo VOD by using the short video SDK. For more information, see Short video SDK. editing (online editing): files uploaded to ApsaraVideo VOD by using online editing. For more information, see Produce videos. live (live recording): files uploaded to ApsaraVideo VOD through live recording.	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 enabled. Valid values: on (enabled): the initial state. Offline download is allowed. off (disabled): offline download is disabled.	on
CateName	string	The category name.	cate1
TranscodeMode	string	The transcoding mode. Valid values: FastTranscode (standard transcoding, default): transcoding starts after the upload is complete, and the audio can be played only after transcoding is complete. NoTranscode (distribution without transcoding): the audio can be played immediately after the upload is complete without transcoding. AsyncTranscode (distribution and transcoding upon upload): the audio can be played immediately after the upload is complete, and transcoding is performed asynchronously.	FastTranscode
PreprocessStatus	string	The preprocessing status. Only preprocessed videos can be used for live streaming. Valid values: UnPreprocess: not preprocessed. Preprocessing: preprocessing. PreprocessSucceed: preprocessing complete. PreprocessFailed: preprocessing failed.	UnPreprocess
RestoreExpiration	string	The expiration time of the media asset restoration.	2023-03-30T10:14:14Z
RestoreStatus	string	The media asset restoration status. Valid values: Processing: restoring. Success: restoration successful. Failed: restoration failed.	Success
StorageClass	string	The storage class of the media asset. Valid values: Standard: standard. IA: Infrequent Access (media asset). Archive: Archive (media asset). ColdArchive: Cold Archive (media asset). SourceIA: Infrequent Access (source file). SourceArchive: Archive (source file). SourceColdArchive: Cold Archive (source file). 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 automatic snapshots.
	string	The list of automatic snapshots.	{“http://example.aliyundoc.com/image03.jpg”}
ReferenceId	string	The custom ID. Only lowercase letters, uppercase letters, digits, hyphens, and underscores are supported. The value must be 6 to 64 characters in length and is unique at the user level.	123-123
Image	object	Image information.
StorageLocation	string	The storage region.	outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
CreationTime	string	The creation time. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).	2018-07-19T03:45:25Z
Status	string	The image status. Valid values: Uploading (uploading): the initial state. The image is being uploaded. Normal (normal): the image is uploaded. UploadFail (failed): the image failed to be uploaded.	Uploading
CateId	integer	The category ID.	1000123
Tags	string	The tags.	tag1
ModificationTime	string	The last modification time. The time is in the yyyy-MM-ddTHH:mm:ssZ format (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 creation time. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).	2018-07-19T03:45:25Z
Status	string	The status. Valid values: Uploading (uploading): the initial state. The auxiliary media asset is being uploaded. Normal (normal): the auxiliary media asset is uploaded. UploadFail (failed): 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 last modification time. The time is in the yyyy-MM-ddTHH:mm:ssZ format (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 auxiliary media asset URL.	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.