Queries media files based on their Object Storage Service (OSS) URLs.

Usage notes

You can call this operation to query up to 10 media files at a time.

QPS limit

You can call this operation up to 100 times per second per account. If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation. For more information, see QPS limits.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes QueryMediaListByURL

The operation that you want to perform. Set the value to QueryMediaListByURL.

FileURLs String Yes http://example-bucket-****.oss-cn-shanghai.aliyuncs.com/example.mp4

The OSS URLs of the media files. To obtain the OSS URL of a media file, you can perform the following operations in the ApsaraVideo Media Processing (MPS) console: In the left-side navigation pane, choose Media Management > Media List. Find the required video and click Manage. The OSS URL of the video is displayed on the Obtain Encoding URL tab. Separate multiple URLs with commas (,). You can query up to 10 media files at a time.

  • The URLs comply with RFC 3986 and are encoded in UTF-8, with reserved characters being percent-encoded. The value can be up to 3,200 bytes in size.
  • Only OSS HTTP URLs are supported. Alibaba Cloud CDN URLs and HTTPS URLs are not supported.
IncludePlayList Boolean No true

Specifies whether to include playback information in the returned result.

  • Valid values: true and false.
  • Default value: false.
IncludeSnapshotList Boolean No true

Specifies whether to include snapshot information in the returned result.

  • Valid values: true and false.
  • Default value: false.
IncludeMediaInfo Boolean No true

Specifies whether to include media information in the returned result.

  • Valid values: true and false.
  • Default value: false.
IncludeSummaryList Boolean No true

Specifies whether to include summaries in the returned result.

  • Valid values: true and false.
  • Default value: false.

Response parameters

Parameter Type Example Description
MediaList Array of Media

The list of media files.

Media
CreationTime String 2021-07-14T13:05:00Z

The time when the media file was created.

CateId Long 123

The ID of the category to which the media file belongs.

Height String 360

The height of the queried media file.

CensorState String Initiated

The review status of the media file. Valid values:

  • Initiated: The media file is uploaded but not reviewed.
  • Pass: The media file is uploaded and passes the review.
Tags Array of String tag1,tag2

The tags of the media file.

PlayList Array of Play

The playlist.

Play
Encryption String 1

Indicates whether the media file is encrypted. Valid values:

  • 0: The media file is not encrypted.
  • 1: The media file is encrypted.
Height String 10

The height of the media file.

Bitrate String 25.067

The bitrate of the media file.

File Object

The playback file.

State String Normal

The status of the media file. Valid values:

  • Normal: normal
  • Deleted: deleted
URL String http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com//example-****.mp4l-test/in/1.mp4

The OSS URL of the playback file.

MediaWorkflowId String 6cc3aa66d1cb4bb2adf14e726c0a****

The ID of the workflow that generates the playback file.

Width String 11

The width.

Size String 100

The size.

Fps String 25.0

The frame rate.

Duration String 7.965000

The duration.

ActivityName String test name

The name of the workflow activity.

Format String mov

The encoding format. Valid values: mov, mp4, m4a, 3gp, 3g2, and mj2.

MediaWorkflowName String example-mediaworkflow-****

The name of the workflow that generates the playback file.

Bitrate String 593.192

The bitrate.

MediaId String 52d7e98b05e648199612290bb819****

The ID of the media file.

File Object

The details of the input file.

State String Normal

The status of the input file. Valid values:

  • Normal: normal
  • Deleted: deleted
URL String http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com//example-****.mp4

The OSS URL of the input file.

SummaryList Array of Summary

The list of video summaries.

Summary
Type String Gif

The type of the summary. Valid values:

  • Video: video
  • Gif: dynamic image
MediaWorkflowId String 93ab850b4f6f44eab54b6e91d24d****

The ID of the workflow that generates the summary.

ActivityName String example-activity-****

The name of the workflow activity.

MediaWorkflowName String example-mediaworkflow-****

The name of the workflow that generates the summary.

File Object

The information about the input file.

State String Normal

The status of the input file. Valid values:

  • Normal: normal
  • Deleted: deleted
URL String http://example-bucket-****.o

The OSS URL of the input file.

PublishState String Published

The publishing status of the media file. Valid values:

  • Initiated: The media file is in the initial state.
  • UnPublish: The media file has not been published, and the playback permission on the OSS object is Private.
  • Published: The media file has been published, and the playback permission on the OSS object is Default.
  • Deleted: The media file has been deleted.
MediaInfo Object

The media information.

Streams Object

The stream information.

VideoStreamList Array of VideoStream

The list of video streams.

VideoStream
Sar String 1:1

The sample aspect ratio (SAR).

Height String 360

The latter number in the video resolution. The number indicates the video height.

CodecTagString String avc1

The tag string of the encoding format.

NetworkCost Object

The network bandwidth consumption.

PreloadTime String 0.01

The amount of preload time.

AvgBitrate String 2659.326

The average bitrate.

CostBandwidth String 100

The maximum bandwidth that was consumed.

Width String 640

The former number in the video resolution. The number indicates the video width and cannot be negative.

Index String 5

The sequence number of the video stream. The value indicates the position of the video stream in all video streams.

Timebase String 1/15360

The time base.

AvgFPS String 15.0

The average frame rate.

PixFmt String yuv420p

The pixel format.

Lang String und

The language. For more information, see FFmpeg documentation.

CodecLongName String H.264/AVC/MPEG-4 AVC/MPEG-4 part 10

The full name of the encoding format.

NumFrames String 12

The total number of frames.

Rotate String 90

The video rotation angle.

Bitrate String 512.701

The bitrate.

HasBFrames String 2

Indicates whether the video stream contains bidirectional frames (B-frames). A value of 1 indicates that the video stream contains B-frames. A value of 2 indicates that the video stream does not contain B-frames.

Profile String High

The codec profile.

StartTime String 0.046029

The start time.

Dar String 16:9

The display aspect ratio (DAR).

CodecName String H264

The short name of the encoding format. Valid values: H264, mov, aac, avc, and mpeg.

Duration String 79.200000

The duration.

Fps String 15.0

The frame rate.

CodecTag String 0x31637661

The tag of the encoding format.

CodecTimeBase String 1/30

The codec time base.

Level String 31

The codec level.

AudioStreamList Array of AudioStream

The list of audio streams.

AudioStream
Timebase String 1/44100

The time base.

Index String 1

The sequence number of the audio stream. The value indicates the position of the audio stream in all audio streams.

SampleFmt String fltp

The sampling format.

ChannelLayout String stereo

The output layout of the sound channels.

Lang String und

The language. For more information, see FFmpeg language definition.

Samplerate String 44100

The sampling rate.

CodecLongName String AAC (Advanced Audio Coding)

The full name of the encoding format.

Channels String 2

The number of sound channels.

NumFrames String 100

The total number of frames.

Bitrate String 76.356

The bitrate.

CodecTagString String mp4a

The tag string of the encoding format.

StartTime String 0.000000

The start time.

CodecName String aac

The short name of the encoding format. Valid values: H264, mov, aac, avc, and mpeg.

Duration String 79.203265

The duration.

CodecTag String 0x6134706d

The tag of the encoding format.

CodecTimeBase String 1/44100

The codec time base.

SubtitleStreamList Array of SubtitleStream

The list of subtitle streams.

SubtitleStream
Index String 1

The sequence number of the subtitle stream. The value indicates the position of the subtitle stream in all subtitle streams.

Lang String und

The language. For more information, see FFmpeg language definition.

Format Object

The format information.

StartTime String 0.000000

The start time.

NumPrograms String 0

The total number of program streams.

Size String 5872904

The size.

NumStreams String 2

The total number of media streams.

FormatLongName String QuickTime/MOV

The full name of the encoding format.

Duration String 79.204000

The duration.

Bitrate String 593.192

The bitrate.

FormatName String mov

The short name of the container format. Valid values: mov, mp4, m4a, 3gp, 3g2, and mj2.

Description String This is description ****

The description.

Size String 5872904

The size of the file.

Width String 640

The width.

CoverURL String http://example-bucket1-****.oss-cn-hangzhou.aliyuncs.com//example-****.png

The OSS URL of the thumbnail.

SnapshotList Array of Snapshot

The list of snapshots.

Snapshot
Type String Single

The type of the snapshot. Valid values:

  • Single
  • Sequence
MediaWorkflowId String 6cc3aa66d1cb4bb2adf14e726c0a****

The ID of the workflow that generates the snapshot.

ActivityName String example-activity1-****

The name of the workflow activity that generates the snapshot.

Count String 3

The number of snapshots. This parameter is valid only when the value of the Type parameter is Sequence.

MediaWorkflowName String example-workflow-****

The name of the workflow that generates the snapshot.

File Object

The snapshot.

State String Normal

The status of the file. Valid values:

  • Normal: normal
  • Deleted: deleted
URL String http://example1-bucket1-****.oss-cn-hangzhou.aliyuncs.com//example111-****.png

The OSS URL of the snapshot.

RunIdList Array of String 9343bd0e7bb54ae19228529908e5****

The IDs of the media workflow execution instances.

Duration String 79.204000

The duration.

Fps String 15.0

The frame rate.

Title String kled.mp4

The title.

Format String mov

The encoding format. Valid values: mov, mp4, m4a, 3gp, 3g2, and mj2.

NonExistFileURLs Array of String null

The IDs of the media files that do not exist. This parameter is not returned if all specified media files exist.

RequestId String 1C8A0AEB-4321-485B-B4CB-DA4E9E6C9B42

The ID of the request.

Examples

Sample requests

http(s)://mts.cn-hangzhou.aliyuncs.com/?Action=QueryMediaListByURL
&FileURLs=http://example-bucket-****.oss-cn-shanghai.aliyuncs.com/example.mp4
&IncludePlayList=true
&IncludeSnapshotList=true
&IncludeMediaInfo=true
&IncludeSummaryList=true
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<QueryMediaListByURLResponse>
    <MediaList>
        <CreationTime>2021-07-14T13:05:00Z</CreationTime>
        <CateId>123</CateId>
        <Height>360</Height>
        <CensorState>Initiated</CensorState>
        <Tags>tag1,tag2</Tags>
        <PlayList>
            <Encryption>1</Encryption>
            <Height>10</Height>
            <Bitrate>25.067</Bitrate>
            <File>
                <State>Normal</State>
                <URL>http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com//example-****.mp4l-test/in/1.mp4</URL>
            </File>
            <MediaWorkflowId>6cc3aa66d1cb4bb2adf14e726c0a****</MediaWorkflowId>
            <Width>11</Width>
            <Size>100</Size>
            <Fps>25.0</Fps>
            <Duration>7.965000</Duration>
            <ActivityName>test name</ActivityName>
            <Format>mov</Format>
            <MediaWorkflowName>example-mediaworkflow-****</MediaWorkflowName>
        </PlayList>
        <Bitrate>593.192</Bitrate>
        <MediaId>52d7e98b05e648199612290bb819****</MediaId>
        <File>
            <State>Normal</State>
            <URL>http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com//example-****.mp4</URL>
        </File>
        <SummaryList>
            <Type>Gif</Type>
            <MediaWorkflowId>93ab850b4f6f44eab54b6e91d24d****</MediaWorkflowId>
            <ActivityName>example-activity-****</ActivityName>
            <MediaWorkflowName>example-mediaworkflow-****</MediaWorkflowName>
            <File>
                <State>Normal</State>
                <URL>http://example-bucket-****.o</URL>
            </File>
        </SummaryList>
        <PublishState>Published</PublishState>
        <MediaInfo>
            <Streams>
                <VideoStreamList>
                    <Sar>1:1</Sar>
                    <Height>360</Height>
                    <CodecTagString>avc1</CodecTagString>
                    <NetworkCost>
                        <PreloadTime>0.01</PreloadTime>
                        <AvgBitrate>2659.326</AvgBitrate>
                        <CostBandwidth>100</CostBandwidth>
                    </NetworkCost>
                    <Width>640</Width>
                    <Index>5</Index>
                    <Timebase>1/15360</Timebase>
                    <AvgFPS>15.0</AvgFPS>
                    <PixFmt>yuv420p</PixFmt>
                    <Lang>und</Lang>
                    <CodecLongName>H.264/AVC/MPEG-4 AVC/MPEG-4 part 10</CodecLongName>
                    <NumFrames>12</NumFrames>
                    <Rotate>90</Rotate>
                    <Bitrate>512.701</Bitrate>
                    <HasBFrames>2</HasBFrames>
                    <Profile>High</Profile>
                    <StartTime>0.046029</StartTime>
                    <Dar>16:9</Dar>
                    <CodecName>H264</CodecName>
                    <Duration>79.200000</Duration>
                    <Fps>15.0</Fps>
                    <CodecTag>0x31637661</CodecTag>
                    <CodecTimeBase>1/30</CodecTimeBase>
                    <Level>31</Level>
                </VideoStreamList>
                <AudioStreamList>
                    <Timebase>1/44100</Timebase>
                    <Index>1</Index>
                    <SampleFmt>fltp</SampleFmt>
                    <ChannelLayout>stereo</ChannelLayout>
                    <Lang>und</Lang>
                    <Samplerate>44100</Samplerate>
                    <CodecLongName>AAC (Advanced Audio Coding)</CodecLongName>
                    <Channels>2</Channels>
                    <NumFrames>100</NumFrames>
                    <Bitrate>76.356</Bitrate>
                    <CodecTagString>mp4a</CodecTagString>
                    <StartTime>0.000000</StartTime>
                    <CodecName>aac</CodecName>
                    <Duration>79.203265</Duration>
                    <CodecTag>0x6134706d</CodecTag>
                    <CodecTimeBase>1/44100</CodecTimeBase>
                </AudioStreamList>
                <SubtitleStreamList>
                    <Index>1</Index>
                    <Lang>und</Lang>
                </SubtitleStreamList>
            </Streams>
            <Format>
                <StartTime>0.000000</StartTime>
                <NumPrograms>0</NumPrograms>
                <Size>5872904</Size>
                <NumStreams>2</NumStreams>
                <FormatLongName>QuickTime/MOV</FormatLongName>
                <Duration>79.204000</Duration>
                <Bitrate>593.192</Bitrate>
                <FormatName>mov</FormatName>
            </Format>
        </MediaInfo>
        <Description>This is description ****</Description>
        <Size>5872904</Size>
        <Width>640</Width>
        <CoverURL>http://example-bucket1-****.oss-cn-hangzhou.aliyuncs.com//example-****.png</CoverURL>
        <SnapshotList>
            <Type>Single</Type>
            <MediaWorkflowId>6cc3aa66d1cb4bb2adf14e726c0a****</MediaWorkflowId>
            <ActivityName>example-activity1-****</ActivityName>
            <Count>3</Count>
            <MediaWorkflowName>example-workflow-****</MediaWorkflowName>
            <File>
                <State>Normal</State>
                <URL>http://example1-bucket1-****.oss-cn-hangzhou.aliyuncs.com//example111-****.png</URL>
            </File>
        </SnapshotList>
        <RunIdList>9343bd0e7bb54ae19228529908e5****</RunIdList>
        <Duration>79.204000</Duration>
        <Fps>15.0</Fps>
        <Title>kled.mp4</Title>
        <Format>mov</Format>
    </MediaList>
    <NonExistFileURLs>null</NonExistFileURLs>
    <RequestId>1C8A0AEB-4321-485B-B4CB-DA4E9E6C9B42</RequestId>
</QueryMediaListByURLResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "MediaList" : [ {
    "CreationTime" : "2021-07-14T13:05:00Z",
    "CateId" : 123,
    "Height" : "360",
    "CensorState" : "Initiated",
    "Tags" : [ "tag1,tag2" ],
    "PlayList" : [ {
      "Encryption" : "1",
      "Height" : "10",
      "Bitrate" : "25.067",
      "File" : {
        "State" : "Normal",
        "URL" : "http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com//example-****.mp4l-test/in/1.mp4"
      },
      "MediaWorkflowId" : "6cc3aa66d1cb4bb2adf14e726c0a****",
      "Width" : "11",
      "Size" : "100",
      "Fps" : "25.0",
      "Duration" : "7.965000",
      "ActivityName" : "test name",
      "Format" : "mov",
      "MediaWorkflowName" : "example-mediaworkflow-****"
    } ],
    "Bitrate" : "593.192",
    "MediaId" : "52d7e98b05e648199612290bb819****",
    "File" : {
      "State" : "Normal",
      "URL" : "http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com//example-****.mp4"
    },
    "SummaryList" : [ {
      "Type" : "Gif",
      "MediaWorkflowId" : "93ab850b4f6f44eab54b6e91d24d****",
      "ActivityName" : "example-activity-****",
      "MediaWorkflowName" : "example-mediaworkflow-****",
      "File" : {
        "State" : "Normal",
        "URL" : "http://example-bucket-****.o"
      }
    } ],
    "PublishState" : "Published",
    "MediaInfo" : {
      "Streams" : {
        "VideoStreamList" : [ {
          "Sar" : "1:1",
          "Height" : "360",
          "CodecTagString" : "avc1",
          "NetworkCost" : {
            "PreloadTime" : "0.01",
            "AvgBitrate" : "2659.326",
            "CostBandwidth" : "100"
          },
          "Width" : "640",
          "Index" : "5",
          "Timebase" : "1/15360",
          "AvgFPS" : "15.0",
          "PixFmt" : "yuv420p",
          "Lang" : "und",
          "CodecLongName" : "H.264/AVC/MPEG-4 AVC/MPEG-4 part 10",
          "NumFrames" : "12",
          "Rotate" : "90",
          "Bitrate" : "512.701",
          "HasBFrames" : "2",
          "Profile" : "High",
          "StartTime" : "0.046029",
          "Dar" : "16:9",
          "CodecName" : "H264",
          "Duration" : "79.200000",
          "Fps" : "15.0",
          "CodecTag" : "0x31637661",
          "CodecTimeBase" : "1/30",
          "Level" : "31"
        } ],
        "AudioStreamList" : [ {
          "Timebase" : "1/44100",
          "Index" : "1",
          "SampleFmt" : "fltp",
          "ChannelLayout" : "stereo",
          "Lang" : "und",
          "Samplerate" : "44100",
          "CodecLongName" : "AAC (Advanced Audio Coding)",
          "Channels" : "2",
          "NumFrames" : "100",
          "Bitrate" : "76.356",
          "CodecTagString" : "mp4a",
          "StartTime" : "0.000000",
          "CodecName" : "aac",
          "Duration" : "79.203265",
          "CodecTag" : "0x6134706d",
          "CodecTimeBase" : "1/44100"
        } ],
        "SubtitleStreamList" : [ {
          "Index" : "1",
          "Lang" : "und"
        } ]
      },
      "Format" : {
        "StartTime" : "0.000000",
        "NumPrograms" : "0",
        "Size" : "5872904",
        "NumStreams" : "2",
        "FormatLongName" : "QuickTime/MOV",
        "Duration" : "79.204000",
        "Bitrate" : "593.192",
        "FormatName" : "mov"
      }
    },
    "Description" : "This is description ****",
    "Size" : "5872904",
    "Width" : "640",
    "CoverURL" : "http://example-bucket1-****.oss-cn-hangzhou.aliyuncs.com//example-****.png",
    "SnapshotList" : [ {
      "Type" : "Single",
      "MediaWorkflowId" : "6cc3aa66d1cb4bb2adf14e726c0a****",
      "ActivityName" : "example-activity1-****",
      "Count" : "3",
      "MediaWorkflowName" : "example-workflow-****",
      "File" : {
        "State" : "Normal",
        "URL" : "http://example1-bucket1-****.oss-cn-hangzhou.aliyuncs.com//example111-****.png"
      }
    } ],
    "RunIdList" : [ "9343bd0e7bb54ae19228529908e5****" ],
    "Duration" : "79.204000",
    "Fps" : "15.0",
    "Title" : "kled.mp4",
    "Format" : "mov"
  } ],
  "NonExistFileURLs" : [ "null" ],
  "RequestId" : "1C8A0AEB-4321-485B-B4CB-DA4E9E6C9B42"
}

Error codes

For a list of error codes, visit the API Error Center.