# 创建云端播放器 (/zh-CN/api-reference/api-ref/media-pull/create)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

创建一个云端播放器，用于将在线媒体流输入到声网频道。

- OpenAPI: /openapi/media-pull/media-pull.zh-CN.yaml
- Operation ID: get-region-v1-projects-appId-cloud-player-players
- Method: POST
- Path: /{region}/v1/projects/{appId}/cloud-player/players
- Endpoint: https://api.sd-rtn.com/{region}/v1/projects/{appId}/cloud-player/players

## Servers

- https://api.sd-rtn.com

`Create` 方法用于在项目中创建一个云端播放器。


:::warning[注意]
为确保请求成功，请不要将必填字段设为空，例如 `null` 或 `""`。
:::

## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `Content-Type` (header, required, string) - `application/json`
- `X-Request-ID` (header, optional, string) - UUID（通用唯一识别码），标识本次请求。传入该字段后，声网服务器会在响应 Header 中返回该字段。声网推荐你对 `X-Request-ID` 赋值。如果不赋值，声网服务器会自动生成一个 UUID 传入。
- `streamIp` (query, optional, string) - 媒体流源站 IP 地址。必须使用有效的 IPv4 地址。

该参数可以保障媒体流的传输质量。如果源媒体流只在 `region` 区域内的部分区域提供服务，请使用该参数。如果源媒体流可在 `region` 区域内的广泛的区域提供服务，请忽略该参数。
- `region` (path, required, string) - 云端播放器的区域。声网支持分区域创建云端播放器，目前支持以下区域：

- `cn`：中国大陆。

- `ap`：除中国大陆以外的亚洲区域。

- `na`：北美。

- `eu`：欧洲。

**注意**：请确保设置的 `region` 与你的媒体流源站在同一个区域，且 `region` 值为小写。
- `appId` (path, required, string) - 声网为每个开发者提供的 **App ID**。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。

## Request body

- `player` (object)
  - `player.channelName` (string, required) - 声网频道名称。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "\|", "~", ","
  - `player.uid` (number) - 云端播放器在声网频道内的用户 UID。取值范围为 0 到（2<sup>32</sup>-1）。取值 0 时，声网服务器自动为 player 分配一个 UID。

> [!CAUTION]
> - `uid` 和 `account` 字段二选一必填。如果不设置用户名（UID 或 Account），该云端播放器不能创建，声网服务器会返回 `400(Bad Request)` 的状态码。请确保该值与频道内其他用户、云端播放器的 UID 都不同，否则影响播放质量。
> - 如果你需要在同一个频道内有多个云端播放器，请确保每个云端播放器的用户名（UID 或 Account）都是唯一的。
  - `player.account` (string) - 云端播放器在声网频道内的用户 Account。使用该字段前请先阅读[如何使用 String 型用户名](/zh-CN/reference/faq/integration/string_uid)。该字段不能超过 255 字节，也不能为空字符串。支持的字符集范围（共 89 个字符）如下：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "\|", "~", ","
> [!CAUTION]
> - `uid` 和 `account` 字段二选一必填。如果不设置用户名（UID 或 Account），该云端播放器不能创建，声网服务器会返回 `400(Bad Request)` 的状态码。请确保该值与频道内其他用户、云端播放器的 UID 都不同，否则影响播放质量。
> - 如果你需要在同一个频道内有多个云端播放器，请确保每个云端播放器的用户名（UID 或 Account）都是唯一的。
  - `player.token` (string) - 云端播放器在声网频道内使用的动态密钥。如在声网控制台未启用 App 证书，则不需要向 `token` 传值；如在声网控制台已启用 App 证书，则必须传入 `token`：
- 安全性要求一般时，可使用声网控制台生成的[临时 Token](/zh-CN/introduction/quickstart#获取开发参数)。
- 安全性要求高时，使用用户服务器生成的[正式 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
**注意**：生成正式 Token 时，使用的 `uid` 或 `account` 必须和云端播放器的 `uid` 或 `account` 取值一致。
  - `player.name` (string) - 云端播放器的名字。长度必须在 64 个字符以内，支持的字符集范围为：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- "-", "_"
> [!CAUTION]
> - 不传值时，`name` 为空。同一时间，一个项目下可以有多个 `name` 为空的云端播放器。
> - 同一时间，一个项目下不允许出现重名的云端播放器，用户尝试创建同名的云端播放器时会收到响应状态码 `409(Conflict)`。
> - 如果你需要在同一个频道内仅有一个云端播放器，请你务必使用 `name` 字段。
    - Max length: `64`
  - `player.audioOptions` (object) - 云端播放器的音频转码配置。
    - `player.audioOptions.volume` (number) - 云端播放器的的音量大小。取值范围 [0,200]。默认值为 100，表示原始音量。
      - Default: `100`
      - Range: `[0, 200]`
    - `player.audioOptions.profile` (number) - 音频场景。用于设置音频采样率、码率、编码模式和声道数。
- `0`：默认设置：
  - 通信场景下，该选项代表指定 32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps。
  - 直播场景下，该选项代表指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
- `1`：SPEECH_STANDARD。指定 32 kHz 采样率，语音编码, 单声道，编码码率最大值为 18 Kbps。
- `2`：MUSIC_STANDARD。指定 48 kHz 采样率，音乐编码, 单声道，编码码率最大值为 64 Kbps。
- `4`：MUSIC_HIGH_QUALITY。指定 48 kHz 采样率，音乐编码, 单声道，编码码率最大值为 96 Kbps。
      - Default: `0`
  - `player.videoOptions` (object) - 云端播放器的视频转码配置。
    - `player.videoOptions.width` (number) - 输出视频宽度 (pixel)。取值范围为 [66,1920]。默认值为源媒体流的视频宽度。
      - Default: `源文件视频宽度`
      - Range: `[66, 1920]`
    - `player.videoOptions.height` (number) - 输出视频高度 (pixel)。取值范围为 [66,1080]。默认值为源媒体流的高度宽度。
      - Default: `源文件视频高度`
      - Range: `[66, 1080]`
    - `player.videoOptions.widthHeightAdaption` (boolean) - 是否开启横竖屏自适应模式：
- `true`：开启横竖屏自适应模式。成功开启后，如果源媒体流为横屏模式，则输出视频宽度和高度为 1280 × 720；如果源媒体流为竖屏模式，则输出视频宽度和高度为 720 × 1280。
- `false`：（默认）不开启横竖屏自适应模式。
      - Default: `false`
    - `player.videoOptions.frameRate` (number) - 输出视频的编码帧率 (fps)。详见[输出视频参考表](/zh-CN/realtime-media/rtc/build/video/video-profile#分辨率帧率和码率)。
      - Default: `15`
      - Range: `[5, 30]`
    - `player.videoOptions.bitrate` (number) - 输出视频的编码码率 (Kbps)。详见[输出视频参考表](/zh-CN/realtime-media/rtc/build/video/video-profile#分辨率帧率和码率)。默认值为标准码率，即声网依据当前频道场景、分辨率、帧率为你设置的最合适的码率。
      - Default: `标准码率`
      - Range: `[1, 10000]`
    - `player.videoOptions.gop` (number) - GOP (Group of Pictures) 为关键帧帧间隔时间，单位为秒。
      - Default: `2`
      - Range: `[1, 10]`
    - `player.videoOptions.codec` (string) - 输出视频的编码格式，目前仅支持标准 H.264 格式。默认值为 `"H.264"`。如果设置为其他值，则依然为 H.264。
      - Default: `H.264`
    - `player.videoOptions.fillMode` (string) - 视频画面的显示方式：
- `"fit"`：（默认）等比缩放视频，直到画面在视窗内完整显示。
- `"fill"`：等比缩放视频，直至充满视窗。
      - Default: `fit`
  - `player.streamUrl` (string, required) - 在线媒体流 URL 地址。必须为有效的 HTTP/HTTPS/RTMP/HLS 地址，且长度在 1024 个字符以内。

**注意**：如需发布图片到声网频道，则设置 `streamUrl` 为你需要发布的图片 URL，云端播放器会将图片转换为视频，并发布到声网频道。目前支持 JPEG 和 PNG 格式的图片。你可以通过 `videoOptions` 设置视频转码相关参数。
    - Max length: `1024`
  - `player.playTs` (number) - 云端播放器开始播放在线媒体流时的 Unix 时间戳（秒）。假设云端播放器创建时的 Unix 时间戳是 T，那么 `playTs` 的取值范围为 [T - 86400,T + 300]。默认值为 0，代表云端播放器在创建成功时自动播放在线媒体流。假设 `playTs` 取值为 S：
- 当 S = T 或 0 时，云端播放器在创建成功时自动播放在线媒体流。
- 当 S > T 时，云端播放器会在 S 时刻开始播放在线媒体流。这种取值方式适用于定时播放。
- 当 S < T 时，如果在线媒体流是直播流，云端播放器在创建成功时直接播放直播流；如果在线媒体流是点播流，云端播放器会从 T - S 时刻（秒）的位置开始播放点播流。这种取值方式适用于应对云端播放器运行出错的场景。举例来说，如果云端播放器 A 在运行中出错，你可以重新创建一个云端播放器 B 并将 `playTs` 字段设为云端播放器 A 开始播放在线媒体流时的 Unix 时间戳。
  - `player.idleTimeout` (number) - 云端播放器处于空闲状态的最大时长（秒），即媒体流为非播放状态的最大时长。空闲状态超过设置的 `idleTimeout` 后，该播放器会自动销毁。取值范围为 5 到 600。默认值为 300。如果取值小于 5，声网服务器会自动调整为 5；如果取值大于 600，声网服务器会自动调整为 600。
    - Default: `300`
    - Range: `[5, 600]`
  - `player.encryptMode` (string) - 内置加密模式，可设为如下值：
- `"aes-128-xts"`：128 位 AES 加密，XTS 模式。
- `"aes-256-xts"`：256 位 AES 加密，XTS 模式。
- `"aes-128-ecb"`：128 位 AES 加密，ECB 模式。
- `"sm4-128-ecb"`：128 位 SM4 加密，ECB 模式。
- `"aes-128-gcm"`：128 位 AES 加密，GCM 模式。
- `"aes-256-gcm"`：256 位 AES 加密，GCM 模式。
- `"aes-128-gcm2"`：**推荐设置**。128 位 AES 加密，GCM 模式。 相比于 `aes-128-gcm` 加密模式，`aes-128-gcm2` 加密模式安全性更高且需要设置盐（`encryptKdfSalt`）。
- `"aes-256-gcm2"`：**推荐设置**。256 位 AES 加密，GCM 模式。相比于 `aes-256-gcm` 加密模式，`aes-256-gcm2` 加密模式安全性更高且需要设置盐（`encryptKdfSalt`）。
  - `player.encryptKey` (string) - 内置加密密钥。字符串长度无限制。声网推荐使用 32 字节的密钥。

**注意**：如果该字段为空，则无法启用内置加密。
  - `player.encryptKdfSalt` (string) - 盐，长度为 32 字节。声网推荐你在服务端使用 OpenSSL 随机生成 Base64 编码的盐，详见[媒体流加密](/zh-CN/realtime-media/rtc/build/advanced-channel/channel-encryption)。

**注意**：该字段仅在 `aes-128-gcm2` 或 `aes-256-gcm2` 加密模式下生效。
  - `player.repeatTime` (number) - 播放媒体流次数。该参数仅适用于点播流。可设为如下值：
- `1`：（默认）播放媒体流一次。
- `-1`：循环播放媒体流。
- `n`：自定义播放媒体流次数。整型，不可设置为 0。
  - `player.seekPosition` (number) - 指定点播文件的播放位置（秒）。默认值为 0，表示从点播文件起始位置播放。必须小于音视频时长。
    - Default: `0`
  - `player.dataStreamOptions` (object) - 数据流配置，用于展示当前 Cloud Player 对应的 UID 的点播流总时长，可以用来展示实时播放进度。
    - `player.dataStreamOptions.enable` (boolean) - 设置是否通过 Data stream 展示点播流总时长：
- `true`：展示。
- `false`：（默认）不展示。

如果通过 Data stream 展示点播流总时长，发出的 Data stream 需要使用 Protobuf 解析，而不能用 ASCII 码直接解析。

Protobuf（全称 [Protocol Buffers](https://protobuf.dev/)）是由 Google 开发的一种高效的、跨语言的序列化数据格式。Protobuf 解析步骤如下：

1. 将如下代码保存到一个 proto 文件中，例如 `PlayerMessage.proto`：

    ```proto
    syntax = "proto3";

    message PositionData {
      int32 duration = 1;
      int32 position = 2;
      int32 uid = 3;
    }
    ```

2. 使用 protoc 生成源代码
3. 对接收到的数据进行反序列化
      - Default: `false`
  - `player.tempo` (number) - 播放倍速，支持如下取值：
- 0.5
- 0.75
- 1.0（默认）
- 1.25
- 1.5
- 1.75
- 2.0
    - Default: `1`
    - Format: `float`

### Request body example

```json
{
  "player": {
    "audioOptions": {
      "profile": 1
    },
    "videoOptions": {
      "width": 1920,
      "height": 1080,
      "frameRate": 15,
      "bitrate": 400,
      "codec": "H.264",
      "gop": 2,
      "fillMode": "fill"
    },
    "streamUrl": "rtmp://example.agora.io/live/class32/101",
    "channelName": "class32",
    "token": "2a78446***",
    "uid": 101,
    "idleTimeout": 300,
    "name": "test"
  }
}
```

## Responses

### 200

如果状态码为 2XX，请求成功。

- `player` (object)
  - `player.uid` (number) - 云端播放器在声网频道内的用户 UID。
  - `player.id` (string) - 云端播放器的 ID。它是声网服务器生成的一个 UUID（通用唯一识别码），标识已创建的一个云端播放器。
  - `player.createTs` (number) - 云端播放器创建的 Unix 时间戳（秒）。
  - `player.status` (string) - 云端播放器的运行状态：
- `"idle"`：播放未开始。
- `"connecting"`：声网服务器正在连接媒体流地址或正在探测音视频数据。
- `"running"`：正在播放。
- `"failed"`：声网服务器无法连接媒体流地址或该媒体流无法播放。
- `fields` (string) - JSON 编码方式的字段掩码，详见[谷歌 protobuf FieldMask 文档](https://googleapis.dev/nodejs/pubsub/latest/google.protobuf.html#.FieldMask)。用于指定返回 `players` 数组中每个 player 中的字段子集。在使用 `uid` 的示例中，`fields` 指定声网服务器返回 `players` 数组中每个 player 中的 `name`,`streamUrl`,`channelName`,`uid`,`id`,`createTs` 和 `status` 字段子集。
### 非 2XX

如果状态码不为 2XX，请求失败。

- `message` (string) - 描述请求失败的具体原因。

## Response examples

### 200

```json
{
  "player": {
    "uid": 101,
    "id": "2a784467d647bb87b60b719f6fa56317",
    "createTs": 1575508644,
    "status": "running"
  },
  "fields": "player.uid,player.id,player.createTs,player.status"
}
```
### 非 2XX

```json
{
  "message": "Invalid authentication credentials."
}
```