Retransmissão do Speak pela API

Uma sala do Speak guarda perfis de retransmissão, que dizem para onde o fluxo da reunião vai e com qual chave. O perfil pertence à sala, e não a uma chamada específica, então um destino do YouTube ou da Twitch configurado uma vez funciona em todas as reuniões daquela sala. Na interface da sala esse objeto se chama destino; na API ele é o perfil de retransmissão, com os campos restreams e restream_id.

Pela API você define os perfis ao criar a sala e os altera com uma requisição separada. O apresentador não precisa colar URL e chave antes de entrar no ar: ele abre o painel de retransmissão e liga o botão. Antes de começar, leia as regras gerais da API.

Para quem é este artigo

• Desenvolvedores de plataformas de webinar — você cria salas que já precisam ter destinos de transmissão
• Desenvolvedores de backend de LMS e CRM — a agenda das transmissões e os endereços das plataformas ficam no seu sistema
• Integradores — você precisa preencher as chaves de transmissão sem envolver o apresentador

Quando definir perfis de retransmissão pelo código

• As salas são criadas em lote. Seu sistema cria uma sala por webinar, e cada uma já precisa ter YouTube e Twitch prontos.
• O apresentador não deve ver as chaves. As chaves das plataformas ficam com você, e o apresentador apenas liga o botão na sala.
• A plataforma emitiu uma nova chave. Você troca o stream_key em uma requisição, sem abrir cada sala na interface.
• Os destinos mudam conforme a agenda. Um curso vai para o YouTube, outro para a Twitch, e quem decide é o seu backend.

Como funcionam os perfis de retransmissão

1. Você cria a sala e envia o array restreams com nome, URL e chave de transmissão.
2. O Kinescope identifica a plataforma pelo domínio da URL e a devolve no campo service.
3. Os perfis voltam no campo restreams do objeto da sala e ficam lá até a sala ser excluída.
4. Um organizador ou coorganizador liga o perfil desejado no painel de retransmissão, sem digitar URL nem chave.
5. Enquanto o perfil não está no ar, você pode alterá-lo com PATCH.

O que preparar

• Um token de API do espaço de trabalho no cabeçalho Authorization: Bearer YOUR_API_TOKEN.
• O ID do dono da sala para o campo owner_id. O usuário precisa pertencer ao mesmo espaço de trabalho, caso contrário a requisição falha.
• A URL e a chave de transmissão da plataforma externa. O artigo Retransmissão no Speak mostra onde cada plataforma guarda esses valores.

Crie uma sala com perfis de retransmissão

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

A API não tem um método para “adicionar um perfil à sala”. Os perfis são definidos apenas no momento em que a sala é criada.

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": "Webinar: estudos de caso",
    "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"
        }
    ]
}'

Campos do perfil:

Envie url e stream_key separadamente, sem juntar os dois em uma única string. O Kinescope remove espaços e barras finais da url por conta própria.

Os perfis são criados junto com a sala, em uma única transação. Se um único perfil não passar na validação, a sala não é criada: corrija o corpo da requisição e envie tudo de novo. Cada sala comporta até 15 perfis.

Uma requisição bem-sucedida devolve 200 OK com o objeto da sala:

{
  "data": {
    "id": "9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41",
    "name": "Webinar: estudos de caso",
    "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"
  }
}

Guarde o id do perfil: ele é necessário para alterar a URL ou a chave.

Quais plataformas o Kinescope reconhece

O Kinescope calcula o service pelo domínio da url, então você nunca o envia. Quando a URL muda, o valor é recalculado.

Subdomínios também contam: rtmp://a.rtmp.youtube.com/live2 resulta em youtube.

Consulte os perfis salvos

Não existe um endpoint separado que liste os perfis. Eles chegam no campo restreams do objeto da sala, ordenados pela data de criação:

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

Todas as salas na resposta de GET /v1/speak/rooms trazem o mesmo campo, então dá para exportar os perfis de todas elas com uma requisição paginada.

Altere a URL, a chave ou o nome

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

Envie apenas os campos que precisa alterar:

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

Os limites de tamanho são os mesmos da criação: name de 1 a 128 caracteres, stream_key de 1 a 512.

A resposta traz o perfil atualizado, e não a sala inteira. A mudança vale a partir da próxima vez que a retransmissão for iniciada.

Exclua os perfis junto com a sala

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

A API não tem um método para excluir um perfil isolado. Os perfis duram exatamente o que a sala durar:

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

A requisição encerra a sala, desconecta os participantes, derruba as retransmissões ativas e exclui todos os perfis da sala. Repetir o DELETE na mesma sala também devolve sucesso, então ele é seguro dentro de uma rotina de novas tentativas.

Para remover um destino e manter a sala, um organizador ou coorganizador clica no ícone de lixeira ao lado do destino no painel de retransmissão. É no mesmo painel que se adicionam perfis a uma sala já criada.

Limites

Trate os erros mais comuns

O formato do corpo do erro e os campos de invalid_params estão descritos nas regras gerais da API.

O 404404 aparece com facilidade quando o restream_id está certo e o room_id está errado: o perfil é procurado estritamente dentro da sala informada e do seu espaço de trabalho.

O que fazer a seguir?

Depois de configurar os perfis de retransmissão:

1. Retransmissão no Speak — como o apresentador inicia os destinos pela sala e o que aparece quando o fluxo cai
2. Link de entrada no Speak com a função de administrador — um JWT no link para o apresentador já poder iniciar as retransmissões
3. Referência da API do Speak — salas, participantes e chamadas com parâmetros e exemplos
4. Regras gerais da API — autorização, formato das respostas e limites de requisições

Dúvidas? Escreva para o chat de suporte na interface do Kinescope.