Media Gateway（RTMP 网关 / RTLS Ingress）
streamkeys、stream templates、online-streams、mute 与断开、appconfig 全局配置、对账语义。
Media Gateway（接口定义里的 rtls/ingress，产品名「RTMP 网关」）解决的是外部 RTMP 推流进入 RTC 频道：主播用 OBS 等工具推到我们给的地址，频道里的观众像看普通参与者一样看到它。
三个概念要分清：
| 概念 | 作用 | 生命周期 |
|---|---|---|
| streamkey | 推流凭证与目标绑定（推到哪个频道、用哪个 uid、多久过期） | 一次性/短期，用完可删 |
| stream template | 推流参数模板（转码、抖动缓冲） | 长期，可复用 |
| online stream | 正在推的一路流（会话），可查询、可静音、可断开 | 随推流建立/结束 |
全局配置
curl -s -X PUT "$NIMEET_API_BASE/cn-shanghai/v1/projects/$APP_ID/rtls/ingress/appconfig" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"settings":{"defaultStreamTemplate":"standard-720p"}}'settings.defaultStreamTemplate 指向一个模板 id；没带模板的推流会用它。
创建 streamkey（主播侧推流凭证）
curl -s -X POST "$NIMEET_API_BASE/cn-shanghai/v1/projects/$APP_ID/rtls/ingress/streamkeys" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"settings":{"channel":"weekly-sync","uid":"30001","expiresAfter":3600,"templateId":"standard-720p"}}'| 字段 | 类型 | 说明 | |
|---|---|---|---|
channel | string | 目标频道 | |
uid | string \ | number | 在频道里的身份（可用字符串账号名） |
expiresAfter | integer | 有效期秒数 | |
templateId | string | 使用的模板 id |
响应 data.streamKey 就是推流密钥。OBS 配置：服务器填 rtmp://<你的网关域名>/live，串流密钥填 streamKey。
流模板
# 新建/覆盖模板
curl -s -X PUT "$NIMEET_API_BASE/cn-shanghai/v1/projects/$APP_ID/rtls/ingress/stream-templates/standard-720p" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"settings":{"transcoding":{"width":1280,"height":720,"frameRate":30,"bitrate":2000},"jitterBuffer":{"sizeMs":500}}}'
# 局部更新
curl -s -X PATCH "$NIMEET_API_BASE/cn-shanghai/v1/projects/$APP_ID/rtls/ingress/stream-templates/standard-720p" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"settings":{"jitterBuffer":{"sizeMs":300}}}'transcoding 控制转码参数，jitterBuffer 控制抖动缓冲：直播追低延迟时把 sizeMs 调小（代价是卡顿更敏感）。
在线流管理
| 操作 | 端点 | 说明 |
|---|---|---|
| 列表 | GET /{region}/v1/projects/{appId}/rtls/ingress/online-streams（可 channel 过滤） | 返回正在推的会话 |
| 查询单个 | GET /{region}/v1/projects/{appId}/rtls/ingress/online-streams/{sid} | 该路流的详情/状态 |
| 静音 | POST /{region}/{version}/projects/{appId}/rtls/ingress/online-streams/mute/{sid} | 服务端静音（不踢人） |
| 断开 | DELETE /{region}/v1/projects/{appId}/rtls/ingress/online-streams/{sid} | 断开推流并结束会话 |
典型接入时序
- 服务端建 streamkey（绑定频道 + uid + 模板），把
streamKey交给主播； - 主播在 OBS 里推流，网关建立会话，频道里出现该 uid（其他端收到
user-published）； - 你可以在
online-streams里看到sid，必要时mute或DELETE； - 推流结束后会话消失；streamkey 到期或主动
DELETE后不能再推。
与 Media Push 的区别
| Media Gateway（ingress） | Media Push（egress） | |
|---|---|---|
| 方向 | 外部流 → 频道 | 频道 → RTMP 地址 |
| 典型场景 | OBS 推流进会议/直播 | 频道内容推到 CDN |
| 资源 | streamkey / template / online-stream | converter |
两者可以组合：OBS 推流进频道（Gateway）→ 合流后再推到 CDN（Push）。
配额与错误
| 场景 | 返回 |
|---|---|
| 服务未开通 | 403 service_not_enabled |
| 流模板超过 10 个 | 429 streaming_quota_exceeded（at most 10 templates can exist under one app id） |
| streamkey 过期后推流 | 网关拒绝握手（该 sid 不会出现在 online-streams） |
| 同一个 uid 重复推流 | 由媒体面仲裁：后到的连接会替换先到的，旧 sid 失效；控制面只反映真实会话 |
| 模板维度非法 | 400 validation，字段级错误在 details |
端到端示例
node 文档站 class="tok-flag">-all.mjs --only=2020-media-gateway-lifecycle.mjs：appconfig → 建模板 → 建 streamkey → 查 streamkey → 查在线流 → 删 streamkey → 删模板（写操作，需要 --all）。