# Ретрансляции Speak через API

> Как через API Kinescope задать профили ретрансляции комнаты Speak: создание вместе с комнатой, смена адреса и ключа потока, удаление, лимиты и ошибки.

Источник: https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/restriming-speak-cherez-api/
Обновлено: 2026-10-12

Комната Speak хранит профили ретрансляции — настройки вида «куда и с каким ключом уходит поток встречи». Профиль принадлежит комнате, а не отдельному звонку, поэтому заданный один раз YouTube или Rutube работает во всех встречах в этой комнате. В интерфейсе комнаты тот же объект называется направлением, в API — профилем ретрансляции и полями `restreams` и `restream_id`.

Через API вы задаёте профили при создании комнаты и меняете их отдельным запросом. Ведущему не придётся вставлять адрес и ключ руками перед эфиром: он открывает панель рестрима и включает тогл. Перед началом работы прочитайте [общие правила API](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/api-obshchie-pravila/).

## Кому подходит эта статья

* **Разработчикам вебинарных платформ** — нужно создавать комнаты с готовыми направлениями трансляции
* **Backend-разработчикам LMS и CRM** — расписание эфиров и адреса площадок живут в вашей системе
* **Интеграторам** — требуется подставлять ключи потока без участия ведущего

## Когда задавать профили ретрансляции из кода

Вот типичные ситуации, когда это пригодится:

* **Эфиры создаются пачками.** Ваша система заводит комнату на каждый вебинар, и в каждой уже должны быть YouTube и VK Видео.
* **Ведущий не должен видеть ключи.** Ключи площадок хранятся у вас, а ведущий только включает тогл в комнате.
* **Площадка перевыпустила ключ.** Вы меняете `stream_key` запросом, не заходя в интерфейс каждой комнаты.
* **Направления меняются по расписанию.** Для одного курса поток идёт на YouTube, для другого — на Rutube, и решает это ваш бэкенд.

Если хотя бы один из этих сценариев вам знаком — читайте дальше.

## Как работают профили ретрансляции (5 шагов)

1. Вы создаёте комнату и передаёте в ней массив `restreams` с названием, адресом и ключом потока.
2. Kinescope определяет площадку по домену адреса и возвращает её в поле `service`.
3. Профили приходят в поле `restreams` объекта комнаты и остаются там до удаления комнаты.
4. Ведущий с ролью организатора или со-организатора включает нужный профиль в панели рестрима — вводить адрес и ключ ему уже не нужно.
5. Пока профиль не вещает, вы можете изменить его запросом `PATCH`.

> **Информация:**
>
> **Запуск и остановка ретрансляции через API недоступны.** API отвечает только за профили: создание, чтение и изменение. Включает и выключает поток участник в комнате — подробности в статье [«Рестриминг в Speak»](https://docs.kinescope.ru/speak-beta/restriming-v-speak/).

Теперь разберём, как это настроить.

## Что подготовить

* API-токен рабочей зоны в заголовке `Authorization: Bearer YOUR_API_TOKEN`.
* ID владельца комнаты для поля `owner_id`. Это пользователь из той же рабочей зоны, иначе запрос вернёт ошибку.
* Адрес и ключ потока с внешней площадки. Где их искать на YouTube, VK Видео, Rutube, Twitch и в Telegram, разобрано в статье [«Рестриминг в Speak»](https://docs.kinescope.ru/speak-beta/restriming-v-speak/).

## Создайте комнату с профилями ретрансляции

`POST https://api.kinescope.io/v1/speak/rooms`

Отдельного метода «добавить профиль в комнату» в API нет. Профили задаются только в момент создания комнаты.

```bash
curl -X POST 'https://api.kinescope.io/v1/speak/rooms' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "owner_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "name": "Вебинар: разбор кейсов",
    "type": "permanent_meeting",
    "restreams": [
        {
            "name": "YouTube Live",
            "url": "rtmp://a.rtmp.youtube.com/live2",
            "stream_key": "xxxx-xxxx-xxxx-xxxx-xxxx"
        },
        {
            "name": "Twitch",
            "url": "rtmp://live.twitch.tv/app",
            "stream_key": "live_xxxxxxxxxx"
        }
    ]
}'
```

Поля профиля:

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| `name` | string | да | Название профиля, от 1 до 128 символов |
| `url` | string | да | RTMP-адрес площадки, без ключа потока |
| `stream_key` | string | да | Ключ потока с площадки, от 1 до 512 символов |

Передавайте `url` и `stream_key` по отдельности, склеивать их в одну строку не нужно. Пробелы и хвостовые слэши в `url` Kinescope отбрасывает сам.

Профили создаются вместе с комнатой в одной транзакции. Если хотя бы один профиль не прошёл проверку, комната не создаётся — поправьте тело запроса и отправьте его целиком заново. В одной комнате можно хранить до 15 профилей.

Успешный запрос возвращает `200 OK` с объектом комнаты:

```json
{
  "data": {
    "id": "9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41",
    "name": "Вебинар: разбор кейсов",
    "type": "permanent_meeting",
    "code": "jqi-qhua-glk",
    "link": "https://speak.kinescope.io/jqi-qhua-glk",
    "status": "pending",
    "restreams": [
      {
        "id": "3c7f1b84-5d20-4e91-a0c6-8f2b1d4e7a93",
        "room_id": "9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41",
        "name": "YouTube Live",
        "url": "rtmp://a.rtmp.youtube.com/live2",
        "stream_key": "xxxx-xxxx-xxxx-xxxx-xxxx",
        "service": "youtube",
        "created_at": "2026-10-12T13:20:00.000000Z",
        "updated_at": null
      }
    ],
    "created_at": "2026-10-12T13:20:00.000000Z"
  }
}
```

Сохраните `id` профиля: он понадобится, чтобы изменить адрес или ключ.

### Какие площадки распознаёт Kinescope

Поле `service` вычисляется по домену `url`, в запросах его передавать не нужно. При смене адреса значение пересчитывается.

| Значение | Домен |
|---|---|
| `youtube` | youtube.com |
| `twitch` | twitch.tv |
| `telegram` | t.me |
| `rutube` | rutube.ru |
| `vk` | mycdn.me |
| `kinescope` | kinescope.io |
| `custom` | любой другой домен |

Поддомены тоже засчитываются: адрес `rtmp://a.rtmp.youtube.com/live2` даст `youtube`.

## Получите сохранённые профили

Отдельного эндпоинта со списком профилей нет. Они приходят в поле `restreams` объекта комнаты, отсортированные по дате создания:

```bash
curl 'https://api.kinescope.io/v1/speak/rooms/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

То же поле есть у каждой комнаты в ответе `GET /v1/speak/rooms`, так что выгрузить профили всех комнат можно одним запросом со страничной навигацией.

## Измените адрес, ключ или название

`PATCH https://api.kinescope.io/v1/speak/rooms/{room_id}/restreams/{restream_id}`

Передавайте только те поля, которые нужно изменить:

```bash
curl -X PATCH 'https://api.kinescope.io/v1/speak/rooms/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41/restreams/3c7f1b84-5d20-4e91-a0c6-8f2b1d4e7a93' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "stream_key": "yyyy-yyyy-yyyy-yyyy-yyyy"
}'
```

| Что передать | Результат |
|---|---|
| Не передавать поле | Значение не изменится |
| `"name": "Новое название"` | Меняет подпись профиля в списке направлений |
| `"url": "rtmp://..."` | Меняет адрес площадки, `service` пересчитывается по новому домену |
| `"stream_key": "..."` | Меняет ключ потока |

Ограничения на длину те же, что при создании: `name` — от 1 до 128 символов, `stream_key` — от 1 до 512.

В ответ приходит обновлённый профиль, а не вся комната. Изменения подхватятся в следующем запуске ретрансляции.

> **Внимание:**
>
> **Профиль, который прямо сейчас вещает, изменить нельзя.** API вернёт `409` с кодом `409298`. Сначала остановите ретрансляцию в комнате, потом повторите запрос.

## Удалите профили вместе с комнатой

`DELETE https://api.kinescope.io/v1/speak/rooms/{room_id}`

Отдельного метода для удаления одного профиля в API нет. Профили живут ровно столько, сколько живёт комната:

```bash
curl -X DELETE 'https://api.kinescope.io/v1/speak/rooms/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

Запрос завершает комнату, отключает участников, гасит активные ретрансляции и удаляет все профили комнаты. Повторный `DELETE` той же комнаты тоже вернёт успех, так что в ретраях его можно не бояться.

Если нужно убрать одно направление, а комнату оставить, это делает участник с ролью организатора или со-организатора: кнопка **«Удалить»** рядом с направлением в панели рестрима. Там же добавляют профили в уже созданную комнату.

## Ограничения

| Что | Значение |
|---|---|
| Профилей в комнате | до 15 |
| Одновременно работающих ретрансляций в звонке | до 5 |
| Длина `name` | 1–128 символов |
| Длина `stream_key` | 1–512 символов |
| Запуск и остановка ретрансляции через API | недоступны |
| Добавление и удаление отдельного профиля через API | недоступны |

> **Внимание:**
>
> **API возвращает `stream_key` в открытом виде.** Ключ потока позволяет вещать на вашу площадку, поэтому ходите в эти эндпоинты только с бэкенда. Не передавайте API-токен в браузер или мобильное приложение и не показывайте сырые ответы API конечным пользователям.

## Обработайте типовые ошибки

| HTTP | Код | Когда возникает |
|---|---|---|
| `400` | `400289` | В запросе на создание комнаты больше 15 профилей |
| `400` | `400400` | `name`, `url` или `stream_key` не прошли проверку |
| `404` | `404404` | Комната или профиль не найдены в вашей рабочей зоне |
| `409` | `409298` | Профиль сейчас вещает и не может быть изменён |

Формат тела ошибки и список полей `invalid_params` разобраны в [общих правилах API](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/api-obshchie-pravila/).

Ошибку `404404` легко получить, если взять верный `restream_id`, но чужой `room_id`: профиль ищется строго внутри указанной комнаты и вашей рабочей зоны.

## Что дальше?

После настройки профилей ретрансляции рекомендуем:

1. **[Рестриминг в Speak](https://docs.kinescope.ru/speak-beta/restriming-v-speak/)** — как ведущий запускает направления из комнаты и что видит при обрыве
2. **[Ссылка для входа в Speak с ролью администратора](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/ssylka-dlya-vhoda-v-speak-s-rolyu-administratora/)** — JWT-токен в ссылке, чтобы ведущий сразу получил права на запуск
3. **[Справочник API по Speak](https://docs.kinescope.ru/api/speak/#v1-speak-rooms)** — комнаты, участники и звонки с параметрами и примерами
4. **[Общие правила API](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/api-obshchie-pravila/)** — авторизация, формат ответов и лимиты запросов

Остались вопросы? Напишите в [чат поддержки](https://t.me/kinescope_bot) — специалисты помогут!