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:GenerateVideoPlaylist	none	*Project `acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}`	无	无

请求参数

名称	类型	必填	描述	示例值
ProjectName	string	是	项目名称，获取方式请参见创建项目。	immtest
UserData	string	否	用户自定义信息，在异步消息通知中会返回，方便您在系统内对消息通知进行关联处理。最大长度为 2048 字节。	{"ID": "user1","Name": "test-user1","Avatar": "http://example.com?id=user1"}
SourceURI	string	是	视频的 OSS 地址。 OSS 地址规则为 oss://${Bucket}/${Object}，其中${Bucket}为和当前项目处于同一区域(Region)的 OSS Bucket 名称，${Object}为包含文件扩展名的文件完整路径。说明只支持 OSS 标准存储 Bucket。不支持设置了防盗链白名单访问 bucket。	oss://test-bucket/test-source-object/video.mp4
SourceStartTime	float	否	生成播放列表的起始时间点，单位为秒（s）。取值范围如下： 0（默认）或不填表示从源视频起始时间点开始。大于 0 表示从源视频所设置的时间点开始。说明通过与参数 SourceDuration 一同设置可以对源视频的部分内容生成播放列表。	0
SourceDuration	float	否	生成播放列表的持续时间。单位为秒（s），取值范围如下： 0（默认）或不填表示持续到源视频结尾。大于 0 表示从生成播放列表的起始时间点持续所设置的时长。说明当设定参数所对应的时间点超过源视频结尾时按默认值处理。	0
SourceSubtitles	array<object>	否	添加字幕列表，默认为空。最大支持 2 个。
	object	否	字幕信息。
URI	string	是	被嵌入字幕的 OSS 地址。 OSS 地址规则为 oss://${Bucket}/${Object}，其中${Bucket}为和当前项目处于同一区域(Region)的 OSS Bucket 名称，${Object}为文件的完整路径。说明参数 MasterURI 必须不为空，并且被嵌入字幕的 OSS 地址`oss://${Bucket}/${Object}`必须处于参数 MasterURI 所在目录或它的子目录。	oss://test-bucket/test-object/subtitle/eng.vtt
Language	string	否	字幕语言，参考标准为 ISO 639-2，默认为空。	eng
MasterURI	string	否	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
Targets	array<object>	是	边转边播播放列表数组，数组长度最大为 6。每个 Target 对应至多一个视频 Media Playlist 和一个或多个字幕 Media Playlist 说明如果配置了大于一个 Target，参数 MasterURI 必须不为空。
	object	是	边转边播任务详细信息。
URI	string	否	边转边播输出文件的 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
Video	TargetVideo	否	视频处理参数配置，空值（默认）表示禁用视频处理，输出 ts 文件中将不包含视频流。说明同一 Target 内的 Video 和 Subtitle 字段互斥。如果设置了 Video 字段会忽略 Subtile 字段。
Audio	TargetAudio	否	音频处理参数配置，空值（默认）表示禁用音频处理，输出 ts 文件中将不包含音频流。说明同一 Target 内的 Audio 和 Subtitle 字段互斥。如果设置了 Audio 字段会忽略 Subtile 字段。Audio 和 Video 可以同时设置，Audio 表示输出视频中的音频信息。也可以只设置 Audio，只生成音频信息。
Subtitle	TargetSubtitle	否	字幕处理参数配置。说明同一 Target 内的 Subtile 和 Video 或 Audio 字段互斥，只有单独设置 Subtile 才能生成字幕。
TranscodeAhead	integer	否	触发边转边播时向前转码的 ts 文件数量。默认向前转码 2 分钟时长的视频。示例：Duraiton 为 10，则 TranscodeAhead 默认为 12。您可以指定该参数控制异步向前转码的数量，取值范围为[10,30]。	12
Duration	float	否	单个 ts 文件的播放时长。单位为秒（s），默认为 10，取值范围为[5,15]。	10
InitialTranscode	float	否	初始转码时长，单位为秒（s），默认值为 30。当所设置的时长为 0 时，不预装。当所设置的时长小于 0 或超过源视频长度时，将初始转码整段视频。当所设置的时长位于 ts 文件中间时，将持续转码到 ts 文件结束位置。说明该参数主要用于加快视频初次播放的等待时间，提升播放体验。若您需要替换传统 VOD 业务场景则可尝试初始转码整段视频。	30
InitialSegments	array	否	初始转码 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]
Tags	object	否	为生成的 ts 文件添加 OSS 对象标签。可以使用 OSS 标签来控制 OSS 文件的生命周期。说明当前标签值与上一级中定义的 Tags 取并集作为当前 Target 的标签值。如有同名，取当前值。
	string	否	标签值。	{\"key1\":\"value1\"}
Tags	object	否	为生成的 ts 文件添加 OSS 对象标签。可以使用标签来控制 OSS 文件的生命周期。
	string	否	标签值。	{"key1": "value1", "key2": "value2"}
CredentialConfig	CredentialConfig	否	如无特殊需求，请保持留空即可。链式授权配置，非必填。更多信息，请参见使用链式授权访问其他实体资源。
Notification	Notification	否	消息通知配置，详细内容请单击 Notification 查看，异步通知消息格式请参见异步通知消息格式。
OverwritePolicy	string	否	当 Media Playlist 存在时的覆盖策略，取值范围： overwrite（默认）：覆盖已经存在的 Media Playlist。 skip-existing：跳过生成，保留已经存在的 Media Playlist。	overwrite

返回参数

名称	类型	描述	示例值
	object	Schema of Response
RequestId	string	请求 ID。	CA995EFD-083D-4F40-BE8A-BDF75FFF*****
Duration	float	输出视频总时长。	1082
Token	string	Master Playlist 的 Token。	92376fbb-171f-4259-913f-705f7ee0****
MasterURI	string	Master Playlist 的 OSS 地址。	oss://test-bucket/test-object/master.m3u8
VideoPlaylist	array<object>	视频 Media Playlist 文件列表。
VideoPlaylist	object	视频 Media Playlist 文件信息。
Token	string	视频 Media Playlist 生成的 Token。可以使用该参数组装成 ts 文件生成的地址。说明根据返回的 Token 值，可以拼接出转码生成的 ts 地址。拼接格式为：oss://${Bucket}/${Object}-${Token}-${Index}.ts，其中 oss://${Bucket}/${Object}为输入参数的 Target URI 地址，${Token}为返回的参数，${Index}为 ts 的序号。	affe0c6042f09722fec95a21b8b******
URI	string	视频 Media Playlist 的 OSS 地址。	oss://test-bucket/test-object/output-video.m3u8
Resolution	string	视频分辨率。	640x480
FrameRate	string	视频帧率。	25/1
AudioPlaylist	array<object>	音频 Media Playlist 文件列表。
AudioPlaylist	object	音频 Media Playlist 文件信息。
Token	string	音频 Media Playlist 生成的 Token。可以使用该参数组装成 ts 文件生成的地址。	affe0c6042f09722fec95a21b8b******
URI	string	音频 Media Playlist 的 OSS 地址。	oss://test-bucket/test-object/output-audio.m3u8
Channels	integer	音频声道数量。	1
SubtitlePlaylist	array<object>	字幕 Media Playlist 文件列表。
SubtitlePlaylist	object	字幕 Media Playlist 文件信息。
Token	string	字幕 Media Playlist 生成的 Token。可以使用该参数组装成字幕文件生成的地址。说明根据返回的 Token 值，可以拼接出转码生成的字幕文件地址。拼接格式为：oss://${Bucket}/${Object}-${Token}_${Index}.ts，其中 oss://${Bucket}/${Object}为输入参数的 Subtitle URI 地址，${Token}为返回的参数，${Index}为字幕的序号。	affe0c6042f09722fec95a21b8b******
URI	string	字幕 Media Playlist 的 OSS 地址。	oss://test-bucket/test-object/output-subtitle.m3u8
Language	string	字幕流的语言。说明语言来源于 SourceURI 源视频的字幕流信息。如果源视频不存在语言信息，返回空值。	eng
Index	integer	字幕流编号，从 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-26	OpenAPI 返回结构发生变更	查看变更详情
2023-04-04	API 内部配置变更，不影响调用	查看变更详情