# 创建推流码 (/zh-CN/api-reference/api-ref/rtmp-gateway/create-streaming-key)

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

创建用于将媒体流推送到指定频道和主播 UID 的推流码。

- OpenAPI: /openapi/media-gateway/media-gateway.zh-CN.yaml
- Operation ID: post-region-v1-projects-appId-rtls-ingress-streamkeys
- Method: POST
- Path: /{region}/v1/projects/{appId}/rtls/ingress/streamkeys
- Endpoint: https://api.sd-rtn.com/{region}/v1/projects/{appId}/rtls/ingress/streamkeys

## Servers

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

该接口创建一个推流码。

推流码也叫推流密钥，能够确保媒体流被推送到正确的频道与主播 uid 下。在开启推流前，你需要先创建推流码。


:::warning[注意]
请合理保管已创建的推流码，不要暴露，否则任何人都可以凭借该推流码推流到频道内。
:::

## Authorization

This endpoint requires authentication.

- `Basic Auth`
- `API Key`

## Parameters

- `X-Request-ID` (header, optional, string) - 本次请求的 UUID（通用唯一识别码）。传入该字段后，声网服务器会在响应 Header 中返回该字段。声网推荐你对 `X-Request-ID` 赋值。如果不赋值，声网服务器会自动生成一个 UUID 传入。
- `region` (path, required, string) - 创建推流码的区域。声网支持分区域创建推流码，目前支持以下区域：
- `cn`：中国大陆
- `ap`：除中国大陆以外的亚洲区域
- `na`：北美
- `eu`：欧洲

> [!CAUTION]
> - 请确保设置的 `region` 与输入的源流在同一个区域。
> - 请确保设置的 `region` 与推流使用的域名在同一个区域。
> - 请确保传入 `region` 的值为小写。
- `appId` (path, required, string) - 声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。App ID 是一个项目的唯一标识。

## Request body

请求包体为 JSON Object 类型的 `settings` 字段。

- `settings` (object)
  - `settings.channel` (string, required) - 声网频道名称，字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `|`, `~`, `,`。
  - `settings.uid` (string, required) - RTMP 网关在声网频道内的主播用户 UID，可以为数字 ID 或[字符串 ID](/zh-CN/reference/faq/integration/string_uid)。如果为数字 ID，取值范围为 1 到 2<sup>32</sup>-1（即 4294967295，大于此数值则会被识别为字符串）；如果为字符串 ID，不能超过 255 字节。支持以下字符集（共 89 个字符）：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `|`, `~`, `,`
允许填 "" 或者 "0"，此时会使用随机的整型 uid 进入频道。具体 uid 的值可通过[查询在推流列表 API](query-streaming-list)  或[接收 NCS 回调](/zh-CN/realtime-media/rtmp-gateway/reference/ncs-events)获得。
> [!CAUTION]
> `uid` 和 `channel` 不能同时为空，即在 `channel` 为 "" 的情况下，`uid` 就不能为 "0" 或 ""。
输入的 `uid` 与实际识别值举例：
> - "123" → 整型 uid，123
> - "0123" → 整型 uid，123
> - "4294967295" → 整型 uid，4294967295
> - "4294967296" → 字符串 uid，"4294967296"
> - "123abc" → 字符串 uid，"123abc"
  - `settings.expiresAfter` (number, required) - 创建的推流码的有效时长，单位为秒。从创建时开始计算。如果填 `0`，则推流码永远有效。
> [!CAUTION]
> 为确保请求成功，请不要将该必填字段设为 `null` 或 `""`。
  - `settings.templateId` (string) - 关联的流配置模板 ID，具体请见[流配置模板](create-reset-template)。如果你不确定它的作用，请不要提供此字段。

### Request body example

```json
{
  "settings": {
    "channel": "shx001",
    "uid": "1001",
    "expiresAfter": 0
  }
}
```

## Responses

### 2XX

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

- `status` (string) - 请求状态，值为 `success`。
- `data` (object)
  - `data.streamKey` (string) - 新创建的推流码。
  - `data.channel` (string) - 推流码绑定的声网频道名称。
  - `data.uid` (string) - 推流码绑定的声网频道内的用户 UID。
  - `data.expiresAfter` (integer) - 推流码的有效时长，从创建时开始计算，单位为秒。
  - `data.createdAt` (string) - 推流码创建时的 Unix 时间戳，单位为秒。
### default

如果状态码不为 `2XX`，则请求失败。你可以参考[响应状态码](/zh-CN/realtime-media/rtmp-gateway/reference/response-code)了解可能的原因。

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

## Response examples

### 2XX

```json
{
  "status": "success",
  "data": {
    "streamKey": "2dfMTR****fys",
    "channel": "shx001",
    "uid": "1001",
    "expiresAfter": 0,
    "createdAt": "1686820170"
  }
}
```
### default

```json
{
  "message": "string"
}
```