服务端 API 文档

搜索媒体信息

最近更新时间:2020-10-20 08:08:24

1. 接口描述

接口请求域名: vod.tencentcloudapi.com 。

搜索媒体信息,支持多种条件筛选,以及支持对返回结果排序、过滤等功能,具体包括:

  • 根据多个媒体文件名 Names 或描述信息 Descriptions 进行模糊搜索。
  • 根据多个文件名前缀 NamePrefixes 进行搜索。
  • 指定分类集合 ClassIds(见输入参数),返回满足集合中任意分类的媒体。例如:媒体分类有电影、电视剧、综艺等,其中电影分类下又有子分类历史片、动作片、言情片。如果 ClassIds 指定了电影、电视剧,那么电影和电视剧下的所有子分类都会返回;而如果 ClassIds 指定的是历史片、动作片,那么只有这2个子分类下的媒体才会返回。
  • 指定标签集合 Tags(见输入参数),返回满足集合中任意标签的媒体。例如:媒体标签有二次元、宫斗、鬼畜,如果 Tags 指定了二次元、鬼畜2个标签,那么只要符合这2个标签中任意一个的媒体都会被检索出来。
  • 指定来源集合 SourceTypes(见输入参数),返回满足集合中任意来源的媒体。例如:媒体来源有 Record (直播录制)、Upload (上传)等。如果 SourceTypes 指定了 Record 和 Upload ,那么符合这些来源的媒体都会被检索出来。
  • 指定媒体的创建时间范围筛选媒体。
  • 指定文件类型集合 Categories(见输入参数),返回满足集合中任意类型的媒体。例如:文件类型有 Video(视频)、 Audio (音频)、 Image (图片)。如果Categories指定了 Video 和 Audio 2个文件类型,那么符合这些类型的媒体都会被检索出来。
  • 指定文件 ID 集合 FileIds ,返回匹配集合中任意 ID 的媒体。
  • 指定直播推流码集合 StreamIds(见输入参数)筛选直播录制的媒体。
  • 指定视频 ID 集合 Vids (见输入参数)筛选直播录制的媒体。
  • (不推荐:应使用 Names、NamePrefixes 或 Descriptions 替代)指定单个文本 Text 对媒体文件名或描述信息进行模糊搜索。
  • (不推荐:应使用 StreamIds 替代)指定单个推流直播码 StreamId 进行搜索。
  • (不推荐:应使用 Vids 替代)指定单个视频 ID Vid 进行搜索。
  • (不推荐:应使用 CreateTime 替代)指定单个起始创建时间 StartTime 进行搜索。
  • (不推荐:应使用 CreateTime 替代)指定单个结尾创建时间 EndTime 进行搜索。
  • (不推荐: 应使用 SourceTypes 替代)指定单个媒体文件来源 SourceType 进行搜索。

  • 以上参数之间可以任意组合进行检索。例如:筛选创建时间在2018年12月1日12:00:00到2018年12月8日12:00:00之间、分类为电影或电视剧、带有宫斗和悬疑标签的媒体。注意,任何支持数组输入的参数,其元素之间的搜索逻辑为‘或’。所有参数之间的逻辑关系为‘与’。
  • 允许对结果根据创建时间进行排序并分页返回,通过 Offset 和 Limit (见输入参数)来控制分页。
  • 允许通过 Filters 控制返回的媒体信息种类(默认返回所有信息)。可选输入包括:
    1. 基础信息(basicInfo):包括媒体名称、分类、播放地址、封面图片等。
    2. 元信息(metaData):包括大小、时长、视频流信息、音频流信息等。
    3. 转码结果信息(transcodeInfo):包括该媒体转码生成的各种规格的媒体地址、视频流参数、音频流参数等。
    4. 转动图结果信息(animatedGraphicsInfo):对视频转动图(如 gif)后的动图信息。
    5. 采样截图信息(sampleSnapshotInfo):对视频采样截图后的截图信息。
    6. 雪碧图信息(imageSpriteInfo):对视频截取雪碧图后的雪碧图信息。
    7. 指定时间点截图信息(snapshotByTimeOffsetInfo):对视频依照指定时间点截图后,的截图信息。
    8. 视频打点信息(keyFrameDescInfo):对视频设置的打点信息。
    9. 转自适应码流信息(adaptiveDynamicStreamingInfo):包括规格、加密类型、打包格式等相关信息。
接口返回结果数限制:
  • OffsetLimit 两个参数影响单次分页查询结果数。特别注意:当这2个值都缺省时,本接口最多只返回10条查询结果。
  • 最大支持返回5000条搜索结果,超出部分不再支持查询。如果搜索结果量太大,建议使用更精细的筛选条件来减少搜索结果。

默认接口请求频率限制:100次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:SearchMedia。
Version String 公共参数,本接口取值:2018-07-17。
Region String 公共参数,本接口不需要传递此参数。
Tags.N Array of String 标签集合,匹配集合中任意元素。
  • 单个标签长度限制:8个字符。
  • 数组长度限制:10。
  • ClassIds.N Array of Integer 分类 ID 集合,匹配集合指定 ID 的分类及其所有子类。
  • 数组长度限制:10。
  • StreamIds.N Array of String 推流 直播码 集合。匹配集合中的任意元素。
  • 数组长度限制:10。
  • Vids.N Array of String 直播录制文件的唯一标识。匹配集合中的任意元素。
  • 数组长度限制:10。
  • SourceTypes.N Array of String 媒体文件来源集合,来源取值参见 SourceType
  • 数组长度限制:10。
  • Categories.N Array of String 文件类型。匹配集合中的任意元素:
  • Video: 视频文件
  • Audio: 音频文件
  • Image: 图片文件
  • CreateTime TimeRange 匹配创建时间在此时间段内的文件。
  • 包含所指定的头尾时间点。
  • FileIds.N Array of String 文件 ID 集合,匹配集合中的任意元素。
  • 数组长度限制:10。
  • 单个 ID 长度限制:40个字符。
  • Names.N Array of String 文件名集合,模糊匹配媒体文件的文件名,匹配度越高,排序越优先。
  • 单个文件名长度限制:40个字符。
  • 数组长度限制:10。
  • NamePrefixes.N Array of String 文件名前缀,前缀匹配媒体文件的文件名。
  • 单个文件名前缀长度限制:20个字符。
  • 数组长度限制:10。
  • Descriptions.N Array of String 文件描述集合,匹配集合中的任意元素。
  • 单个描述长度限制:100个字符。
  • 数组长度限制:10。
  • Sort SortBy 排序方式。
  • Sort.Field 可选 CreateTime 。
  • 当 Text、 Names 或 Descriptions 不为空时,Sort.Field 字段无效, 搜索结果将以匹配度排序。
  • Offset Integer
    分页返回的起始偏移量,默认值:0。将返回第 Offset 到第 Offset+Limit-1 条。
  • 取值范围:Offset + Limit 不超过5000。(参见:接口返回结果数限制
  • Limit Integer
    分页返回的记录条数,默认值:10。将返回第 Offset 到第 Offset+Limit-1 条。
  • 取值范围:Offset + Limit 不超过5000。(参见:接口返回结果数限制
  • Filters.N Array of String 指定所有媒体文件需要返回的信息,可同时指定多个信息,N 从 0 开始递增。如果未填写该字段,默认返回所有信息。选项有:
  • basicInfo(视频基础信息)。
  • metaData(视频元信息)。
  • transcodeInfo(视频转码结果信息)。
  • animatedGraphicsInfo(视频转动图结果信息)。
  • imageSpriteInfo(视频雪碧图信息)。
  • snapshotByTimeOffsetInfo(视频指定时间点截图信息)。
  • sampleSnapshotInfo(采样截图信息)。
  • keyFrameDescInfo(打点信息)。
  • adaptiveDynamicStreamingInfo(转自适应码流信息)。
  • miniProgramReviewInfo(小程序审核信息)。
  • SubAppId Integer 点播子应用 ID。如果要访问子应用中的资源,则将该字段填写为子应用 ID;否则无需填写该字段。
    StreamId String (不推荐:应使用 StreamIds 替代)
    推流 直播码
    Vid String (不推荐:应使用 Vids 替代)
    直播录制文件的唯一标识。
    Text String (不推荐:应使用 Names、NamePrefixes 或 Descriptions 替代)
    搜索文本,模糊匹配媒体文件名称或描述信息,匹配项越多,匹配度越高,排序越优先。长度限制:64个字符。
    StartTime String (不推荐:应使用 CreateTime 替代)
    创建时间的开始时间。
  • 大于等于开始时间。
  • 当 CreateTime.After 也存在时,将优先使用 CreateTime.After。
  • 格式按照 ISO 8601标准表示,详见 ISO 日期格式说明
  • EndTime String (不推荐:应使用 CreateTime 替代)
    创建时间的结束时间。
  • 小于结束时间。
  • 当 CreateTime.Before 也存在时,将优先使用 CreateTime.Before。
  • 格式按照 ISO 8601标准表示,详见 ISO 日期格式说明
  • SourceType String (不推荐:应使用 SourceTypes 替代)
    媒体文件来源,来源取值参见 SourceType

    3. 输出参数

    参数名称 类型 描述
    TotalCount Integer 符合搜索条件的记录总数。
  • 最大值:5000。当命中记录数超过5000时,该字段将返回 5000,而非实际命中总数。
  • MediaInfoSet Array of MediaInfo 媒体文件信息列表。
    注意:此字段可能返回 null,表示取不到有效值。
    RequestId String 唯一请求 ID,每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

    4. 示例

    示例1 搜索媒体信息

    输入示例

    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
    &<公共请求参数>

    输出示例

    {
      "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": "测试",
              "ClassPath": "测试",
              "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. 开发者资源

    API Explorer

    该工具提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力,能显著降低使用云 API 的难度,推荐使用。

    SDK

    云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

    命令行工具

    6. 错误码

    以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

    错误码 描述
    FailedOperation.InvalidVodUser 没有开通点播业务。
    InternalError 内部错误。
    InternalError.GetMediaListError 内部错误:获取媒体列表错误。
    InvalidParameterValue.ClassIds 参数值错误:ClassIds 无效。
    InvalidParameterValue.EndTime 参数值错误:EndTime 无效。
    InvalidParameterValue.FileIds FileIds 参数错误。
    InvalidParameterValue.Names Names数组中元素过多。
    InvalidParameterValue.Offset 参数值错误:Offset 无效。
    InvalidParameterValue.Sort 参数值错误:Sort 无效。
    InvalidParameterValue.SourceType 参数值错误:SourceType 无效。
    InvalidParameterValue.StartTime 参数值错误:StartTime 无效。
    InvalidParameterValue.SubAppId 参数值错误:子应用 ID。
    InvalidParameterValue.Tags 参数值错误:Tags 无效。
    InvalidParameterValue.Text 参数值错误:搜索文本。
    LimitExceeded 超过配额限制。
    UnauthorizedOperation 未授权操作。
    目录