Documentation

SearchMedia

Last updated: 2020-09-17 17:55:35

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

API Explorer

This tool allows online call, signature authentication, SDK code generation and quick search of APIs to greatly improve the efficiency of using TencentCloud APIs.

API 3.0 Explorer

SDK

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

Command Line Interface

Tencent Cloud CLI 3.0

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.InvalidVodUser	The VOD service is not activated.
InternalError	Internal error.
InternalError.GetMediaListError	Internal error: an error occurred while getting the media list.
InvalidParameterValue.ClassIds	Incorrect parameter value: invalid `ClassIds`.
InvalidParameterValue.EndTime	Incorrect parameter value: invalid `EndTime`.
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.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

Recent Pages

SearchMedia

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Example1 Searching for media information

Input Example

Output Example

5. Developer Resources

API Explorer

SDK

Command Line Interface

6. Error Code

Was this page helpful?

Was this page helpful?

About Tencent Cloud

Help & Support

User Center

Resources

7x24 Hotline

Documentation

Sign Up

Log in

Recent Pages

SearchMedia

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Example1 Searching for media information

Input Example

Output Example

5. Developer Resources

API Explorer

SDK

Command Line Interface

6. Error Code

Was this page helpful?

Was this page helpful?

About Tencent Cloud

Help & Support

User Center

Resources

7x24 Hotline