AI 助理
备案控制台
文档
输入文档关键字查找
首页 智能媒体管理 开发参考 API参考（2020-09-30） API目录 媒体处理 GenerateVideoPlaylist - 生成边转边播播放列表

GenerateVideoPlaylist - 生成边转边播播放列表

更新时间：
产品详情
我的收藏

创建边转边播播放列表能够将视频文件生成m3u8文件。生成播放列表后即时播放，并根据播放进度实施按需转码，相比离线转码能极大减少了转码等待时间并大幅度降低了转码和存储开销。

接口说明

  • 请确保在使用该接口前，已充分了解智能媒体管理产品的收费方式和价格。
  • 调用该接口前，请确保当前 Region 已经存在可用的项目（Project），详见项目管理。
  • 使用该接口时，默认只处理一路视频/音频/字幕流，同时支持配置处理的视频/音频/字幕流数量。
  • 该接口同时能支持生成 Media playlist 和 Master playlist，请注意文档参数说明。
  • 该接口为同步接口。播放或预转时才会触发同步或异步转码。可以通过设置 Notification 消息通知参数，通过消息通知获取转码任务结果。
  • 该接口的功能说明参见边转边播。
  • OSS 的数据处理能力也提供了生成播放列表功能，但只提供生成 Media Playlist 且参数进行了简化。详情参见 OSS 数据处理能力生成播放列表。

调试

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

授权信息

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

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

请求参数

名称类型必填描述示例值
ProjectNamestring是

项目名称，获取方式请参见创建项目。

immtest
UserDatastring否

用户自定义信息，在异步消息通知中会返回，方便您在系统内对消息通知进行关联处理。最大长度为 2048 字节。

{"ID": "user1","Name": "test-user1","Avatar": "http://example.com?id=user1"}
SourceURIstring是

视频的 OSS 地址。

OSS 地址规则为 oss://${Bucket}/${Object}，其中${Bucket}为和当前项目处于同一区域(Region)的 OSS Bucket 名称，${Object}为包含文件扩展名的文件完整路径。

说明 只支持 OSS 标准存储 Bucket。 不支持设置了防盗链白名单访问 bucket。
oss://test-bucket/test-source-object/video.mp4
SourceStartTimefloat否

生成播放列表的起始时间点，单位为秒（s）。取值范围如下：

  • 0（默认）或不填表示从源视频起始时间点开始。

  • 大于 0 表示从源视频所设置的时间点开始。

说明 通过与参数 SourceDuration 一同设置可以对源视频的部分内容生成播放列表。
0
SourceDurationfloat否

生成播放列表的持续时间。单位为秒（s），取值范围如下：

  • 0（默认）或不填表示持续到源视频结尾。

  • 大于 0 表示从生成播放列表的起始时间点持续所设置的时长。

说明 当设定参数所对应的时间点超过源视频结尾时按默认值处理。
0
SourceSubtitlesarray<object>否

添加字幕列表，默认为空。最大支持 2 个。

object否

字幕信息。

URIstring是

被嵌入字幕的 OSS 地址。

OSS 地址规则为 oss://${Bucket}/${Object}，其中${Bucket}为和当前项目处于同一区域(Region)的 OSS Bucket 名称，${Object}为文件的完整路径。

说明 参数 MasterURI 必须不为空，并且被嵌入字幕的 OSS 地址oss://${Bucket}/${Object}必须处于参数 MasterURI 所在目录或它的子目录。
oss://test-bucket/test-object/subtitle/eng.vtt
Languagestring否

字幕语言，参考标准为 ISO 639-2，默认为空。

eng
MasterURIstring否

Master Playlist 的 OSS 地址。

OSS 地址规则为 oss://${Bucket}/${Object}，其中${Bucket}为和当前项目处于同一区域(Region)的 OSS Bucket 名称，${Object}为带".m3u8"后缀名的文件完整路径。

说明 如果 Playlist 有字幕输入或有多 Target 输出，MasterURI 为必填，并且字幕 URI 或 Target URI 必须处于 MasterURI 所在目录或子目录。
oss://test-bucket/test-object/master.m3u8
Targetsarray<object>是

边转边播播放列表数组，数组长度最大为 6。每个 Target 对应至多一个视频 Media Playlist 和一个或多个字幕 Media Playlist

说明 如果配置了大于一个 Target，参数 MasterURI 必须不为空。
object是

边转边播任务详细信息。

URIstring否

边转边播输出文件的 OSS 地址前缀，输出文件包括 m3u8 文件和 ts 文件。

OSS 地址规则为 oss://${Bucket}/${Object}，其中${Bucket}为和当前项目处于同一地域的 OSS Bucket 名称，${Object}为不包含文件扩展名的文件完整路径前缀。

  • 示例：URI 为 oss://test-bucket/test-object/output-video，则将产生一个 oss://test-bucket/test-object/output-video.m3u8 文件以及多个 oss://test-bucket/test-object/output-video-${token}-${index}.ts 文件，其中${token}为根据转码参数生成的唯一字符串，在 API 返回结果中包含了${token}参数。${index}为生成的从 0 开始编号的 ts 文件序号。
说明 如果参数 MasterURI 不为空，URI 地址必须处于参数 MasterURI 所在目录或它的子目录。
oss://test-bucket/test-object/output-video
VideoTargetVideo否

视频处理参数配置，空值（默认）表示禁用视频处理，输出 ts 文件中将不包含视频流。

说明 同一 Target 内的 Video 和 Subtitle 字段互斥。如果设置了 Video 字段会忽略 Subtile 字段。
AudioTargetAudio否

音频处理参数配置，空值（默认）表示禁用音频处理，输出 ts 文件中将不包含音频流。

说明 同一 Target 内的 Audio 和 Subtitle 字段互斥。如果设置了 Audio 字段会忽略 Subtile 字段。Audio 和 Video 可以同时设置，Audio 表示输出视频中的音频信息。也可以只设置 Audio，只生成音频信息。
SubtitleTargetSubtitle否

字幕处理参数配置。

说明 同一 Target 内的 Subtile 和 Video 或 Audio 字段互斥，只有单独设置 Subtile 才能生成字幕。
TranscodeAheadinteger否

触发边转边播时向前转码的 ts 文件数量。默认向前转码 2 分钟时长的视频。

  • 示例：Duraiton 为 10，则 TranscodeAhead 默认为 12。您可以指定该参数控制异步向前转码的数量，取值范围为[10,30]。
12
Durationfloat否

单个 ts 文件的播放时长。单位为秒（s），默认为 10，取值范围为[5,15]。

10
InitialTranscodefloat否

初始转码时长，单位为秒（s），默认值为 30。

  • 当所设置的时长为 0 时，不预装。
  • 当所设置的时长小于 0 或超过源视频长度时，将初始转码整段视频。
  • 当所设置的时长位于 ts 文件中间时，将持续转码到 ts 文件结束位置。
说明 该参数主要用于加快视频初次播放的等待时间，提升播放体验。若您需要替换传统 VOD 业务场景则可尝试初始转码整段视频。
30
InitialSegmentsarray否

初始转码 ts 文件时长数组，数组长度最大为 6，默认为空，与参数 Duration 独立。

float否

初始转码 ts 文件时长，取值范围为[1,Duration]，

  • 示例：初始转码 ts 时长数组为[2, 2, 4, 4, 8, 8]，则序号为 0 的 ts 时长为 2，序号为 1 的 ts 时长为 2，序号为 2 的 ts 时长为 4，序号为 3 的 ts 时长为 4，序号为 4 的 ts 时长为 8，序号为 5 的 ts 时长为 8。
说明 自定义更小的初始转码 ts 文件时长可以让视频加载更加流畅。
[2, 2, 4, 4, 8, 8]
Tagsobject否

为生成的 ts 文件添加 OSS 对象标签。可以使用 OSS 标签来控制 OSS 文件的生命周期。

说明 当前标签值与上一级中定义的 Tags 取并集作为当前 Target 的标签值。如有同名，取当前值。
string否

标签值。

{\"key1\":\"value1\"}
Tagsobject否

为生成的 ts 文件添加 OSS 对象标签。可以使用标签来控制 OSS 文件的生命周期。

string否

标签值。

{"key1": "value1", "key2": "value2"}
CredentialConfigCredentialConfig否

如无特殊需求，请保持留空即可。

链式授权配置，非必填。更多信息，请参见使用链式授权访问其他实体资源。

NotificationNotification否

消息通知配置，详细内容请单击 Notification 查看，异步通知消息格式请参见异步通知消息格式。

OverwritePolicystring否

当 Media Playlist 存在时的覆盖策略，取值范围：

  • overwrite（默认）：覆盖已经存在的 Media Playlist。
  • skip-existing：跳过生成，保留已经存在的 Media Playlist。
overwrite

返回参数

名称类型描述示例值
object

Schema of Response

RequestIdstring

请求 ID。

CA995EFD-083D-4F40-BE8A-BDF75FFF*****
Durationfloat

输出视频总时长。

1082
Tokenstring

Master Playlist 的 Token。

92376fbb-171f-4259-913f-705f7ee0****
MasterURIstring

Master Playlist 的 OSS 地址。

oss://test-bucket/test-object/master.m3u8
VideoPlaylistarray<object>

视频 Media Playlist 文件列表。

VideoPlaylistobject

视频 Media Playlist 文件信息。

Tokenstring

视频 Media Playlist 生成的 Token。可以使用该参数组装成 ts 文件生成的地址。

说明 根据返回的 Token 值，可以拼接出转码生成的 ts 地址。拼接格式为：oss://${Bucket}/${Object}-${Token}-${Index}.ts，其中 oss://${Bucket}/${Object}为输入参数的 Target URI 地址，${Token}为返回的参数，${Index}为 ts 的序号。
affe0c6042f09722fec95a21b8b******
URIstring

视频 Media Playlist 的 OSS 地址。

oss://test-bucket/test-object/output-video.m3u8
Resolutionstring

视频分辨率。

640x480
FrameRatestring

视频帧率。

25/1
AudioPlaylistarray<object>

音频 Media Playlist 文件列表。

AudioPlaylistobject

音频 Media Playlist 文件信息。

Tokenstring

音频 Media Playlist 生成的 Token。可以使用该参数组装成 ts 文件生成的地址。

affe0c6042f09722fec95a21b8b******
URIstring

音频 Media Playlist 的 OSS 地址。

oss://test-bucket/test-object/output-audio.m3u8
Channelsinteger

音频声道数量。

1
SubtitlePlaylistarray<object>

字幕 Media Playlist 文件列表。

SubtitlePlaylistobject

字幕 Media Playlist 文件信息。

Tokenstring

字幕 Media Playlist 生成的 Token。可以使用该参数组装成字幕文件生成的地址。

说明 根据返回的 Token 值，可以拼接出转码生成的字幕文件地址。拼接格式为：oss://${Bucket}/${Object}-${Token}_${Index}.ts，其中 oss://${Bucket}/${Object}为输入参数的 Subtitle URI 地址，${Token}为返回的参数，${Index}为字幕的序号。
affe0c6042f09722fec95a21b8b******
URIstring

字幕 Media Playlist 的 OSS 地址。

oss://test-bucket/test-object/output-subtitle.m3u8
Languagestring

字幕流的语言。

说明 语言来源于 SourceURI 源视频的字幕流信息。如果源视频不存在语言信息，返回空值。
eng
Indexinteger

字幕流编号，从 0 开始。

1

示例

正常返回示例

JSON格式

{
  "RequestId": "CA995EFD-083D-4F40-BE8A-BDF75FFF*****",
  "Duration": 1082,
  "Token": "92376fbb-171f-4259-913f-705f7ee0****",
  "MasterURI": "oss://test-bucket/test-object/master.m3u8",
  "VideoPlaylist": [
    {
      "Token": "affe0c6042f09722fec95a21b8b******",
      "URI": "oss://test-bucket/test-object/output-video.m3u8",
      "Resolution": "640x480",
      "FrameRate": "25/1"
    }
  ],
  "AudioPlaylist": [
    {
      "Token": "affe0c6042f09722fec95a21b8b******",
      "URI": "oss://test-bucket/test-object/output-audio.m3u8",
      "Channels": 1
    }
  ],
  "SubtitlePlaylist": [
    {
      "Token": "affe0c6042f09722fec95a21b8b******",
      "URI": "oss://test-bucket/test-object/output-subtitle.m3u8",
      "Language": "eng",
      "Index": 1
    }
  ]
}

错误码

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

变更历史

变更时间变更内容概要操作
2024-03-26OpenAPI 返回结构发生变更查看变更详情
2023-04-04API 内部配置变更，不影响调用查看变更详情
上一篇：GetVideoLabelClassificationResult - 获取视频标签检测任务下一篇：文档处理
文档推荐