# Retransmissão do Speak pela API

> Use a API do Kinescope para definir perfis de retransmissão de uma sala do Speak: criação junto com a sala, troca de URL e chave de transmissão, exclusão, limites e erros.

Fonte: https://docs-br.kinescope.com/developer-guides/retransmissao-do-speak-pela-api/
Atualizado: 2026-10-12

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](https://docs-br.kinescope.com/developer-guides/api-general-rules/).

## 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`.

> **Informação:**
>
> **A API não inicia nem interrompe uma retransmissão.** Ela cuida apenas dos perfis: criar, ler e alterar. Quem liga e desliga o fluxo é um participante dentro da sala, como descrito em [Retransmissão no Speak](https://docs-br.kinescope.com/speak-beta/restreaming-in-speak/).

## 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](https://docs-br.kinescope.com/speak-beta/restreaming-in-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.

```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": "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:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | string | Sim | Nome do perfil, de 1 a 128 caracteres |
| `url` | string | Sim | URL RTMP da plataforma, sem a chave de transmissão |
| `stream_key` | string | Sim | Chave de transmissão da plataforma, de 1 a 512 caracteres |

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:

```json
{
  "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.

| Valor | Domínio |
|---|---|
| `youtube` | youtube.com |
| `twitch` | twitch.tv |
| `telegram` | t.me |
| `kinescope` | kinescope.io |
| `custom` | qualquer outro domínio |

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:

```bash
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:

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

| O que enviar | Resultado |
|---|---|
| Não enviar o campo | O valor não muda |
| `"name": "Novo nome"` | Muda o rótulo do perfil na lista de destinos |
| `"url": "rtmp://..."` | Muda a URL da plataforma, e o `service` é recalculado pelo novo domínio |
| `"stream_key": "..."` | Muda a chave de transmissão |

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.

> **Atenção:**
>
> **Um perfil que está no ar não pode ser alterado.** A API devolve `409` com o código `409298`. Pare a retransmissão na sala e repita a requisição.

## 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:

```bash
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

| Item | Valor |
|---|---|
| Perfis por sala | até 15 |
| Retransmissões simultâneas em uma chamada | até 5 |
| Tamanho de `name` | de 1 a 128 caracteres |
| Tamanho de `stream_key` | de 1 a 512 caracteres |
| Iniciar e parar a retransmissão pela API | indisponível |
| Adicionar e excluir um perfil isolado pela API | indisponível |

> **Atenção:**
>
> **A API devolve o `stream_key` em texto aberto.** A chave de transmissão permite transmitir na sua conta da plataforma, então chame esses endpoints apenas pelo backend. Não exponha o token de API no navegador ou em aplicativos móveis e não mostre respostas brutas da API para os usuários finais.

## Trate os erros mais comuns

| HTTP | Código | Quando acontece |
|---|---|---|
| `400` | `400289` | A requisição de criação da sala tem mais de 15 perfis |
| `400` | `400400` | `name`, `url` ou `stream_key` não passou na validação |
| `404` | `404404` | A sala ou o perfil não foi encontrado no seu espaço de trabalho |
| `409` | `409298` | O perfil está no ar e não pode ser alterado |

O formato do corpo do erro e os campos de `invalid_params` estão descritos nas [regras gerais da API](https://docs-br.kinescope.com/developer-guides/api-general-rules/).

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](https://docs-br.kinescope.com/speak-beta/restreaming-in-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](https://docs-br.kinescope.com/developer-guides/speak-admin-login-link/)** — um JWT no link para o apresentador já poder iniciar as retransmissões
3. **[Referência da API do Speak](https://docs-br.kinescope.com/api/speak/#v1-speak-rooms)** — salas, participantes e chamadas com parâmetros e exemplos
4. **[Regras gerais da API](https://docs-br.kinescope.com/developer-guides/api-general-rules/)** — autorização, formato das respostas e limites de requisições

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