文档中心

获取播放地址

最近更新时间：2024.01.25 15:56:45

首次发布时间：2021.02.23 10:42:37

此接口用于通过 Vid 获取播放地址。

使用说明

您可以通过指定封装格式、编码格式、清晰度等参数，获取所需的播放地址。

注意事项

请求频率：单用户请求频率限制为 1000 次/秒。

请求说明

请求地址：https://vod.volcengineapi.com?Action=GetPlayInfo&Version=2020-08-01

调试

API Explorer

您可以通过API Explorer在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

参数	类型	是否必选	示例值	描述
Action	String	是	`GetPlayInfo`	接口名称。当前 API 的名称为 `GetPlayInfo`。
Version	String	是	`2020-08-01`	接口版本。当前 API 的版本为 `2020-08-01`。
Vid	String	是	`v029c1g10003civ2i5mqib*******`	音视频 ID。音视频上传后，获取 `Vid` 的方式如下所示。通过 GetMediaList 接口获取 `Vid`。如果您设置了媒资上传完成的回调事件，会在 FileUploadComplete 中返回 `Vid`。
Format	String	否	`mp4`	封装格式。当 `FileType` 为视频时，默认为 `mp4`。取值如下： `mp4` `dash` `hls` 当 `FileType` 为音频时，默认为 `m4a`。取值如下： `m4a` `mp4` `mp3` `dash` `hls` `ogg`
Codec	String	否	`H265`	编码格式。当 `FileType` 为视频时，默认为 `H264`。取值如下： `H264` `H265` `H266` 当 `FileType` 为音频时，默认为 `aac`。取值如下： `aac`（含 heaacv2） `mp3` `opus` 说明如果采用 `Vid+PlayAuthToken` 播放方式，建议服务端生成 `PlayAuthToken` 时，不要指定编码格式。客户端播放请求时，点播服务会根据策略自动灵活选择 H.264 或 H.265。如需使用 H.266 编码，请提交工单联系技术支持开通。
Definition	String	否	`1080p`	视频流清晰度。仅当 `FileType` 为 `video` 和 `evideo` 时生效。如不传 `Definition`，则默认返回全部清晰度的视频地址。取值如下： `240p` `360p` `480p` `540p` `720p` `1080p` `2k` `4k` `od`（原画转封装） `oe`（画质增强）说明当 `Definition` 参数取值为 `oe` 时，没有对应 `oe` 下发的话会返回空列表。当 `Definition` 和 `HDRDefinition` 参数取值都为 `oe` 时, 会取结果的并集，如果都没有 `oe` 则返回空列表。
FileType	String	否	`video`	流文件类型。取值如下： `evideo`：加密视频流。 `eaudio`：加密音频流。 `video`：（默认）非加密视频流。 `audio`：普通音频流。
LogoType	String	否	`aa`	水印贴片标签。您可在点播控制台创建水印贴片模板时设置水印贴片标签，详见水印贴片模板。
Ssl	String	否	`1`	是否返回 HTTPS 播放地址。取值如下： `1`：是。 `0`：（默认）否。
NeedThumbs	String	否	`0`	是否返回雪碧图。取值如下： `1`：是。 `0`：（默认）否。
NeedBarrageMask	String	否	`0`	是否需要蒙版弹幕。取值如下： `1`：是。 `0`：（默认）否。
UnionInfo	String	否	`8988***`	加密视频和加密音频时使用，播放端从浏览器或设备中取出能够标识访问或设备唯一性的信息。详情请见私有 DRM 加密。
HDRDefinition	String	否	`1080p`	查询 HDR 清晰度。默认为不查询 HDR 清晰度。取值如下： `240p` `360p` `480p` `540p` `720p` `1080p` `2k` `4k` `oe`（画质增强）说明当 `HDRDefinition` 参数取值为 `oe` 时，没有对应 `oe` 下发的话会返回空列表。当 `Definition` 和 `HDRDefinition` 参数取值都为 `oe` 时, 会取结果的并集，如果都没有 `oe` 则返回空列表。
PlayScene	String	否	`preview`	播放场景。指定获取对应场景的音视频流。当前仅支持设为 `preview`，表示试看场景，详见点播试看说明。
DrmExpireTimestamp	String	否	`1695037103`	加密视频和加密音频时使用，DRM 过期时间戳。Unix 时间戳，单位为秒。
Quality	String	否	`higher`	音频音质参数。仅当 `FileType` 为 `audio` 和 `eaudio` 时生效。如不传 `Quality`，默认返回全部音质的音频地址。取值如下： `medium`：普通音质。 `higher`：高音质。 `highest`：音乐音质。
PlayConfig	String	否	`{"PlayDomain":"vod.test_domain"}`	自定义播放配置。为 JSON 字符串，支持指定播放域名。例如：`{"PlayDomain":"vod.test_domain"}` 说明如果您设置了 `PlayConfig` 且其中的 `PlayDomain` 有效，点播服务会使用您传入的 `PlayDomain` 下发播放地址。如果您未设置 `PlayConfig` 和其中的 `PlayDomain`，或者 `PlayDomain` 无效，点播服务会使用您在点播控制台分发加速设置 > 域名设置页面设置的默认域名下发播放地址。如果您没有设置默认域名，则会在启用的播放域名中随机分发。为防止点播服务返回的不是您想要的域名，建议您设置默认播放域名，详见域名设置。
NeedOriginal	String	否	`0`	是否返回原视频信息。取值如下： `1`：是。 `0`：（默认）否。
ForceExpire	String	否	`60`	强行指定本次请求的时间戳防盗链，单位为秒，取值范围为 [60,315360000]。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数	类型	示例值	描述
Vid	String	`v029c1g10003civ2i5mqib*******`	音视频 ID。
Status	Integer	`10`	视频状态，取值如下： `10`：请求成功。其他数值均表示视频无法播放。可能返回以下数值： `1000`：视频未发布，不可播放。 `1010`：视频已被删除。
PosterUrl	String	`https://img.*.com/1234/8511abe**.jpeg`	封面地址。
Duration	Float	`0.1`	播放时长，单位为秒。
FileType	String	`video`	流文件类型。
EnableAdaptive	Boolean	`false`	是否关键帧对齐。取值如下： `true`：是。 `false`：否。
TotalCount	Integer	`1`	播放列表数量。
PlayInfoList	Array of PlayInfoList	`-`	播放列表。
ThumbInfoList	Array of ThumbInfoList	`-`	雪碧图列表。
BarrageMaskUrl	String	`http://**.com/460224cfc86a9177b80b**********`	蒙版弹幕 URL。
SubtitleInfoList	Array of SubtitleInfoList	`-`	字幕信息列表。
BarrageMaskInfo	Object of BarrageMaskInfo	`-`	蒙版弹幕信息。

PlayInfoList

参数	类型	示例值	描述
FileId	String	`v029c1g10003civ2i5mqib*******`	文件 ID。
Md5	String	`398e352f8342aa29a6feee2a18e*****`	哈希值。
FileType	String	`video`	文件类型，取值如下： `video` `audio`
Definition	String	`1080p`	视频分辨率。
Quality	String	`normal`	音频质量，取值如下： `medium`：普通音质 `higher`：高音质 `highest`：音乐音质
Format	String	`mp4`	视频格式。
Codec	String	`H265`	编码类型。
LogoType	String	`default`	水印贴片标签。
MainPlayUrl	String	`http://video.*.com/oIpB7fCZQ2ttbMe4Iklnvx******`	主播放地址。
BackupPlayUrl	String	`http://video.*.com/oIpB7fCZQ2ttbMe4Iklnvx******`	备用播放地址。
Bitrate	Integer	`1381635`	码率，单位为 bps。
Width	Integer	`1920`	视频宽度。
Height	Integer	`1080`	视频高度。
Size	Double	`1653067`	文件大小。
CheckInfo	String	`"a:v029c1g10003civ2i5mqib*****\|b:0-983-ac368d50ea39b160****\|c:0-983-**"`	劫持校验信息。
IndexRange	String	`974-1089`	DASH segment_base 分片信息，用以描述 sidx（分段索引）的范围。
InitRange	String	`0-973`	DASH segment_base 分片信息，用以描述头信息的范围。
PlayAuth	String	`****`	加密过的密钥。
PlayAuthId	String	`****`	密钥 KeyID。
BarrageMaskOffset	String	`100`	蒙版弹幕偏移量。
Volume	Object of Volume	`-`	音量均衡响度信息。说明无对应的请求字段，有数据则下发。
MainUrlExpire	String	`1690534212`	主播放 URL 过期时间。
BackupUrlExpire	String	`1690534212`	备用播放 URL 过期时间。

ThumbInfoList

参数	类型	示例值	描述
CaptureNum	Integer	`1`	包含的截图总数。
StoreUrls	Array of String	`[]`	雪碧图 URL 列表。
CellWidth	Integer	`1`	小图宽。
CellHeight	Integer	`1`	小图高。
ImgXLen	Integer	`1`	雪碧图每行包含的小图数量。
ImgYLen	Integer	`1`	雪碧图每列包含的小图数量。
Interval	Double	`0.1`	截图间隔。
Format	String	`jpg`	图片格式，取值为 `jpg`。

SubtitleInfoList

参数	类型	示例值	描述
Vid	String	`v029c1g10003civ2i5mqib*******`	视频 ID。
FileId	String	`v029c1g10003civ2i5mqib*******`	文件 ID。
Language	String	`eng-US`	字幕语言。
LanguageId	Integer	`1`	字幕语言 ID。
Format	String	`webvtt`	字幕格式。
SubtitleId	String	`123`	字幕 ID。
Title	String	`subtitle.vtt`	字幕标题。
Tag	String	`subtitle`	字幕标签。
Status	String	`enable`	字幕状态。
Source	String	`MU`	字幕来源。
StoreUri	String	`tos-vod-cn-**/191fe22a1c4a49189a69**********`	存储 URL。
SubtitleUrl	String	`http://**.com/191fe22a1c4a49189a69**********`	字幕 URL。
CreateTime	String	`2019-10-12T07:20:50.52Z`	创建时间。
Version	String	`1`	字幕版本。

BarrageMaskInfo

参数	类型	示例值	描述
Version	String	`v1`	蒙版弹幕版本，取值如下： `V1` `V2`
BarrageMaskUrl	String	`http://**.com/460224cfc86a9177b80b**********`	蒙版弹幕 URL。
FileId	String	`v029c1g10003civ2i5mqib*******`	蒙版弹幕文件 ID。
FileSize	Double	`1`	蒙版弹幕文件大小。
FileHash	String	`c2e595ab2db511daf6fc************`	蒙版弹幕文件哈希值。
UpdatedAt	String	`1676017784`	蒙版弹幕文件更新日期。
Bitrate	Integer	`1`	蒙版弹幕文件码率。
HeadLen	Double	`1`	蒙版弹幕文件头部大小。

Volume

参数	类型	示例值	描述
Loudness	Double	`0.1`	音量响度
Peak	Double	`0.1`	音量峰值

请求示例

https://vod.volcengineapi.com?Action=GetPlayInfo&Version=2020-08-01&Codec=H265&Definition=1080p&DrmExpireTimestamp=1695037103&FileType=video&Format=mp4&HDRDefinition=1080p&LogoType=&NeedBarrageMask=0&NeedOriginal=0&NeedThumbs=0&PlayConfig=%7B%22PlayDomain%22%3A%22vod.test_domain%22%7D&PlayScene=preview&Quality=higher&Ssl=1&UnionInfo=&Vid=v029c1g10003civ2i5mqib*******

返回示例

{
  "ResponseMetadata": {
    "RequestId": "202306041104200100100232280022D31",
    "Action": "GetPlayInfo",
    "Version": "2020-08-01",
    "Service": "vod",
    "Region": "cn-north-1"
  },
  "Result": {
    "Vid": "v029c1g10003civ2i5mqib*******",
    "Status": 1,
    "PosterUrl": "https://img.***.com/1234/8511abe****.jpeg",
    "Duration": 0.1,
    "FileType": "video",
    "EnableAdaptive": true,
    "TotalCount": 1,
    "PlayInfoList": [
      {
        "FileId": "v029c1g10003civ2i5mqib*******",
        "Md5": "398e352f8342aa29a6feee2a18e*****",
        "FileType": "video",
        "Definition": "1080p",
        "Quality": "normal",
        "Format": "mp4",
        "Codec": "H265",
        "LogoType": "default",
        "MainPlayUrl": "http://video.***.com/oIpB7fCZQ2ttbMe4Iklnvx********",
        "BackupPlayUrl": "http://video.***.com/oIpB7fCZQ2ttbMe4Iklnvx********",
        "Bitrate": 1381635,
        "Width": 1920,
        "Height": 1080,
        "Size": 1653067,
        "CheckInfo": "\"a:v029c1g10003civ2i5mqib*******|b:0-983-ac368d50ea39b160********|c:0-983-****\"",
        "IndexRange": "974-1089",
        "InitRange": "0-973",
        "PlayAuth": "****",
        "PlayAuthId": "****",
        "BarrageMaskOffset": "100",
        "Volume": {
          "Loudness": 0.1,
          "Peak": 0.1
        },
        "MainUrlExpire": "1690534212",
        "BackupUrlExpire": "1690534212"
      }
    ],
    "ThumbInfoList": [
      {
        "CaptureNum": 1,
        "StoreUrls": [
          "http://****.com/611d9a3c188150d69435************"
        ],
        "CellWidth": 1,
        "CellHeight": 1,
        "ImgXLen": 1,
        "ImgYLen": 1,
        "Interval": 0.1,
        "Format": "jpg"
      }
    ],
    "BarrageMaskUrl": "http://****.com/460224cfc86a9177b80b************",
    "SubtitleInfoList": [
      {
        "Vid": "v029c1g10003civ2i5mqib*******",
        "FileId": "v029c1g10003civ2i5mqib*******",
        "Language": "eng-US",
        "LanguageId": 1,
        "Format": "webvtt",
        "SubtitleId": "123",
        "Title": "subtitle.vtt",
        "Tag": "subtitle",
        "Status": "enable",
        "Source": "MU",
        "StoreUri": "tos-vod-cn-****/191fe22a1c4a49189a69************",
        "SubtitleUrl": "http://****.com/191fe22a1c4a49189a69************",
        "CreateTime": "2019-10-12T07:20:50.52Z",
        "Version": "1"
      }
    ],
    "BarrageMaskInfo": {
      "Version": "v1",
      "BarrageMaskUrl": "http://****.com/460224cfc86a9177b80b************",
      "FileId": "v029c1g10003civ2i5mqib*******",
      "FileSize": 1,
      "FileHash": "c2e595ab2db511daf6fc************",
      "UpdatedAt": "1676017784",
      "Bitrate": 1,
      "HeadLen": 1
    }
  }
}

错误码

下表列举了本接口特有的错误码。如需了解更多信息请见公共错误码。

状态码	错误码	错误信息	说明
400	InvalidParameter.InvalidVid	-	非法的 Vid。可能是因为请求参数内 Vid 为空或长度异常。
400	InvalidParameter.VidNotExist	-	Vid 不存在。
404	ResourceNotFound.NoAvailableDomain	-	未配置 CDN 域名。

服务端 SDK

点播 OpenAPI 提供了配套的服务端 SDK，支持多种编程语言，帮助您实现快速开发。建议使用服务端 SDK 来调用 API。此 API 各语言调用的示例代码，请参考如下：

使用说明

注意事项

请求说明

调试

请求参数

返回参数

PlayInfoList

ThumbInfoList

SubtitleInfoList

BarrageMaskInfo

Volume

请求示例

返回示例

错误码

服务端 SDK

视频点播

获取播放地址

使用说明

注意事项

请求说明

调试

请求参数

返回参数

PlayInfoList

ThumbInfoList

SubtitleInfoList

BarrageMaskInfo

Volume

请求示例

返回示例

错误码

服务端 SDK