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

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

Через API вы задаёте профили при создании комнаты и меняете их отдельным запросом. Ведущему не придётся вставлять адрес и ключ руками перед эфиром: он открывает панель рестрима и включает тогл. Перед началом работы прочитайте общие правила API.

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

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

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

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

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

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

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

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

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

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

• API-токен рабочей зоны в заголовке Authorization: Bearer YOUR_API_TOKEN.
• ID владельца комнаты для поля owner_id. Это пользователь из той же рабочей зоны, иначе запрос вернёт ошибку.
• Адрес и ключ потока с внешней площадки. Где их искать на YouTube, VK Видео, Rutube, Twitch и в Telegram, разобрано в статье «Рестриминг в Speak».

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

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

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

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"
        }
    ]
}'

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

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

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

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

{
  "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, в запросах его передавать не нужно. При смене адреса значение пересчитывается.

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

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

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

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}

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

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 — от 1 до 128 символов, stream_key — от 1 до 512.

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

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

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

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

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

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

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

Ограничения

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

Формат тела ошибки и список полей invalid_params разобраны в общих правилах API.

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

Что дальше?

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

1. Рестриминг в Speak — как ведущий запускает направления из комнаты и что видит при обрыве
2. Ссылка для входа в Speak с ролью администратора — JWT-токен в ссылке, чтобы ведущий сразу получил права на запуск
3. Справочник API по Speak — комнаты, участники и звонки с параметрами и примерами
4. Общие правила API — авторизация, формат ответов и лимиты запросов

Остались вопросы? Напишите в чат поддержки — специалисты помогут!