All Products
Search
Document Center

ApsaraVideo VOD:SearchMedia

Last Updated:May 22, 2024

Queries information about videos, audio, images, and auxiliary media assets. You can call this operation and specify the search protocol to query media assets based on the return fields, fields used for exact match, fields used for fuzzy match, fields used for a multi-value query, fields used for a range query, and sort fields.

Operation description

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

  • Method 1: Traverse data by page

    You can use the PageNo and PageSize parameters to traverse up to 5,000 data records that meet the specified filter condition. PageNo specifies the page number and PageSize specifies the number of data records displayed on a page. If the number of data records that meet the specified filter condition exceeds 5,000, change the filter conditions to narrow down the results. You cannot use this method to traverse all data records. If you want to traverse more data records, use Method 2.

  • Method 2: Traverse all data (available only for audio and video files)

    You can use this method to traverse up to 2 million data records related to audio and video files. If the number of data records that meet the specified filter condition exceeds 2 million, change the filter conditions to narrow down the results. To traverse data page by page, you must set the PageNo, PageSize, and ScrollToken parameters. The total number of data records from the current page to the target page cannot exceed 100. For example, you set PageSize to 20. The following content describes the traverse logic:

    • When the PageNo parameter is set to 1, you can traverse data records from page 1 to page 5.
    • When the PageNo parameter is set to 2, you can traverse data records from page 2 to page 6.

Make sure that you set the appropriate page number and page size, and use a traverse method based on the number of results that meet your filter condition.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
vod:SearchMediaList
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
SearchTypestringNo

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.
video
FieldsstringNo

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.

Title,CoverURL
MatchstringNo

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

field = value
SortBystringNo

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.
  • CreationTime:Desc
    PageNointegerNo

    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.
    1
    PageSizeintegerNo

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

    10
    ScrollTokenstringNo

    The pagination identifier. The password must be 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 condition 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.
    24e0fba7188fae707e146esa54****

    Response parameters

    ParameterTypeDescriptionExample
    object

    The returned result.

    RequestIdstring

    The ID of the request.

    3E0CEF83-FB09-4E34-BA1451814B03****
    Totallong

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

    10
    ScrollTokenstring

    The pagination identifier.

    24e0fba7188fae707e146esa54****
    MediaListobject []

    The information about the media assets.

    CreationTimestring

    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.

    2018-07-19T03:45:25Z
    MediaTypestring

    The type of the media asset. Valid values:

    • video
    • audio
    • image
    • attached
    video
    MediaIdstring

    The ID of the file.

    a82a2cd7d4e147bbed6c1ee372****
    Videoobject
    Statusstring

    The status of the file. Valid values:

    • Uploading
    • UploadFail
    • UploadSucc
    • Transcoding
    • TranscodeFail
    • Blocked
    • Normal
    UploadSucc
    CreationTimestring

    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.

    2018-07-19T03:45:25Z
    StorageLocationstring

    The region in which the video is stored.

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

    The ID of the category.

    10000123
    Tagsstring

    The tags of the video file.

    tag1
    ModificationTimestring

    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.

    2018-07-19T03:48:25Z
    MediaSourcestring

    The source of the video file. 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.
    general
    Descriptionstring

    The description of the video file.

    Video test
    AppIdstring

    The ID of the application.

    app-****
    CoverURLstring

    The URL of the thumbnail.

    https://example.aliyundoc.com/image01.png
    VideoIdstring

    The ID of the video file.

    a82a2asdasqadaf3faa0ed6c1ee372****
    DownloadSwitchstring

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

    • on
    • off
    on
    CateNamestring

    The name of the category.

    video1
    TranscodeModestring

    The transcoding mode. 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.
    FastTranscode
    PreprocessStatusstring

    The preprocessing status. Valid values:

    • UnPreprocess
    • Preprocessing
    • PreprocessSucceed
    • PreprocessFailed
    Preprocessing
    RestoreExpirationstring

    The period of time in which the video file remains in the restored state.

    2023-03-30T10:14:14Z
    RestoreStatusstring

    The restoration status of the video file. Valid values:

    • Processing
    • Success
    • Failed
    Success
    StorageClassstring

    The storage class of the video file. Valid values:

    • Standard: All media resources are stored as Standard objects.
    • IA: All media resources are stored as IA objects.
    • Archive: All media resources are stored as Archive objects.
    • ColdArchive: All media resources are stored as Cold Archive objects.
    • SourceIA: Only the source file is stored as an IA object.
    • SourceArchive: Only the source file is stored as an Archive object.
    • SourceColdArchive: Only the source file is stored as a Cold Archive object.
    • Changing: The storage class of the video file is being changed.
    • SourceChanging: The storage class of the source file is being changed.
    Standard
    Sizelong

    The size of the video file.

    123
    Durationfloat

    The duration of the video file. Unit: seconds.

    123
    Titlestring

    The title of the video.

    ceshi
    SpriteSnapshotsarray

    The sprite snapshots.

    string

    The sprite snapshot.

    {“http://example.aliyundoc.com/image02.jpg”}
    Snapshotsarray

    The automatic snapshots.

    string

    The automatic snapshot.

    {“http://example.aliyundoc.com/image03.jpg”}
    Audioobject
    Statusstring

    The status of the audio file. Valid values:

    • Uploading
    • Normal
    • UploadFail
    • Deleted
    Normal
    CreationTimestring

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

    2018-07-19T03:45:25Z
    StorageLocationstring

    The region in which the audio is stored.

    outin-aaa*****aa.oss-cn-shanghai.aliyuncs.com
    CateIdlong

    The ID of the category.

    10000123
    Tagsstring

    The tags of the audio file.

    tag1,tag2
    ModificationTimestring

    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.

    2018-07-19T03:48:25Z
    MediaSourcestring

    The source of the audio file. 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 file is recorded and uploaded as a file to ApsaraVideo VOD.
    general
    Descriptionstring

    The description of the audio file.

    audio description
    AppIdstring

    The ID of the application.

    app-****
    CoverURLstring

    The URL of the thumbnail.

    http://example.com/image04.jpg
    AudioIdstring

    The ID of the audio file.

    a82a2cd7d4e147bbed6c1ee372****
    DownloadSwitchstring

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

    • on
    • off
    on
    CateNamestring

    The name of the category.

    ceshi
    TranscodeModestring

    The transcoding mode. 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.
    FastTranscode
    PreprocessStatusstring

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

    • UnPreprocess
    • Preprocessing
    • PreprocessSucceed
    • PreprocessFailed
    UnPreprocess
    RestoreExpirationstring

    The period of time in which the audio file remains in the restored state.

    2023-03-30T10:14:14Z
    RestoreStatusstring

    The restoration status of the audio file. Valid values:

    • Processing
    • Success
    • Failed
    Success
    StorageClassstring

    The storage class of the audio file. Valid values:

    • Standard: All media resources are stored as Standard objects.
    • IA: All media resources are stored as IA objects.
    • Archive: All media resources are stored as Archive objects.
    • ColdArchive: All media resources are stored as Cold Archive objects.
    • SourceIA: Only the source file is stored as an IA object.
    • SourceArchive: Only the source file is stored as an Archive object.
    • SourceColdArchive: Only the source file is stored as a Cold Archive object.
    • Changing: The storage class is being modified.
    Standard
    Sizelong

    The size of the audio file.

    123
    Durationfloat

    The duration of the audio file.

    123
    Titlestring

    The title of the audio file

    audio
    SpriteSnapshotsarray

    The sprite snapshots.

    string

    The sprite snapshot.

    {“http://example.aliyundoc.com/image02.jpg”}
    Snapshotsarray

    The automatic snapshots.

    string

    The automatic snapshot.

    {“http://example.aliyundoc.com/image03.jpg”}
    Imageobject
    StorageLocationstring

    The region in which the image is stored.

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

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

    2018-07-19T03:45:25Z
    Statusstring

    The status of the image file.

    • Uploading
    • Normal
    • UploadFail
    Uploading
    CateIdlong

    The ID of the category.

    1000123
    Tagsstring

    The tags of the image file.

    tag1
    ModificationTimestring

    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.

    2018-07-19T03:48:25Z
    CateNamestring

    The name of the category.

    beauty
    Descriptionstring

    The description of the image file.

    image test
    AppIdstring

    The ID of the application.

    app-****
    URLstring

    The URL of the image file.

    https://example.com/****.png
    Titlestring

    The title of the image file.

    image1
    ImageIdstring

    The ID of the image file.

    11130843741se99wqmoes****
    AttachedMediaobject
    CreationTimestring

    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.

    2018-07-19T03:45:25Z
    Statusstring

    The status of the auxiliary media asset. Valid values:

    • Uploading
    • Normal
    • UploadFail
    Normal
    StorageLocationstring

    The region in which the auxiliary media asset is stored.

    outin-bfefbb90a47c11*****7426.oss-cn-shanghai.aliyuncs.com
    Tagsstring

    The tags of the auxiliary media asset.

    test2
    ModificationTimestring

    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.

    2018-07-19T03:48:25Z
    MediaIdstring

    The ID of the auxiliary media asset.

    a82a2cd7d4e147ba0ed6c1ee372****
    BusinessTypestring

    The type of the auxiliary media asset. Valid values:

    • watermark
    • subtitle
    • material
    watermark
    Descriptionstring

    The description of the auxiliary media asset.

    test3
    AppIdstring

    The ID of the application.

    app-****
    URLstring

    The URL of the auxiliary media asset.

    https://example.com/****.png
    Titlestring

    The title of the auxiliary media asset.

    test
    Categoriesobject []

    The list of category IDs.

    ParentIdlong

    The ID of the parent node.

    -1
    CateNamestring

    The name of the category.

    test1
    CateIdlong

    The category ID of the auxiliary media asset.

    10027394
    Levellong

    The level of the category.

    1
    Categorystring

    The category.

    Transportation
    LabelNamestring

    The name of the tag.

    Vehicles
    LabelIdstring

    The ID of the tag.

    10310250338
    Scoredouble

    The score.

    0.75287705
    Fromdouble

    The start time of the clip.

    1.4
    Todouble

    The end time of the clip.

    2.5
    Fromdouble

    The start time of the subtitle.

    1.4
    Todouble

    The end time of the subtitle.

    2.5
    Contentstring

    The text content.

    I'm Jane.
    SaveTypestring

    The save type.

    TEXT
    Statusstring

    The data status.

    SaveSuccess
    AiJobIdstring

    The ID of the AI task.

    cd35b0b0025f71edbfcb472190a9xxxx
    AiCategorystring

    The AI category.

    TV series

    Examples

    Sample success responses

    JSONformat

    {
      "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",
            "RestoreExpiration": "2023-03-30T10:14:14Z",
            "RestoreStatus": "Success",
            "StorageClass": "Standard",
            "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",
            "RestoreExpiration": "2023-03-30T10:14:14Z",
            "RestoreStatus": "Success",
            "StorageClass": "Standard",
            "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": "beauty",
            "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": "test2",
            "ModificationTime": "2018-07-19T03:48:25Z",
            "MediaId": "a82a2cd7d4e147ba0ed6c1ee372****",
            "BusinessType": "watermark",
            "Description": "test3",
            "AppId": "app-****",
            "URL": "https://example.com/****.png",
            "Title": "test",
            "Categories": [
              {
                "ParentId": -1,
                "CateName": "test1",
                "CateId": 10027394,
                "Level": 1
              }
            ]
          },
          "AiData": {
            "AiLabelInfo": [
              {
                "Category": "Transportation",
                "LabelName": "Vehicles",
                "LabelId": "10310250338",
                "Occurrences": [
                  {
                    "Score": 0.75287705,
                    "From": 1.4,
                    "To": 2.5
                  }
                ]
              }
            ],
            "OcrInfo": [
              {
                "From": 1.4,
                "To": 2.5,
                "Content": "I'm Jane."
              }
            ]
          },
          "AiRoughData": {
            "SaveType": "TEXT\n",
            "Status": "SaveSuccess",
            "AiJobId": "cd35b0b0025f71edbfcb472190a9xxxx",
            "AiCategory": "TV series"
          }
        }
      ]
    }

    Error codes

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2023-04-11The response structure of the API has changedsee changesets
    Change itemChange content
    Output ParametersThe response structure of the API has changed.

    Common errors

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

    Error codeError messageHTTP status codeDescription
    SortByExceededMaxThe SortBy parameter only supports one sort field when traversing all data.400The error message returned because more than one sort field is specified to traverse all data.
    ErrorMatchSyntaxThe parameter Match.%s has an error syntax, please check it.400The error message returned because the syntax of the Match parameter is invalid. Check the syntax and try again.
    InvalidScrollToken.ExpiredThe ScrollToken is expired, please refresh it.400The error message returned because the value of the ScrollToken parameter is invalid. Obtain data again from Page 1.