Queries the information about media assets such as video, audio, and image files, and auxiliary media assets.

Description

The maximum number of data records that you can query is limited based on the method used to query the data. You can use the following methods to query data:

  • Method 1: You must use the PageNo and PageSize parameters for the first 5,000 data records that meet the specified filter criteria. This allows you to traverse data page by page. If the number of data records that meet the specified filter criteria exceeds 5,000, use Method 2.
  • Method 2: This method applies only to the data of video and audio files. To traverse all the data records that meet the specified filter criteria, you must set the PageNo, PageSize, and ScrollToken parameters to traverse data page by page. The total number of data records from the current page to the desired page cannot exceed 1,200. Assume that the PageSize parameter is set to 20:
    • When the PageNo parameter is set to 1, you can scroll forward to traverse data records from page 1 to page 60 at most.
    • When the PageNo parameter is set to 2, you can scroll forward to traverse data records from page 2 to page 61 at most.
    • When the PageNo parameter is set to 61, you can scroll backward to traverse data records from page 61 to page 2 at most or scroll forward to traverse data records from page 61 to page 120 at most.

QPS limit

You can call this operation up to 50 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limits on API operations in ApsaraVideo VOD.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes SearchMedia

The operation that you want to perform. Set the value to SearchMedia.

SearchType String No video

The type of the media asset that you want to query. Default value: video. Valid values:

  • video
  • audio
  • image
  • attached
Note If this parameter is set to video or audio and you want to traverse all data that meets the filter criteria, you must set the ScrollToken parameter.
Fields String No Title,CoverURL

The media asset fields to return in the query results.

By default, only the basic media asset fields are returned. You can specify additional media asset fields that need to be returned in the request. For more information, see the "API examples" section of the Search for media asset information topic.

Match String No field = value

The filter condition. For more information about the syntax, see Protocol for media asset search.

SortBy String No CreationTime:Desc

The sort field and order. Separate multiple values with commas (,). Default value: CreationTime:Desc. Valid values:

  • CreationTime:Desc: The results are sorted in reverse chronological order based on the creation time.
  • CreationTime:Asc: The results are sorted in chronological order based on the creation time.
Note
  • For more information about the sort field, see "Sort field" in the Search for media asset information topic.
  • To obtain the first 5,000 data records that meet the specified filter criteria, you can specify a maximum of three sort fields.
  • To obtain all the data records that meet the specified filter criteria, you can specify only one sort field.
PageNo Integer No 1

The number of the page to return. Default value: 1.

Note If the value of this parameter exceeds 200, we recommend that you set the ScrollToken parameter as well.
PageSize Integer No 10

The number of entries to return on each page. Default value: 10. Maximum value: 100.

ScrollToken String No 24e0fba7188fae707e146esa54****

The pagination identifier. The identifier can be up to 32 characters in length.

The first time you call this operation for each new search, you do not need to specify this parameter. The value of this parameter is returned each time data records that meet the specified filter criteria are found. The value is used to record the current position of queried data. Record the returned parameter value and set this parameter according to the following requirements during the next search:

  • If SearchType is set to video or audio and you need to traverse all data that meets the filter criteria, you must set the ScrollToken parameter.
  • If the value of the PageNo parameter exceeds 200, we recommend that you set this parameter to optimize search performance.

Response parameters

Parameter Type Example Description
RequestId String 3E0CEF83-FB09-4E34-BA1451814B03****

The ID of the request.

Total Long 10

The total number of data records that meet the specified filter criteria.

ScrollToken String 24e0fba7188fae707e146esa54****

The pagination identifier.

MediaList Array of Media

Details about media assets.

CreationTime String 2018-07-19T03:45:25Z

The time when the media asset was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

MediaType String video

The type of the media asset. Valid values:

  • video
  • audio
  • image
  • attached
MediaId String a82a2cd7d4e147bbed6c1ee372****

The ID of the media asset.

Video Object

Details about video files.

Status String UploadSucc

The status of the video file. Valid values:

  • Uploading
  • UploadFail
  • UploadSucc
  • Transcoding
  • TranscodeFail
  • Blocked
  • Normal
CreationTime String 2018-07-19T03:45:25Z

The time when the video file was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

StorageLocation String outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com

The endpoint of the OSS bucket in which the video file is stored.

CateId Long 10000123

The category ID of the video file.

Tags String tag1

The tags of the video file.

ModificationTime String 2018-07-19T03:48:25Z

The time when the video file was updated. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

MediaSource String general

The source. Valid values:

  • general: The video file is uploaded by using ApsaraVideo VOD.
  • short_video: The video file is uploaded by using the short video SDK.
  • editing: The video file is produced after online editing.
  • live: The video stream is recorded and uploaded as a file.
Description String Video test

The description of the video file.

AppId String app-****

The ID of the application.

CoverURL String https://example.aliyundoc.com/image01.png

The URL of the thumbnail.

VideoId String a82a2asdasqadaf3faa0ed6c1ee372****

The ID of the video file.

DownloadSwitch String on

The download switch. The video file can be downloaded offline only when the download switch is turned on. Valid values:

  • on
  • off
CateName String video1

The name of the category.

TranscodeMode String FastTranscode

The transcoding mode. Default value: FastTranscode. Valid values:

  • FastTranscode: The video file is immediately transcoded after it is uploaded. You cannot play the file before it is transcoded.
  • NoTranscode: The video file can be played without being transcoded. You can immediately play the file after it is uploaded.
  • AsyncTranscode: The video file can be immediately played and asynchronously transcoded after it is uploaded.
PreprocessStatus String Preprocessing

The preprocessing status. Valid values:

  • UnPreprocess
  • Preprocessing
  • PreprocessSucceed
  • PreprocessFailed
Size Long 123

The size of the video file.

Duration Float 123

The duration of the video file. Unit: seconds.

Title String ceshi

The title of the video file.

SpriteSnapshots Array of String {"http://example.aliyundoc.com/image02.jpg"}

The list of sprite snapshots.

Snapshots Array of String {"http://example.aliyundoc.com/image03.jpg"}

The list of automatic snapshots.

Audio Object

Details about audio files.

Status String Normal

The status of the audio file. Valid values:

  • Uploading
  • Normal
  • UploadFail
  • Deleted
CreationTime String 2018-07-19T03:45:25Z

The time when the audio file was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

StorageLocation String outin-aaa*****aa.oss-cn-shanghai.aliyuncs.com

The endpoint of the OSS bucket in which the audio file is stored.

CateId Long 10000123

The category ID of the audio file.

Tags String tag1,tag2

The tags of the audio file.

ModificationTime String 2018-07-19T03:48:25Z

The time when the audio file was updated. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

MediaSource String general

The source. Valid values:

  • general: The audio file is uploaded by using ApsaraVideo VOD.
  • short_video: The audio file is uploaded to ApsaraVideo VOD by using the short video SDK. For more information, see Introduction.
  • editing: The audio file is uploaded to ApsaraVideo VOD after online editing and production. For more information, see ProduceEditingProjectVideo.
  • live: The audio stream is recorded and uploaded as a file to ApsaraVideo VOD.
Description String Audio description

The description of the audio file.

AppId String app-****

The ID of the application.

CoverURL String http://example.com/image04.jpg

The URL of the thumbnail.

AudioId String a82a2cd7d4e147bbed6c1ee372****

The ID of the audio file.

DownloadSwitch String on

The download switch. The audio file can be downloaded offline only when the download switch is turned on. Valid values:

  • on
  • off
CateName String ceshi

The name of the category.

TranscodeMode String FastTranscode

The transcoding mode. Default value: FastTranscode. Valid values:

  • FastTranscode: The audio file is immediately transcoded after it is uploaded. You cannot play the file before it is transcoded.
  • NoTranscode: The audio file can be played without being transcoded. You can immediately play the file after it is uploaded.
  • AsyncTranscode: The audio file can be immediately played and asynchronously transcoded after it is uploaded.
PreprocessStatus String UnPreprocess

The preprocessing status. Only preprocessed videos can be used for live streaming in the production studio. Valid values:

  • UnPreprocess
  • Preprocessing
  • PreprocessSucceed
  • PreprocessFailed
Size Long 123

The size of the audio file.

Duration Float 123

The duration of the audio file.

Title String Audio

The title of the audio file.

SpriteSnapshots Array of String {"http://example.aliyundoc.com/image02.jpg"}

The list of sprite snapshots.

Snapshots Array of String {"http://example.aliyundoc.com/image03.jpg"}

The list of automatic snapshots.

Image Object

Details about image files.

StorageLocation String outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com

The endpoint of the OSS bucket in which the image file is stored.

CreationTime String 2018-07-19T03:45:25Z

The time when the image file was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Status String Uploading

The status of the image file.

  • Uploading: The image file is being uploaded. This is the initial status.
  • Normal: The image file is uploaded.
  • UploadFail: The image file fails to be uploaded.
CateId Long 1000123

The category ID of the image file.

Tags String tag1

The tags of the image file.

ModificationTime String 2018-07-19T03:48:25Z

The time when the image file was updated. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

CateName String Beautification image 1

The name of the category.

Description String Image test

The description of the image file.

AppId String app-****

The ID of the application.

URL String https://example.com/****.png

The URL of the image file.

Title String image1

The title of the image file.

ImageId String 11130843741se99wqmoes****

The ID of the image file.

AttachedMedia Object

Details about auxiliary media assets.

CreationTime String 2018-07-19T03:45:25Z

The time when the auxiliary media asset was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Status String Normal

The status of the auxiliary media asset. Valid values:

  • Uploading: The auxiliary media asset is being uploaded. This is the initial status.
  • Normal: The auxiliary media asset is uploaded.
  • UploadFail: The auxiliary media asset fails to be uploaded.
StorageLocation String outin-bfefbb90a47c11*****7426.oss-cn-shanghai.aliyuncs.com

The endpoint of the OSS bucket in which the auxiliary media asset is stored.

Tags String Test

The tags of the auxiliary media asset.

ModificationTime String 2018-07-19T03:48:25Z

The time when the auxiliary media asset was updated. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

MediaId String a82a2cd7d4e147ba0ed6c1ee372****

The ID of the auxiliary media asset.

BusinessType String watermark

The type of the auxiliary media asset. Valid values:

  • watermark
  • subtitle
  • material
Description String Test

The description of the auxiliary media asset.

AppId String app-****

The ID of the application.

URL String https://example.com/****.png

The URL of the auxiliary media asset.

Title String Test

The title of the auxiliary media asset.

Categories Array of Category

The list of category IDs.

ParentId Long -1

The ID of the parent category.

CateName String Test

The name of the category.

CateId Long 10027394

The category ID of the auxiliary media asset.

Level Long 1

The level of the category.

Examples

Sample requests

http(s)://vod.cn-shanghai.aliyuncs.com/?Action=SearchMedia
&SearchType=video
&Fields=Title,CoverURL
&Match=field = value
&SortBy=CreationTime:Desc
&PageNo=1
&PageSize=10
&ScrollToken=24e0fba7188fae707e146esa54****
&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<SearchMediaResponse>
    <RequestId>3E0CEF83-FB09-4E34-BA1451814B03****</RequestId>
    <Total>10</Total>
    <ScrollToken>24e0fba7188fae707e146esa54****</ScrollToken>
    <MediaList>
        <CreationTime>2018-07-19T03:45:25Z</CreationTime>
        <MediaType>video</MediaType>
        <MediaId>a82a2cd7d4e147bbed6c1ee372****</MediaId>
        <Video>
            <Status>UploadSucc</Status>
            <CreationTime>2018-07-19T03:45:25Z</CreationTime>
            <StorageLocation>outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com</StorageLocation>
            <CateId>10000123</CateId>
            <Tags>tag1</Tags>
            <ModificationTime>2018-07-19T03:48:25Z</ModificationTime>
            <MediaSource>general</MediaSource>
            <Description>Video test</Description>
            <AppId>app-****</AppId>
            <CoverURL>https://example.aliyundoc.com/image01.png</CoverURL>
            <VideoId>a82a2asdasqadaf3faa0ed6c1ee372****</VideoId>
            <DownloadSwitch>on</DownloadSwitch>
            <CateName>video1</CateName>
            <TranscodeMode>FastTranscode</TranscodeMode>
            <PreprocessStatus>Preprocessing</PreprocessStatus>
            <Size>123</Size>
            <Duration>123</Duration>
            <Title>ceshi</Title>
            <SpriteSnapshots>{“http://example.aliyundoc.com/image02.jpg”}</SpriteSnapshots>
            <Snapshots>{“http://example.aliyundoc.com/image03.jpg”}</Snapshots>
        </Video>
        <Audio>
            <Status>Normal</Status>
            <CreationTime>2018-07-19T03:45:25Z</CreationTime>
            <StorageLocation>outin-aaa*****aa.oss-cn-shanghai.aliyuncs.com</StorageLocation>
            <CateId>10000123</CateId>
            <Tags>tag1,tag2</Tags>
            <ModificationTime>2018-07-19T03:48:25Z</ModificationTime>
            <MediaSource>general</MediaSource>
            <Description>Audio description</Description>
            <AppId>app-****</AppId>
            <CoverURL>http://example.com/image04.jpg</CoverURL>
            <AudioId>a82a2cd7d4e147bbed6c1ee372****</AudioId>
            <DownloadSwitch>on</DownloadSwitch>
            <CateName>ceshi</CateName>
            <TranscodeMode>FastTranscode</TranscodeMode>
            <PreprocessStatus>UnPreprocess</PreprocessStatus>
            <Size>123</Size>
            <Duration>123</Duration>
            <Title>Audio</Title>
            <SpriteSnapshots>{“http://example.aliyundoc.com/image02.jpg”}</SpriteSnapshots>
            <Snapshots>{“http://example.aliyundoc.com/image03.jpg”}</Snapshots>
        </Audio>
        <Image>
            <StorageLocation>outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com</StorageLocation>
            <CreationTime>2018-07-19T03:45:25Z</CreationTime>
            <Status>Uploading</Status>
            <CateId>1000123</CateId>
            <Tags>tag1</Tags>
            <ModificationTime>2018-07-19T03:48:25Z</ModificationTime>
            <CateName>Beautification image 1</CateName>
            <Description>Image test</Description>
            <AppId>app-****</AppId>
            <URL>https://example.com/****.png</URL>
            <Title>image1</Title>
            <ImageId>11130843741se99wqmoes****</ImageId>
        </Image>
        <AttachedMedia>
            <CreationTime>2018-07-19T03:45:25Z</CreationTime>
            <Status>Normal</Status>
            <StorageLocation>outin-bfefbb90a47c11*****7426.oss-cn-shanghai.aliyuncs.com</StorageLocation>
            <Tags>Test</Tags>
            <ModificationTime>2018-07-19T03:48:25Z</ModificationTime>
            <MediaId>a82a2cd7d4e147ba0ed6c1ee372****</MediaId>
            <BusinessType>watermark</BusinessType>
            <Description>Test</Description>
            <AppId>app-****</AppId>
            <URL>https://example.com/****.png</URL>
            <Title>Test</Title>
            <Categories>
                <ParentId>-1</ParentId>
                <CateName>Test</CateName>
                <CateId>10027394</CateId>
                <Level>1</Level>
            </Categories>
        </AttachedMedia>
    </MediaList>
</SearchMediaResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "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" : "Video test",
      "AppId" : "app-****",
      "CoverURL" : "https://example.aliyundoc.com/image01.png",
      "VideoId" : "a82a2asdasqadaf3faa0ed6c1ee372****",
      "DownloadSwitch" : "on",
      "CateName" : "video1",
      "TranscodeMode" : "FastTranscode",
      "PreprocessStatus" : "Preprocessing",
      "Size" : 123,
      "Duration" : 123,
      "Title" : "ceshi",
      "SpriteSnapshots" : [ "{“http://example.aliyundoc.com/image02.jpg”}" ],
      "Snapshots" : [ "{“http://example.aliyundoc.com/image03.jpg”}" ]
    },
    "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" : "Audio description",
      "AppId" : "app-****",
      "CoverURL" : "http://example.com/image04.jpg",
      "AudioId" : "a82a2cd7d4e147bbed6c1ee372****",
      "DownloadSwitch" : "on",
      "CateName" : "ceshi",
      "TranscodeMode" : "FastTranscode",
      "PreprocessStatus" : "UnPreprocess",
      "Size" : 123,
      "Duration" : 123,
      "Title" : "Audio",
      "SpriteSnapshots" : [ "{“http://example.aliyundoc.com/image02.jpg”}" ],
      "Snapshots" : [ "{“http://example.aliyundoc.com/image03.jpg”}" ]
    },
    "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" : "Beautification image 1",
      "Description" : "Image test",
      "AppId" : "app-****",
      "URL" : "https://example.com/****.png",
      "Title" : "image1",
      "ImageId" : "11130843741se99wqmoes****"
    },
    "AttachedMedia" : {
      "CreationTime" : "2018-07-19T03:45:25Z",
      "Status" : "Normal",
      "StorageLocation" : "outin-bfefbb90a47c11*****7426.oss-cn-shanghai.aliyuncs.com",
      "Tags" : "Test",
      "ModificationTime" : "2018-07-19T03:48:25Z",
      "MediaId" : "a82a2cd7d4e147ba0ed6c1ee372****",
      "BusinessType" : "watermark",
      "Description": "Test",
      "AppId" : "app-****",
      "URL" : "https://example.com/****.png",
      "Title" : "Test",
      "Categories" : [ {
        "ParentId" : -1,
        "CateName": "Test",
        "CateId" : 10027394,
        "Level" : 1
      } ]
    }
  } ]
}

Error codes

For a list of error codes, visit the API Error Center.

Common errors

The following table describes the common errors that this operation can return.

Error code

Error message

HTTP status code

Description

SortByExceededMax

The SortBy parameter only supports one sort field when traversing all data.

400

The error message returned because more than one sort field is specified to traverse all data.

ErrorMatchSyntax

The parameter Match.%s has an error syntax, please check it.

400

The error message returned because the syntax of the Match parameter is invalid. Check the syntax and try again.

InvalidScrollToken.Expired

The ScrollToken is expired, please refresh it.

400

The error message returned because the value of the ScrollToken parameter is invalid. Obtain data again from Page 1.

Sample code of SDKs for various languages

We recommend that you use a server-side SDK to call this operation. For more information about the sample code that is used to call this operation in various languages, see the following topics: