International
中国站
Console
PrevNext
search by keyword

Recent Pages

Documentation
Documentation

SearchMedia

Last updated: 2021-04-21 16:38:26

    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. You can:

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

    • 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) to 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 these two subcategories will be returned.

    • Specify the tag set Tags (please see the input parameters) to 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 file type set Categories (please see the input parameters) to return the media files of 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 all media files of these two types will be retrieved.

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

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

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

    • Specify the creation time range to filter media files.

    • Specify a text string Text for fuzzy search by media filenames or descriptions. (This is not recommended. Names, NamePrefixes, or Descriptions should be used instead.)

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

    • Specify a live stream code StreamId for search. (This is not recommended. StreamIds should be used instead.)

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

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

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

    • Search by any combination of the parameters above. For example, you can search for 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", and the logical relationship between 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).

    • Specify Filters to return specified types of media information (all types will be returned by default). Valid values:

      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 various specifications generated by the file transcoding.
      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 configured for a video.
      9. Information of transcoding to 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 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.
    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. Media file descriptions are fuzzily matched. The higher the match rate, the higher-ranked the result.
  • Length limit for a single description: 100 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.
    		•
    Tags.N No Array of String Tag set, which matches any element in the set.
  • Tag length limit: 8 characters.
  • 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
    		•
    SourceTypes.N No Array of String Media file source set. For valid values, please see SourceType.
  • 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.
    		•
    CreateTime No TimeRange Matches files created within the time period.
  • Includes specified start and end points in time.
    		•
    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).
  • m