Media Push（推流到 CDN）

现行 rtmp-converters 形态、converter 生命周期、输出地址、legacy entry_points 迁移与回调。

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

Media Push 把频道里的音视频推到 RTMP 地址（CDN、直播平台、自建转码）。这一页说明现行实现（rtmp-converters）、生命周期、状态语义，以及声网旧版 entry_points（FLS）与它怎么迁移。

概念

概念	含义
converter	一个推流任务：把某个频道的合流推到某个 `rtmpUrl`。有 id、状态、创建/更新时间
region	区域前缀（如 `cn-shanghai`），写在路径最前面
idleTimeout	无观众/无发布时自动回收的秒数
transcodeOptions / rawOptions	转码参数；不填则按原始参数直推

converter 与 Egress 任务的对应关系是 1:1：每个 converter 对应一个 room_composite egress 任务。

创建 converter

bash

curl -s -X POST "$NIMEET_API_BASE/cn-shanghai/v1/projects/$APP_ID/rtmp-converters?regionHintIp=$REGION_HINT_IP" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H 'Content-Type: application/json' \
  -d '{
    "converter": {
      "name": "weekly-live",
      "rtmpUrl": "rtmp://live.example.com/live/weekly",
      "idleTimeout": 300,
      "jitterBufferSizeMs": 500
    }
  }'

请求体只有 converter 一个字段（必填），里面是：

字段	类型	说明
`name`	string \	null	业务名，便于查询
`rtmpUrl`	string	推流地址；含鉴权串时按原样使用，日志里会脱敏
`idleTimeout`	integer	空闲回收秒数
`jitterBufferSizeMs`	integer	抖动缓冲；直播追低延迟时调小
`transcodeOptions`	object	转码参数（分辨率/码率/帧率）
`rawOptions`	object	原始参数（不转码时用）

响应里的 converter.id / state / createTs 是后续操作要用的。

生命周期

text

创建 convert(POST)  → state: connecting → running → （停止/空闲回收）stopped
                        │
                        └─ 失败 → failed（错误在保活查询的 error 字段里）

操作	端点	说明
创建	`POST /{region}/v1/projects/{appId}/rtmp-converters`	立即开始推流
查询状态	`GET /{region}/v1/projects/{appId}/rtmp-converters/{converterId}`	返回 `state`、`rtmpUrl`、`idleTimeout`…
更新	`PATCH /{region}/v1/projects/{appId}/rtmp-converters/{converterId}`	可改 `rtmpUrl` / 转码参数；带 `sequence` 做乐观并发
列表	`GET /v1/projects/{appId}/rtmp-converters`	支持 `cursor`、`channel` 过滤
销毁	`DELETE /{region}/v1/projects/{appId}/rtmp-converters/{converterId}`	停止并释放 egress

信令与保活

没有心跳接口：converter 在频道里有参与者时保持推流；idleTimeout 内无人则自动回收；
回收/失败都会产生事件码 202（streaming_state_changed）的回调，见回调事件参考；
PATCH 带 sequence 时若 id 已被并发更新会返回 409，先 GET 再重试。

与旧版 entry_points（FLS）的关系

维度	`entry_points`（旧）	`rtmp-converters`（现行）
资源模型	先创建 entry point，再在 entry point 下挂「推某个流名」	一个 converter = 一个推流目标
路径	`/v1/projects/{appid}/fls/*`	`/{region}/v1/projects/{appId}/rtmp-converters*`
多目标	entry point 下多个 stream	多个 converter
声网状态	API sunset	现行文档
我们的态度	兼容实现，不推荐	推荐

迁移映射：一个「entry point + 多个 stream name」相当于「多个 converter」。旧接口的 hls 开关在 Media Push 里由输出端（CDN）负责，我们不再生成 HLS 清单——需要 HLS 就用旁路推流（Legacy）。

播放地址

推流成功后，观众通过 CDN 播放 rtmpUrl 对应的 HLS/FLV 地址——那由你的 CDN 决定，不由我们生成。我们的责任边界到「把流推到 rtmpUrl」。

配额与错误

场景	返回
服务未开通	`403 service_not_enabled`
并发 converter 超限	`429 streaming_quota_exceeded`（见用量与配额）
同一个项目里 converter 名称重复	`409 streaming_invalid_state`，`details.existingConverterId` 指向已有任务（名称唯一，不是允许重名）
缺少 `transcodeOptions.rtcChannel`（或 `rawOptions`）	`400 invalid_parameter`：必须告诉它从哪个频道取流
RTMP 地址不可达	创建成功、`state` 会在保活查询里体现失败原因；创建接口不阻塞等推流握手

端到端示例

bash

node 文档站 class="tok-flag">-all.mjs --only=18

18-media-push-lifecycle.mjs 会走「创建 → 查询状态 → 更新 → 销毁」，并对每一步断言信封与状态（写操作，需要 --all 或 NIMEET_EXAMPLES_MUTATING=1）。

Media Push（推流到 CDN）

概念#

创建 converter#

生命周期#

信令与保活#

与旧版 entry_points（FLS）的关系#

播放地址#

配额与错误#

端到端示例#

概念