logo
控制台登录/注册
文档
服务端 API
云端播放器
API 概览
调用方法
在线调试服务端 API
POST
创建云端播放器
POST
更新云端播放器
POST
销毁云端播放器
POST
查询云端播放器列表
POST
创建上传任务
POST
取消上传任务
POST
查询上传任务
回调说明
全局返回码
当前页

CreatePlayer

POST

https://cloud-player-api.zego.im/

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

注意

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

说明
调用频率限制：20 次/秒

Request

Query Parameters

    Action string必填

    可选值: [CreatePlayer]

    接口原型参数

    https://cloud-player-api.zego.im?Action=CreatePlayer

    AppId uint32必填

    💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台 获取。

    SignatureNonce string必填

    💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考 签名示例。

    Timestamp int64必填

    💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考 签名示例，最多允许 10 分钟的误差。

    SignatureVersion string必填

    可选值: [2.0]

    默认值: 2.0

    💡公共参数。签名版本号。

    Signature string必填

    💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

Body

required
    StreamUrl string必填

    可选值: <= 1024 characters

    媒体资源的地址，必须是有效的 HTTP/HTTPS 地址，且长度在 1024 字节以内。此处只能选择其中一个参数，其中 StreamUrl 表示创建单播放器，StreamUrlList 表示创建列表播放器。

    StreamUrlList string[]

    媒体资源的地址列表，用于连续播放多个媒体资源。最长支持传入 100 个文件地址且总字节长度不大于 50000。

    说明

    此功能默认关闭，如需开通和使用，请联系 ZEGO 技术支持配置。

    此处只能选择其中一个参数，其中 StreamUrl 表示创建单播放器，StreamUrlList 表示创建列表播放器。

    BackupStreamUrl string

    可选值: <= 1024 characters

    媒体资源的备用地址，必须是有效的 HTTP/HTTPS 地址，且长度在 1024 字节以内。当 StreamUrl 参数中的地址访问失败时，云端播放器会尝试访问备用地址。

    RoomId string必填

    可选值: <= 128 characters

    推流到指定房间 ID，长度在 128 字节以内。调用本接口时，如果 RoomId 不存在，会自动创建房间。

    StreamId string

    可选值: <= 256 characters

    云端播放器推流到指定房间的流 ID，长度在 256 字节以内，仅支持数字，英文字符 和 '-'，'_'。请注意，同一个 AppID 下，StreamId 必须是唯一的。该参数不填写时，由 ZEGO 服务器随机分配一个 ID。

    PlayerName string

    可选值: <= 64 characters

    云端播放器的名称，长度在 64 字节以内，默认为空。

    • 同一个 AppId 下可以存在多个 PlayerName 为空的云端播放器，但不允许出现多个正在运行中、且 PlayerName 重复的云端播放器。
    • 已销毁的播放器名称 PlayerName 可以再次创建使用，但是建议开发者避免创建相同 PlayerName 的播放器。
    VideoOptions object
    视频转码参数配置。请注意，该参数不填写时，其中所包含的字段均使用默认值。
    Width number

    可选值: >= 1 and <= 3000

    视频宽度，取值范围为 [1, 3000]，且必须是 2 的整倍数，单位为 px，默认值为原始媒体资源的宽度。请注意，Width 和 Height 任意参数设置为 1 时，都表示纯音频推流。

    Height number

    可选值: >= 1 and <= 3000

    视频高度，取值范围为 [1, 3000]，且必须是 2 的整倍数，单位为 px，默认值为原始媒体资源的高度。请注意，Width 和 Height 任意参数设置为 1 时，都表示纯音频推流。

    VideoBitrate number

    可选值: >= 1 and <= 50000

    视频码率，取值范围为 [1, 50000]，单位为 kbps，默认值为 ZEGO 根据分辨率和帧率给出的推荐码率，详情请参考 常用视频配置 中的"预设值组合"。例如，输入分辨率为 360*640 时，输出流的 VideoBitrate 设置为 600 kbps。

    VideoCodec number

    可选值: [0, 2, 3]

    视频编码格式。

    • 0：H264，默认值。
    • 2：VP8。
    • 3：H265。
    Fps number

    可选值: >= 1 and <= 30

    视频帧率，取值范围为 [1, 30]，单位为 fps，默认值为 15。

    RenderMode number

    可选值: [0, 1]

    视频填充模式。

    • 0：填充模式，视频等比例缩放，直到画面在视窗内完整显示，可能会有黑边，默认值。
    • 1：裁剪模式，视频等比例缩放，直到充满整个视窗，可能有部分会被裁减。
    AudioOptions object
    音频转码参数配置。请注意，该参数不填写时，其中所包含的字段均使用默认值。
    AudioCodec number

    可选值: [0, 1, 6]

    音频编码及采样率。

    • 0：AAC-LC，采样率：44100 kHz，默认值。
    • 1：HE-AAC，采样率：44100 kHz。
    • 6：OPUS，采样率：48000 kHz。
    AudioBitrate number

    可选值: >= 1 and <= 192

    音频码率，取值范围为 [1, 192]，单位为 kbps，默认值为 48 kbps。

    SoundChannel number

    可选值: [1, 2]

    音频声道数。

    • 1：单声道，默认值。
    • 2：双声道。
    Volume number

    可选值: >= 0 and <= 200

    音量值，范围为 [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

    可选值: >= 5 and <= 3000

    云端播放器处于空闲状态（指 Status 为 2、5、6，具体请参考 查询云端播放器任务列表 的返回参数）的最大时长，即媒体流为非播放状态的最大时长。取值范围为 [5, 3000]，单位为秒，默认值为 300 秒，大于 3000 时，自动调整为 3000。

    • 空闲状态超过设置的 MaxIdleTime 后，该播放器会被自动销毁。
    • MaxIdleTime 如果取值小于 5，ZEGO 服务器会自动调整为 5；如果取值大于 600，ZEGO 服务器会自动调整为 3000。
    StreamData object
    实时媒体流携带的数据配置（例如播放进度信息等）。该数据将随视频帧作为 SEI 信息，传输给拉流方，拉流方可通过监听客户端的 onPlayerSyncRecvSEI 等回调获取该数据。该参数传输的 SEI 信息默认为 JSON 类型的数据格式，开发者可按 JSON 格式进行解析。例如 SEI 内容为 null，其中 CloudPlayerPlayingProgress 表示视频帧当前的播放进度，1000 表示当前的播放进度为 1000ms。
    Enable number

    可选值: [0, 1]

    是否开启 StreamData 配置。

    • 0：不开启，默认值。
    • 1：开启。
    Interval number

    设置用于传输 StreamData 数据的 SEI 信息发送频率（毫秒），默认值为 1000，表示每隔 1 秒发送 1 个携带 StreamData 数据的 SEI 信息。

    ExtensionParams object[]
    扩展参数，以 Key-Value 的方式进行设置。该参数一般用于非常规的特殊参数或部分技术预览，请根据实际情况填写，常规的云端播放器任务可忽略。
  • Array[
    • Key string

    key 值。

    Value string

    value 值。

  • ]
    • RoomUserUpdate number

    可选值: [0, 1]

    当您在创建云端播放器时因 RoomId 不存在而自动创建房间时，用户进出房间是否会触发房内其他用户的客户端 onRoomUserUpdate 回调通知。

    • 0：不会（默认）。
    • 1：会。

    说明

    若 RoomId 存在，此参数无效。

    DelayDestroySeconds number

    可选值: >= 0 and <= 3600

    延迟销毁云端播放器的时间，单位秒。范围为 [0,3600]，默认值为 0。

    说明

    如果需要调整延迟销毁时间的取值范围，请联系 ZEGO 技术支持。

Responses​

OK
Schema
    Code number

    错误码。

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

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

    错误描述。

    RequestId string

    请求 ID。

    Data object
    返回的具体信息。
    PlayerId string

    播放器唯一标识 ID。

    RoomId string

    房间 ID。

    StreamId string

    流 ID。

    CreateTime number

    播放器创建时间，Unix 时间戳，单位：秒。

Previous

在线调试服务端 API

Next

更新云端播放器

当前页

返回到顶部