创建云端播放器

描述

调用本接口创建一个云端播放器。创建成功后，云端播放器会自动加载传入的媒体资源，将其推流到指定房间内进行播放。

注意

同一个 AppID 下，最多允许同时存在 50 个正在运行中（未被销毁）的云端播放器。如果您需要提高上限，请联系 ZEGO 技术支持处理。

接口原型

请求方法：POST
请求地址：https://cloud-player-api.zego.im/?Action=CreatePlayer
传输协议：HTTPS
调用频率限制：20 次/秒

请求参数

以下请求参数列表仅列出了接口请求参数，公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
StreamUrl	String	是	媒体资源的地址，必须是有效的 HTTP/HTTPS 地址，且长度在 1024 字节以内。
BackupStreamUrl	String	否	媒体资源的备用地址，必须是有效的 HTTP/HTTPS 地址，且长度在 1024 字节以内。当 StreamUrl 参数中的地址访问失败时，云端播放器会尝试访问备用地址。
RoomId	String	是	推流到指定房间 ID，长度在 128 字节以内。调用本接口时，如果 RoomId 不存在，会自动创建房间。
StreamId	String	否	云端播放器推流到指定房间的流 ID，长度在 256 字节以内，仅支持数字，英文字符和 '-'，'_'。请注意，同一个 AppID 下，StreamId 必须是唯一的。该参数不填写时，由 ZEGO 服务器随机分配一个 ID。
PlayerName	String	否	云端播放器的名称，长度在 64 字节以内，默认为空。同一个 AppId 下可以存在多个 PlayerName 为空的云端播放器，但不允许出现多个正在运行中、且 PlayerName 重复的云端播放器。已销毁的播放器名称 PlayerName 可以再次创建使用，但是建议开发者避免创建相同 PlayerName 的播放器。
VideoOptions	Object	否	视频转码参数配置。请注意，该参数不填写时，其中所包含的字段均使用默认值。
└Width	Number	否	视频宽度，取值范围为 [1, 3000]，且必须是 2 的整倍数，单位为 px，默认值为原始媒体资源的宽度。请注意，Width 和 Height 任意参数设置为 1 时，都表示纯音频推流。
└Height	Number	否	视频高度，取值范围为 [1, 3000]，且必须是 2 的整倍数，单位为 px，默认值为原始媒体资源的高度。请注意，Width 和 Height 任意参数设置为 1 时，都表示纯音频推流。
└VideoBitrate	Number	否	视频码率，取值范围为 [1, 50000]，单位为 kbps，默认值为 ZEGO 根据分辨率和帧率给出的推荐码率，详情请参考常用视频配置中的"预设值组合"。例如，输入分辨率为 360*640 时，输出流的 VideoBitrate 设置为 600 kbps。
└VideoCodec	Number	否	视频编码格式。 0：H264，默认值。 2：VP8。 3：H265。
└Fps	Number	否	视频帧率，取值范围为 [1, 30]，单位为 fps，默认值为 15。
└RenderMode	Number	否	视频填充模式。 0：填充模式，视频等比例缩放，直到画面在视窗内完整显示，可能会有黑边，默认值。 1：裁剪模式，视频等比例缩放，直到充满整个视窗，可能有部分会被裁减。
AudioOptions	Object	否	音频转码参数配置。请注意，该参数不填写时，其中所包含的字段均使用默认值。
└AudioCodec	Number	否	音频编码及采样率。 0：AAC-LC，采样率：44100 kHz，默认值。 1：HE-AAC，采样率：44100 kHz。 6：OPUS，采样率：48000 kHz。
└AudioBitrate	Number	否	音频码率，取值范围为 [1, 192]，单位为 kbps，默认值为 48 kbps。
└SoundChannel	Number	否	音频声道数。 1：单声道，默认值。 2：双声道。
└Volume	Number	否	音量值，范围为 [0, 200]，默认值为 100，表示音频的原始音量。
PlayTime	Number	否	开始播放在线媒体流时的 Unix 时间戳（秒），取值范围为 [CreateTime - 86400, CreateTime + 1800]（CreateTime 是云端播放器的创建时间，调用本接口成功后会返回。如需提高上限，请联系 ZEGO 技术支持），默认值为 0，表示云端播放器创建成功时，自动开始播放在线媒体流。当 PlayTime = CreateTime 时，云端播放器在创建成功时，自动开始播放。当 PlayTime > CreateTime 时，云端播放器在创建成功后，提前加载媒体资源，等到设置的 PlayTime 时刻，再开始播放，实现定时播放的效果。当 PlayTime < CreateTime 时，云端播放器在创建成功后，会从 `CreateTime - PlayTime` 时刻对应的位置，开始播放。例如，当云端播放器 A 运行中出现异常时，您可以创建一个新的云端播放器 B，将 B 的 PlayTime 设置为 A 开始播放的 Unix 时间戳，当 B 创建成功后，即可直接从 A 的当前进度开始播放。例如，CreateTime 为晚上 20:00，当 PlayTime 为 20:00 时，云端播放器创建成功后，直接开始播放；当 PlayTime 为 20:10（CreateTime + 600）时，云端播放器创建成功后，开始加载资源，等到 20:10 开始播放；当 PlayTime 为 19:55（CreateTime - 300）时，云端播放器创建成功后，将直接从媒体流的第 6 分钟开始播放。
RepeatTimes	Number	否	播放次数。 1：播放媒体流 1 次，默认值。 -1：自动循环播放。 n：自定义播放媒体流次数，必须大于 0。
SeekTo	Number	否	指定播放进度（秒），默认值为 0，表示从起始位置开始播放。
MaxIdleTime	Number	否	云端播放器处于空闲状态（指 Status 为 2、6，具体请参考查询云端播放器任务列表的返回参数）的最大时长，即媒体流为非播放状态的最大时长。取值范围为 [5, 600]，单位为秒，默认值为 300 秒。空闲状态超过设置的 MaxIdleTime 后，该播放器会被自动销毁。 MaxIdleTime 如果取值小于 5，ZEGO 服务器会自动调整为 5；如果取值大于 600，ZEGO 服务器会自动调整为 600。
StreamData	Object	否	实时媒体流携带的数据配置（例如播放进度信息等）。该数据将随视频帧作为 SEI 信息，传输给拉流方，拉流方可通过监听客户端的 onPlayerSyncRecvSEI 等回调获取该数据。该参数传输的 SEI 信息默认为 JSON 类型的数据格式，开发者可按 JSON 格式进行解析。例如 SEI 内容为 `null`，其中 CloudPlayerPlayingProgress 表示视频帧当前的播放进度，1000 表示当前的播放进度为 1000ms。
└Enable	Number	否	是否开启 StreamData 配置。 0：不开启，默认值。 1：开启。
└Interval	Number	否	设置用于传输 StreamData 数据的 SEI 信息发送频率（毫秒），默认值为 1000，表示每隔 1 秒发送 1 个携带 StreamData 数据的 SEI 信息。
ExtensionParams	Array of Object	否	扩展参数，以 `Key-Value` 的方式进行设置。该参数一般用于非常规的特殊参数或部分技术预览，请根据实际情况填写，常规的云端播放器任务可忽略。
└Key	String	否	key 值。
└Value	String	否	value 值。
└RoomUserUpdate	Number	否	当您在创建云端播放器时因 RoomId 不存在而自动创建房间时，用户进出房间是否会触发房内其他用户的客户端 onRoomUserUpdate 回调通知： 0：不会（默认）。 1：会。 Note 若 RoomId 存在，此参数无效。

请求示例

请求 URL

Untitled

https://cloud-player-api.zego.im/?Action=CreatePlayer
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false

Copied!

请求消息体

Untitled

{
    "StreamUrl": "https://xxx.com/video/test.mp4",
    "BackupStreamUrl": "",
    "RoomId": "room_12",
    "StreamId": "stream",
    "PlayerName": "player_1",
    "VideoOptions": {
        "Width": 360,
        "Height": 640,
        "VideoBitrate": 600,
        "VideoCodec": 0,
        "Fps": 15,
        "RenderMode": 1
    },
    "AudioOptions": {
        "AudioCodec": 1,
        "AudioBitrate": 48,
        "SoundChannel": 1,
        "Volume": 100
    },
    "PlayTime": 0,
    "RepeatTimes": 1,
    "SeekTo": 0,
    "MaxIdleTime": 30,
    "StreamData": {
        "Enable": 1,
        "Interval": 1000
    }
}

Copied!

响应参数

参数	类型	描述
Code	Number	错误码。
Message	String	错误描述。
RequestId	String	请求 ID。
Data	Object	返回的具体信息。
└PlayerId	String	播放器唯一标识 ID。
└RoomId	String	房间 ID。
└StreamId	String	流 ID。
└CreateTime	Number	播放器创建时间，Unix 时间戳，单位：秒。

响应示例

Untitled

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "abcd123",
    "Data": {
        "PlayerId": "XXXXXXXXXXXX",
        "RoomId": "room_12",
        "StreamId": "stream",
        "CreateTime": 1681221508
    }
}

Copied!

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
0	成功。	-
100000004	签名过期。	请重新生成签名。
100000005	签名错误。	请确认生成签名的参数是否正确。
350006001	接口请求频率超过上限。	请确认对应接口的 QPS 限制，降低请求频率。
350006002	网关校验失败。	请联系 ZEGO 技术支持处理。
350006003	无效的输入参数。	请根据 Message 提示，调整对应参数的取值。
350006006	服务未开通。	请联系 ZEGO 技术支持，开通服务权限。
350006007	云端播放器并发数达到上限。	请确认当前创建的云端播放器数量是否超过上限，默认上限为 50 个。
350006008	当前存在同名的正在运行中的云端播放器。	请确认是否已存在 PlayerName 相同、且在运行中的云端播放器。
350010000	系统错误。	请联系 ZEGO 技术支持处理。