文档

SearchMedia - 搜索媒体信息

更新时间:

本接口用于搜索视频点播生产的视频、音频和图片等媒资信息,调用本接口配合媒资搜索协议可实现在视频点播中进行指定返回字段、精确匹配、模糊匹配、多值查询、范围查询、排序字段等多方式多维度的搜索查询。

接口说明

获取命中数据条数限制说明如下:

  • 方法一:分页遍历

    对于命中的搜索结果,您可以通过设置分页参数“PageNo”(页码)和“PageSize”(每页显示的记录数)来逐步遍历最多 5000 条数据。如果搜索结果超出了 5000 条,为了保证有效地遍历数据,请调整搜索条件以缩小结果范围。需要注意的是,此方法无法遍历完整数据集。若要遍历更多数据,请参考方法二。

  • 方法二:全量遍历(限音视频搜索)

    此方法适用于视频和音频内容的搜索,支持遍历最多 200 万条的全部搜索结果。如果搜索结果数量超过 200 万条,您应该通过增加更多筛选条件来减少结果数量。使用此方法时,除了“PageNo”和“PageSize”,您还需使用“ScrollToken”参数实现分页。请注意,每次仅支持向后遍历最多 100 条记录。 使用“PageSize”为 20 为例,以下是分页逻辑:

    • 若“PageNo”为 1,您可以查询接下来的最多 5 页数据。
    • 若“PageNo”为 2,您可以查询接下来的最多 6 页数据。

请确保在搜索时合理设置分页参数,并根据结果集大小选择适当的遍历方法。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
vod:SearchMediaList
  • 全部资源
    *

请求参数

名称类型必填描述示例值
SearchTypestring

搜索媒资数据类型。取值范围:

  • video(默认值):视频。
  • audio:音频。
  • image:图片。
  • attached:辅助媒资。
说明 当本参数取值为 videoaudio,且需要遍历搜索条件命中的所有数据时,必须设置 ScrollToken 参数。
video
Fieldsstring

搜索结果中返回的媒资字段。

默认只返回基本媒资字段,可指定返回更多媒资字段,请参见使用示例

Title,CoverURL
Matchstring

过滤条件。语法规则,请参见搜索协议语法

field = value
SortBystring

排序字段和排序顺序。多个使用半角逗号(,)分隔。取值:

  • CreationTime:Desc(默认值):按创建时间倒序。
  • CreationTime:Asc:按创建时间升序。
说明
  • 排序字段示例:排序字段
  • 获取搜索条件是前 5000 条的数据时,最多支持三个排序字段。
  • 获取搜索条件是所有数据时,仅支持一个排序字段。
  • CreationTime:Desc
    PageNointeger

    当前页码。默认值为 1

    说明 当本参数取值超过 200 时,建议同时设置 ScrollToken 参数。
    1
    PageSizeinteger

    每页返回的数据条数。默认值为 10,最大值为 100

    10
    ScrollTokenstring

    翻页标识。长度为 32 个字符。 第一次执行搜索请求时不用设置本参数。搜索请求命中数据时,服务端会返回该参数值,用于记录当前搜索数据的位置地址。请记录返回的参数值,下一次搜索时按下述要求或建议设置本参数:

    • 当 SearchType 参数取值为 videoaudio,且需要遍历搜索条件命中的所有数据时,本参数必须设置。
    • 当 PageNo 参数取值超过 200 时,建议设置本参数优化搜索性能。
    24e0fba7188fae707e146esa54****

    返回参数

    名称类型描述示例值
    object

    返回结果。

    RequestIdstring

    请求 ID。

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

    满足搜索条件的媒资信息总条数。

    10
    ScrollTokenstring

    翻页标识。

    24e0fba7188fae707e146esa54****
    MediaListobject []

    媒资信息列表。

    CreationTimestring

    媒体创建时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    媒体类型。取值范围:

    • video:视频。
    • audio:音频。
    • image:图片。
    • attached:辅助媒资。
    video
    MediaIdstring

    媒体 ID。

    a82a2cd7d4e147bbed6c1ee372****
    Videoobject
    Statusstring

    状态。取值:

    • Uploading:上传中。
    • UploadFail:上传失败。
    • UploadSucc:上传完成。
    • Transcoding:转码中。
    • TranscodeFail:转码失败。
    • Blocked:屏蔽。
    • Normal:正常。
    UploadSucc
    CreationTimestring

    视频信息创建时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    存储区域。

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

    分类 ID。

    10000123
    Tagsstring

    视频标签。

    tag1
    ModificationTimestring

    视频信息更新时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    来源。取值:

    • general:点播上传。
    • short_video:短视频 SDK。
    • editing:剪辑合成。
    • live:直播录制。
    general
    Descriptionstring

    视频描述。

    视频测试
    AppIdstring

    应用 ID。

    app-****
    CoverURLstring

    封面图片。

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

    视频 ID。

    a82a2asdasqadaf3faa0ed6c1ee372****
    DownloadSwitchstring

    下载开关。只有状态开启时才允许离线下载。取值范围:

    • on(开启):初始状态,允许离线下载。
    • off(禁用):禁用离线下载。
    on
    CateNamestring

    分类名称。

    video1
    TranscodeModestring

    转码模式。取值:

    • FastTranscode(普通转码):默认模式,上传完成即开始转码,且转码完成才能播放。
    • NoTranscode(不转码即分发):上传完成不转码,且立即能播放。
    • AsyncTranscode(上传即分发并转码) :上传完成即能播放,同时异步进行转码。
    FastTranscode
    PreprocessStatusstring

    预处理状态 。取值:

    • UnPreprocess:未进行预处理。
    • Preprocessing:预处理中。
    • PreprocessSucceed:预处理完成。
    • PreprocessFailed:预处理失败。
    Preprocessing
    RestoreExpirationstring

    媒资解冻有效期。

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

    媒资解冻状态。取值:

    • Processing:解冻中。
    • Success:解冻成功。
    • Failed:解冻失败。
    Success
    StorageClassstring

    媒资存储类型。取值:

    • Standard:标准。
    • IA:媒资低频。
    • Archive:媒资归档。
    • ColdArchive:媒资冷归档。
    • SourceIA:源文件低频。
    • SourceArchive:源文件归档。
    • SourceColdArchive:源文件冷归档。
    • Changing:媒资存储类型变更中。
    • SourceChanging:源文件存储类型变更中。
    Standard
    Sizelong

    视频大小。

    123
    Durationfloat

    视频时长。单位:秒。

    123
    Titlestring

    视频标题。

    ceshi
    SpriteSnapshotsarray

    雪碧图列表。

    string

    雪碧图列表。

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

    自动截图列表。

    string

    自动截图列表。

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

    状态。取值:

    • Uploading:上传中。
    • Normal:正常。
    • UploadFail:失败。
    • Deleted:删除。
    Normal
    CreationTimestring

    创建时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    存储区域。

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

    分类 ID。

    10000123
    Tagsstring

    标签。

    tag1,tag2
    ModificationTimestring

    更新时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    来源。取值:

    • general(点播上传):普通上传。
    • short_video(短视频 SDK): 通过短视频 SDK 上传文件至点播,详细内容请参见短视频 SDK
    • editing(剪辑合成):通过云剪辑合成上传文件至点播,详细内容请参见视频合成
    • live(直播录制):通过直播录制上传文件至点播。
    general
    Descriptionstring

    描述。

    音频描述
    AppIdstring

    应用 ID。

    app-****
    CoverURLstring

    封面图片。

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

    音频 ID。

    a82a2cd7d4e147bbed6c1ee372****
    DownloadSwitchstring

    下载开关。只有状态开启时才允许离线下载。取值:

    • on(开启):初始状态,允许离线下载。
    • off(禁用):禁用离线下载。
    on
    CateNamestring

    分类名称。

    ceshi
    TranscodeModestring

    转码模式。取值范围:

    • FastTranscode(普通转码,默认值):上传完成即开始转码,且转码完成才能播放。
    • NoTranscode(不转码即分发):上传完成不转码,且立即能播放。
    • AsyncTranscode(上传即分发并转码):上传完成即能播放,同时异步进行转码。
    FastTranscode
    PreprocessStatusstring

    预处理状态,预处理完成后的视频才可用于直播导播。取值:

    • UnPreprocess:未进行预处理。
    • Preprocessing:预处理中。
    • PreprocessSucceed:预处理完成。
    • PreprocessFailed:预处理失败。
    UnPreprocess
    RestoreExpirationstring

    媒资解冻有效期。

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

    媒资解冻状态。取值:

    • Processing:解冻中。
    • Success:解冻成功。
    • Failed:解冻失败。
    Success
    StorageClassstring

    媒资存储类型。取值:

    • Standard:标准。
    • IA:媒资低频。
    • Archive:媒资归档。
    • ColdArchive:媒资冷归档。
    • SourceIA:源文件低频。
    • SourceArchive:源文件归档。
    • SourceColdArchive:源文件冷归档。
    • Changing:变更中。
    Standard
    Sizelong

    大小。

    123
    Durationfloat

    时长。

    123
    Titlestring

    标题。

    音频
    SpriteSnapshotsarray

    雪碧图列表。

    string

    雪碧图列表。

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

    自动截图列表。

    string

    自动截图列表。

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

    存储地域。

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

    创建时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    图片状态。

    • Uploading(上传中):初始状态,表示图片正在上传。
    • Normal(正常):图片上传成功。
    • UploadFail(失败):图片上传失败。
    Uploading
    CateIdlong

    分类 ID。

    1000123
    Tagsstring

    标签。

    tag1
    ModificationTimestring

    更新时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    分类名称。

    美图1
    Descriptionstring

    描述。

    图片测试
    AppIdstring

    应用 ID。

    app-****
    URLstring

    图片 URL。

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

    标题。

    image1
    ImageIdstring

    图片 ID。

    11130843741se99wqmoes****
    AttachedMediaobject
    CreationTimestring

    创建时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    状态。取值:

    • Uploading(上传中): 初始状态,表示辅助媒资正在上传。
    • Normal(正常):辅助媒资上传成功。
    • UploadFail(失败):辅助媒资上传失败。
    Normal
    StorageLocationstring

    存储区域。

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

    标签。

    测试
    ModificationTimestring

    更新时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

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

    辅助媒资 ID。

    a82a2cd7d4e147ba0ed6c1ee372****
    BusinessTypestring

    业务类型。取值:

    • watermark:水印。
    • subtitle:字幕。
    • material:素材。
    watermark
    Descriptionstring

    描述。

    测试
    AppIdstring

    应用 ID。

    app-****
    URLstring

    辅助媒资 URL。

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

    标题。

    测试
    Categoriesobject []

    分类 ID 列表。

    ParentIdlong

    父节点 ID。

    -1
    CateNamestring

    分类名称。

    测试
    CateIdlong

    分类 ID。

    10027394
    Levellong

    分类层级。

    1
    AiDataobject

    AI 详细信息。

    AiLabelInfoobject []

    AI 标签信息列表。

    Categorystring

    分类。

    交通工具
    LabelNamestring

    实体名称。

    LabelIdstring

    实体 ID。

    10310250338
    Occurrencesobject []

    片段列表。

    Scoredouble

    打分。

    0.75287705
    Fromdouble

    片段起始时间。

    1.4
    Todouble

    片段结束时间。

    2.5
    OcrInfoobject []

    字幕信息列表。

    Fromdouble

    片段起始时间。

    1.4
    Todouble

    片段结束时间。

    2.5
    Contentstring

    文本内容。

    我是皮皮
    AiRoughDataobject

    AI 简介数据。

    SaveTypestring

    保存类型。

    TEXT
    Statusstring

    数据状态。

    SaveSuccess
    AiJobIdstring

    AI 任务 ID。

    cd35b0b0025f71edbfcb472190a9xxxx
    AiCategorystring

    视频 AI 分类。

    电视剧

    示例

    正常返回示例

    JSON格式

    {
      "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": "视频测试",
            "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": "音频描述",
            "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": "音频",
            "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": "美图1",
            "Description": "图片测试",
            "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": "测试",
            "ModificationTime": "2018-07-19T03:48:25Z",
            "MediaId": "a82a2cd7d4e147ba0ed6c1ee372****",
            "BusinessType": "watermark",
            "Description": "测试",
            "AppId": "app-****",
            "URL": "https://example.com/****.png",
            "Title": "测试",
            "Categories": [
              {
                "ParentId": -1,
                "CateName": "测试",
                "CateId": 10027394,
                "Level": 1
              }
            ]
          },
          "AiData": {
            "AiLabelInfo": [
              {
                "Category": "交通工具",
                "LabelName": "车",
                "LabelId": "10310250338",
                "Occurrences": [
                  {
                    "Score": 0.75287705,
                    "From": 1.4,
                    "To": 2.5
                  }
                ]
              }
            ],
            "OcrInfo": [
              {
                "From": 1.4,
                "To": 2.5,
                "Content": "我是皮皮\n"
              }
            ]
          },
          "AiRoughData": {
            "SaveType": "TEXT\n",
            "Status": "SaveSuccess",
            "AiJobId": "cd35b0b0025f71edbfcb472190a9xxxx",
            "AiCategory": "电视剧\n"
          }
        }
      ]
    }

    错误码

    访问错误中心查看更多错误码。

    变更历史

    变更时间变更内容概要操作
    2023-04-11OpenAPI 返回结构发生变更看变更集
    变更项变更内容
    出参OpenAPI 返回结构发生变更

    接口错误码

    下表列举了本接口特有的错误码。

    错误代码错误信息HTTP 状态码说明
    SortByExceededMaxThe SortBy parameter only supports one sort field when traversing all data.400遍历所有数据时,仅支持一个排序字段。
    ErrorMatchSyntaxThe parameter Match.%s has an error syntax, please check it.400Match 参数语法错误,请检查后重试。
    InvalidScrollToken.ExpiredThe ScrollToken is expired,please refresh it.400翻页标识过期,请从第一页重新获取数据。
    • 本页导读 (1)