International
中国站
Console
PrevNext
search by keyword

Recent Pages

Documentation
Documentation

SearchMedia

Last updated: 2021-02-23 16:19:13

1. API Description

Domain name for API request: vod.tencentcloudapi.com.

This API is used to search for media information and supports filtering and sorting the returned results in many ways. It can:

  • Fuzzily search by multiple media filenames Names or multiple descriptions Descriptions.

  • Search by multiple filename prefixes (NamePrefixes).

  • Specify the category set ClassIds (please see the input parameters) and return the media files in any category in the set. For example, assuming that there are categories of Movies, TV Series, and Variety Shows, and there are subcategories of History, Action, and Romance in the category of Movies, if Movies and TV Series are specified in ClassIds, then all the subcategories under Movies and TV Series will be returned; however, if History and Action are specified in ClassIds, only the media files in those two subcategories will be returned.

  • Specify the tag set Tags (please see the input parameters) and return the media files with any tag in the set. For example, assuming that there are tags of ACG, Drama, and YTPMV, if ACG and YTPMV are specified in Tags, then any media files with either tag will be retrieved.

  • Specify the source set SourceTypes (please see the input parameters) and return the media files from any source in the set. For example, assuming that there are Record (LVB recording) and Upload (upload) sources, if Record and Upload are specified in SourceTypes, then any media files from those sources will be retrieved.

  • Specify the creation time range to filter media files.

  • Specify the file type set Categories (please see the input parameters) and return the media files in any type in the set. For example, assuming that there are Video, Audio, and Image file types, if Video and Audio are specified in Categories, then any media files in those types will be retrieved.

  • Specify the file ID set FileIds and return the media files with any ID in the set.

  • Specify the stream ID set StreamIds (please see the input parameters) to filter LVB recording media files.

  • Specify the video ID set Vids (please see the input parameters) to filter LVB recording media files.

  • Specify a single text string Text to fuzzily search for media filenames or descriptions (this is not recommended. Names, NamePrefixes, or Descriptions should be used instead).

  • Specify a single stream ID StreamId for search (this is not recommended. StreamIds should be used instead).

  • Specify a single video ID Vid for search (this is not recommended. Vids should be used instead).

  • Specify a single creation start time StartTime for search (this is not recommended. CreateTime should be used instead).

  • Specify a single creation end time EndTime for search (this is not recommended. CreateTime should be used instead).

  • Specify a single media file source SourceType for search (this is not recommended. SourceTypes should be used instead).

  • Mix and match any parameters above for search. For example, you can filter the media files with the tags of "Drama" and "Suspense" in the category of "Movies" or "TV Series" created between 12:00:00, December 1, 2018 and 12:00:00, December 8, 2018. Please note that for any parameter that supports array input, the search logic between its elements is "OR", while the logical relationship between all parameters is "AND".

  • Sort the results by creation time and return them in multiple pages by specifying Offset and Limit (please see the input parameters).

  • Control the returned types of media information through Filters (all types will be returned by default). Valid values include:

    1. Basic information (basicInfo): media name, category, playback address, cover image, etc.
    2. Metadata (metaData): size, duration, video stream information, audio stream information, etc.
    3. Information of the transcoding result (transcodeInfo): addresses, video stream parameters, and audio stream parameters of the media files with various specifications generated by transcoding a media file.
    4. Information of the animated image generating result (animatedGraphicsInfo): information of an animated image (such as .gif) generated from a video.
    5. Information of a sampled screenshot (sampleSnapshotInfo): information of a sampled screenshot of a video.
    6. Information of an image sprite (imageSpriteInfo): information of an image sprite generated from a video.
    7. Information of a point-in-time screenshot (snapshotByTimeOffsetInfo): information of a point-in-time screenshot of a video.
    8. Information of a timestamp (keyFrameDescInfo): information of a timestamp set for a video.
    9. Information of adaptive bitrate streaming (adaptiveDynamicStreamingInfo): specification, encryption type, muxing format, etc.
Upper limit of returned results:
- The Offset and Limit parameters determine the number of search results on one single page. Note: if both of them use the default value, this API will return up to 10 results. - Up to 5,000 search results can be returned, and excessive ones will not be displayed. If there are too many search results, you are recommended to use more specified filters to narrow down the search results.

A maximum of 100 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common parameter. The value used for this API: SearchMedia.
Version Yes String Common parameter. The value used for this API: 2018-07-17.
Region No String Common parameter. This parameter is not required for this API.
Tags.N No Array of String Tag set, which matches any element in the set.
  • Tag length limit: 8 characters.
  • Array length limit: 10.
    		•
    ClassIds.N No Array of Integer Category ID set. The categories of the specified IDs and all subcategories in the set are matched.
  • Array length limit: 10.
    		•
    StreamIds.N No Array of String Stream ID set. Any element in the set can be matched.
  • Array length limit: 10.
    		•
    Vids.N No Array of String Unique ID of LVB recording file. Any element in the set can be matched.
  • Array length limit: 10.
    		•
    SourceTypes.N No Array of String Media file source set. For valid values, please see SourceType.
  • Array length limit: 10.
    		•
    Categories.N No Array of String File type. Any element in the set can be matched.
  • Video: video file
  • Audio: audio file
  • Image: image file
    		•
    CreateTime No TimeRange Matches files created within the time period.
  • Includes specified start and end points in time.
    		•
    FileIds.N No Array of String File ID set. Any element in the set can be matched.
  • Array length limit: 10.
  • ID length limit: 40 characters.
    		•
    Names.N No Array of String Filename set. Filenames of media files are fuzzily matched. The higher the match rate, the higher-ranked the result.
  • Filename length limit: 40 characters.
  • Array length limit: 10.
    		•
    NamePrefixes.N No Array of String Filename prefix, which matches the filenames of media files.
  • Filename prefix length limit: 20 characters.
  • Array length limit: 10.
    		•
    Descriptions.N No Array of String File description set. Any element in the set can be matched.
  • Description length limit: 100 characters.
  • Array length limit: 10.
    		•
    Sort No SortBy Sorting order.
  • Valid value of Sort.Field: CreateTime.
  • If Text, Names, or Descriptions is not empty, the Sort.Field field will not take effect, and the search results will be sorted by match rate.
    		•
    Offset No Integer
    Start offset of a paged return. Default value: 0. Entries from No. "Offset" to No. "Offset + Limit - 1" will be returned.
  • Value range: "Offset + Limit" cannot be more than 5,000. (For more information, please see Limit on the Number of Results Returned by API)
    		•
    Limit No Integer
    Number of entries returned by a paged query. Default value: 10. Entries from No. "Offset" to No. "Offset + Limit - 1" will be returned.
  • Value range: "Offset + Limit" cannot be more than 5,000. (For more information, please see Limit on the Number of Results Returned by API)
    		•
    Filters.N No Array of String Specifies information entry that needs to be returned for all media files. Multiple entries can be specified simultaneously. N starts from 0. If this field is left empty, all information entries will be returned by default. Valid values:
  • basicInfo (basic video information).
  • metaData (video metadata).
  • transcodeInfo (result information of video transcoding).
  • animatedGraphicsInfo (result information of animated image generating task).
  • imageSpriteInfo (image sprite information).
  • snapshotByTimeOffsetInfo (point-in-time screenshot information).
  • sampleSnapshotInfo (sampled screenshot information).
  • keyFrameDescInfo (timestamp information).
  • adaptiveDynamicStreamingInfo (information of adaptive bitrate streaming).
  • miniProgramReviewInfo (WeChat Mini Program audit information).
    		•
    SubAppId No Integer Subapplication ID in VOD. If you need to access a resource in a subapplication, enter the subapplication ID in this field; otherwise, leave it empty.
    StreamId No String (This is not recommended. StreamIds should be used instead)
    Stream ID.
    Vid No String (This is not recommended. Vids should be used instead)
    Unique ID of LVB recording file.
    Text No String (This is not recommended. Names, NamePrefixes, or Descriptions should be used instead)
    Search text, which fuzzily matches the media file name or description. The more matching items and the higher the match rate, the higher-ranked the result. It can contain up to 64 characters.
    StartTime No String (This is not recommended. CreateTime should be used instead)
    Start time in the creation time range.
  • After or at the start time.
  • If CreateTime.After also exists, it will be used first.
  • In ISO 8601 format. For more information, please see ISO Date Format.
    		•
    EndTime No String (This is not recommended. CreateTime should be used instead)
    End time in the creation time range.
  • Before the end time.
  • If CreateTime.Before also exists, it will be used first.
  • In ISO 8601 format. For more information, please see ISO Date Format.
    		•
    SourceType No String (This is not recommended. SourceTypes should be used instead)
    Media file source. For valid values, please see SourceType.

    3. Output Parameters

    Parameter Name Type Description
    TotalCount Integer Number of eligible entries.
  • Maximum value: 5000. If the number of eligible entries is greater than 5,000, this field will return 5,000 instead of the actual number.
    		•
    MediaInfoSet Array of MediaInfo Media file information list.
    Note: this field may return null, indicating that no valid values can be obtained.
    RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

    4. Example

    Example1 Searching for media information

    Input Example

    https://vod.tencentcloudapi.com/?Action=SearchMedia
&Names.0=test
&ClassIds.0=1
&ClassIds.1=2
&CreateTime.After=2016-09-20T10:00:00Z
&CreateTime.Before=2018-10-02T10:00:00Z
&SourceTypes.0=Record
&Sort.Field=CreatTime
&Sort.Order=Desc
&<Common request parameters>

    Output Example

    {
  "Response": {
    "RequestId": "6ca31e3a-6b8e-4b4e-9256-fdc700064ef3",
    "MediaInfoSet": [
      {
        "FileId": "5285485487985271487",
        "BasicInfo": {
          "Name": "test file",
          "Description": "",
          "CreateTime": "2017-01-23T07:25:52Z",
          "UpdateTime": "2017-01-23T07:25:52Z",
          "ExpireTime": "2017-03-23T07:25:52Z",
          "ClassId": 1,
          "ClassName": "Test",
          "ClassPath": "Test",
          "CoverUrl": "http://xx.vod2.myqcloud.com/xxxxxxxx/shotup/f0.100_0.jpg",
          "Type": "mp4",
          "MediaUrl": "http://xx.vod2.myqcloud.com/xx/xx/f0.mp4",
          "TagSet": [],
          "SourceInfo": {
            "SourceType": "Record",
            "SourceContext": ""
          },
          "StorageRegion": "gzp"
        },
        "MetaData": {
          "Size": 10556,
          "Container": "m4a",
          "Duration": 3601.0,
          "Bitrate": 246035,
          "Height": 480,
          "Width": 640,
          "Rotate": 0,
          "VideoStreamSet": [
            {
              "Bitrate": 246000,
              "Height": 480,
              "Width": 640,
              "Codec": "h264",
              "Fps": 222
            }
          ],
          "AudioStreamSet": [
            {
              "Codec": "aac",
              "SamplingRate": 44100,
              "Bitrate": 35
            }
          ]
        },
        "TranscodeInfo": {
          "TranscodeSet": [
            {
              "Url": "http://xxxx.vod2.myqcloud.com/xx/xx/f0.mp4",
              "Definition": 0,
              "Bitrate": 563477,
              "Height": 378,
              "Width": 672,
              "Container": "m4a",
              "Duration": 3601.0,
              "Size": 10502,
              "Md5": "b3ae6ed07d9bf4efeeb94ed2d37ff3e3",
              "VideoStreamSet": [
                {
                  "Bitrate": 246000,
                  "Height": 480,
                  "Width": 640,
                  "Codec": "h264",
                  "Fps": 222
                }
              ],
              "AudioStreamSet": [
                {
                  "Codec": "aac",
                  "SamplingRate": 44100,
                  "Bitrate": 35
                }
              ]
            },
            {
              "Url": "http://xxxx.vod2.myqcloud.com/xx/xx/f0.f210.m3u8",
              "Definition": 211,
              "Bitrate": 563477,
              "Height": 378,
              "Width": 672,
              "Container": "mov",
              "Duration": 3601.0,
              "Size": 10502,
              "Md5": "b3ae6ed07d9bf4efeeb94ed2d37ff3e3",
              "VideoStreamSet": [
                {
                  "Bitrate": 246000,
                  "Height": 480,
                  "Width": 640,
                  "Codec": "h264",
                  "Fps": 222
                }
              ],
              "AudioStreamSet": [
                {
                  "Codec": "aac",
                  "SamplingRate": 44100,
                  "Bitrate": 35
                }
              ]
            },
            {
              "Url": "http://xxxx.vod2.myqcloud.com/xx/xx/master_playlist.m3u8",
              "Definition": 10000,
              "Duration": 145.0,
              "Size": 265,
              "Bitrate": 2840055,
              "Height": 1080,
              "Width": 1920,
              "Container": "hls,applehttp",
              "Md5": "bfcf7c6f154b18890661f9e80b0731d0",
              "VideoStreamSet": [
                {
                  "Bitrate": 2794233,
                  "Height": 1080,
                  "Width": 1920,
                  "Codec": "h264",
                  "Fps": 24
                }
              ],
              "AudioStreamSet": [
                {
                  "SamplingRate": 44100,
                  "Bitrate": 45822,
                  "Codec": "aac"
                }
              ]
            }
          ]
        },
        "AnimatedGraphicsInfo": {
          "AnimatedGraphicsSet": [
            {
              "Url": "http://125xx.vod2.myqcloud.com/xx/xx/f20000.gif",
              "Definition": 20000,
              "Container": "gif",
              "Height": 480,
              "Width": 640,
              "Bitrate": 1000000,
              "Size": 600000,
              "Md5": "bfcf7c6f154b1842a661f9e80b07a1d0",
              "StartTimeOffset": 10.0,
              "EndTimeOffset": 15.0
            }
          ]
        },
        "SampleSnapshotInfo": {
          "SampleSnapshotSet": [
            {
              "Definition": 10,
              "SampleType": "percent",
              "Interval": 10,
              "ImageUrlSet": [
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx1.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx2.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx3.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx4.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx5.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx6.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx7.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx8.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx9.png",
                "http://125xx.vod2.myqcloud.com/xx/xx/shotup/xx10.png"
              ]
            }
          ]
        },
        "ImageSpriteInfo": {
          "ImageSpriteSet": [
            {
              "Definition": 10,
              "Height": 576,
              "Width": 1024,
              "TotalCount": 100,
              "ImageUrlSet": [
                "http://xx.vod2.myqcloud.com/xx/xx/imageSprite/xx.100_0.jpg"
              ],
              "WebVttUrl": "http://xx.vod2.myqcloud.com/xxxx/xxxx/imageSprite/xx.vtt"
            }
          ]
        },
        "SnapshotByTimeOffsetInfo": {
          "SnapshotByTimeOffsetSet": [
            {
              "Definition": 10,
              "PicInfoSet": [
                {
                  "TimeOffset": 0.0,
                  "Url": "http://xxxx.vod2.myqcloud.com/xx/xx/snapshotByTime/xx1.jpg"
                },
                {
                  "TimeOffset": 1000.0,
                  "Url": "http://xxxx.vod2.myqcloud.com/xx/xx/snapshotByTime/xx2.jpg"
                }
              ]
            }
          ]
        },
        "KeyFrameDescInfo": {
          "KeyFrameDescSet": [
            {
              "TimeOffset": 1.0,
              "Content": "abc"
            },
            {
              "TimeOffset": 100.0,
              "Content": "def"
            }
          ]
        }
      }
    ],
    "NotExistFileIdSet": [
      "5285485487985271488"
    ]
  }
}

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    FailedOperation Operation failed.
    FailedOperation.InvalidVodUser The VOD service is not activated.
    InternalError Internal error.
    InternalError.GetMediaListError Internal error: an error occurred while getting the media list.
    InvalidParameterValue.Categories
    InvalidParameterValue.ClassIds Incorrect parameter value: invalid ClassIds.
    InvalidParameterValue.EndTime Incorrect parameter value: invalid EndTime.
    InvalidParameterValue.FileIds Incorrect FileIds parameter.
    InvalidParameterValue.NamePrefixes
    InvalidParameterValue.Names Too many elements in the Names array.
    InvalidParameterValue.Offset Incorrect parameter value: invalid Offset.
    InvalidParameterValue.Sort Incorrect parameter value: invalid Sort.
    InvalidParameterValue.SourceType Incorrect parameter value: invalid SourceType.
    InvalidParameterValue.StartTime Incorrect parameter value: invalid StartTime.
    InvalidParameterValue.StreamIds
    InvalidParameterValue.SubAppId Incorrect parameter value: subapplication ID
    InvalidParameterValue.Tags Incorrect parameter value: invalid Tags.
    InvalidParameterValue.Text Incorrect parameter value: search text.
    LimitExceeded Quota limit is exceeded.
    UnauthorizedOperation Unauthorized operation.

    Was this page helpful?

    Confirm

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Hide
    Submit a TicketContact sales
    Help
    tencent
    Copyright © 2013-2021 Tencent Cloud. All Rights Reserved.
    Privacy PolicyTerms of ServiceCookie Policy