Transmissões
Uma transmissão Go Live (stream) é um compartilhamento de tela em uma conexão de voz existente de um membro. Uma chave de transmissão (stream key) nomeia uma transmissão. As operações aqui registram uma preferência de região e gerenciam a imagem de visualização JPEG da transmissão.
Todas as rotas nesta página são apenas para usuários (user-only). O Decoding Chat rejeita um token de bot e uma credencial de portador (bearer credential) OAuth2 com 403 ACCESS_DENIED.
Ciclo de vida da transmissão
Seção intitulada “Ciclo de vida da transmissão”Iniciar e parar uma transmissão é uma operação principal do Gateway. Transmitir ao vivo publica uma trilha de compartilhamento de tela no participante LiveKit que o membro já possui, e o publicador a anuncia configurando self_stream nessa conexão com Voice State Update. O Decoding Chat não abre uma segunda conexão e não emite nenhuma nova concessão. A Visão geral de voz estabelece o modelo completo.
Chave de transmissão
Seção intitulada “Chave de transmissão”Uma chave de transmissão é um segmento de caminho de 1 a 256 caracteres. Ela possui exatamente três segmentos separados por dois pontos. A forma é {guild_id}:{channel_id}:{connection_id} para uma transmissão em canal de voz de guilda e dm:{channel_id}:{connection_id} para uma transmissão em chamada privada.
| Campo | Tipo | Descrição |
|---|---|---|
| scope1 | string | O literal dm para uma chamada privada ou o ID decimal da guilda para um canal de voz da guilda |
| channel_id2 | string | O ID decimal do canal de voz ou canal privado no qual a transmissão ocorre |
| connection_id3 | string | O connection_id da conexão de voz existente do publicador |
1 Qualquer outro valor falha na verificação de formato, incluindo um segmento vazio
2 O segmento possui dígitos decimais canônicos, [0-9]+ sem zero à esquerda. Uma forma não canônica nunca corresponde
3 A conexão de voz comum do publicador, que também é aquela em seu estado de voz e em sua identidade de participante de mídia
Uma chave com uma contagem de segmentos diferente, um segmento de canal não numérico, um segmento de conexão vazio ou um segmento de escopo que não seja nem dm nem um ID decimal retorna 400 INVALID_STREAM_KEY_FORMAT.
Modificar região da transmissão, Obter visualização da transmissão e Excluir visualização da transmissão resolvem o canal a partir do segmento de canal da chave. Fazer upload de visualização da transmissão e Criar URL de upload de visualização de transmissão resolvem-no a partir do channel_id no corpo da solicitação e depois comparam esse valor com a chave.
O Decoding Chat verifica o segmento de escopo (scope) em relação ao canal resolvido. Uma chave com escopo de guilda cujo canal resolvido é privado retorna 400 STREAM_KEY_SCOPE_MISMATCH, e o mesmo acontece com uma chave dm cujo canal resolvido pertence a uma guilda. Uma chave com escopo de guilda cujo segmento de guilda não é a guilda do canal resolvido retorna o mesmo código.
A rota então compara o segmento de canal contra o ID do canal resolvido, e uma incompatibilidade retorna 400 STREAM_KEY_CHANNEL_MISMATCH. Nas rotas que têm um corpo channel_id, o chamador DEVE enviar o mesmo valor no corpo e na chave.
O Decoding Chat executa essa comparação após todas as outras verificações de regras de acesso de leitura. A busca de canal, a verificação de escopo, a verificação de tipo de canal e a verificação CONNECT ocorrem primeiro, portanto, um corpo channel_id nomeando um canal que o chamador não pode ver retorna 404 UNKNOWN_CHANNEL ou um dos códigos 403 listados em Regras de acesso.
Regras de acesso
Seção intitulada “Regras de acesso”Obter visualização da transmissão requer acesso de leitura. Todas as outras rotas nesta página requerem acesso de mutação.
O acesso de leitura corresponde a Obter canal para o canal resolvido. Um canal de guilda também requer a permissão CONNECT. O chamador não precisa ser o proprietário da transmissão, portanto, qualquer membro que possa entrar no canal pode ler sua visualização.
O acesso de mutação requer tudo o que o acesso de leitura faz. Um canal de guilda também requer a permissão STREAM. O chamador deve manter um estado de voz cujo canal seja o canal resolvido e cujo connection_id seja o segmento de conexão da chave. O Decoding Chat rejeita um chamador que não possua esse estado de voz com 403 ACCESS_DENIED, mesmo quando ele possui (is owner of) o canal.
O Decoding Chat resolve um canal de guilda antes de sua guilda. Uma linha de canal que sobrevive à sua guilda retorna 404 UNKNOWN_GUILD. Quando o registro da guilda existe e o Decoding Chat não consegue resolver o estado da associação, a rota retorna 403 ACCESS_DENIED, e um chamador que não é membro ou não possui VIEW_CHANNEL retorna 403 MISSING_PERMISSIONS. Uma restrição de idade não satisfeita em um canal de texto, voz ou link de guilda retorna 403 NSFW_CONTENT_AGE_RESTRICTED.
Um canal privado cujo conjunto de destinatários não contém o chamador retorna 404 UNKNOWN_CHANNEL. Um canal ausente retorna o mesmo código, portanto, a participação do destinatário nunca pode ser distinguida da existência de canal privado.
Cada rota verifica o tipo de canal após a verificação de escopo. Uma chave de guilda nomeia um canal de voz de guilda e uma chave dm nomeia uma mensagem direta ou uma mensagem direta em grupo. Qualquer outro canal resolvido retorna 400 INVALID_CHANNEL_TYPE.
Objeto de upload de visualização da transmissão
Seção intitulada “Objeto de upload de visualização da transmissão”Um URL de curta duração que aceita a imagem de visualização de uma transmissão. Criar URL de upload de visualização de transmissão o retorna, e o cliente faz o upload da imagem com um único PUT contra a upload_url.
Estrutura
Seção intitulada “Estrutura”| Campo | Tipo | Descrição |
|---|---|---|
| upload_url1 | string | O URL de capacidade (capability URL) que aceita os bytes de visualização com uma solicitação PUT |
| method | string | Sempre PUT |
| content_type2 | string | O tipo de mídia (media type) da solicitação de upload |
| expires_at3 | ISO8601 timestamp | O tempo em que a capacidade expira |
| expires_in3 | integer | O tempo de vida da capacidade em segundos |
| max_bytes | integer | A contagem máxima de bytes aceitos, sempre 1000000 |
1 Uma URL pré-assinada de armazenamento de objetos ou uma URL de upload relay com a capacidade assinada em seu parâmetro de consulta t
2 O content_type da solicitação é retornado exatamente (verbatim), com as maiúsculas originais incluídas, e um campo ausente resulta em image/jpeg
3 Um URL pré-assinado de armazenamento de objetos dura um dia. Um URL de relay dura o tempo de vida do token de relay para o qual a instância está configurada
Um cliente DEVE enviar o URL exatamente como retornado e NÃO DEVE reconstruí-lo ou reordená-lo. Reconstruir perde a capacidade assinada em t, e um URL de relay que chega sem t retorna 401.
O URL aceita solicitações PUT repetidas até expirar. Cada uma substitui a visualização anterior.
Exemplo
Seção intitulada “Exemplo”{ "upload_url": "https://cdn.example.com/stream-previews/1501314428688998182?t=fabricated-token", "method": "PUT", "content_type": "image/jpeg", "expires_at": "2026-08-31T12:00:00.000Z", "expires_in": 86400, "max_bytes": 1000000}Modificar região da transmissão
Seção intitulada “Modificar região da transmissão”PATCH/v1/streams/{stream_key}/streamRegistra a região de mídia preferida para uma transmissão e retorna 204 com um corpo vazio. O chamador deve satisfazer o limite de acesso de mutação.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| stream_key | string | Chave da transmissão cuja região está definida, de 1 a 256 caracteres |
Corpo JSON
Seção intitulada “Corpo JSON”| Campo | Tipo | Descrição |
|---|---|---|
| region?1 | string | O ID da região RTC de 1 a 64 caracteres |
1 Um campo omitido remove qualquer região já armazenada para esta transmissão
Um identificador de região é o id de um objeto de região de RTC, conforme retornado por Listar regiões de RTC.
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 204 | vazio | A preferência foi registrada |
| 400 | resposta de erro | A chave de transmissão está malformada e a solicitação retorna INVALID_STREAM_KEY_FORMAT |
| 400 | resposta de erro | Seu escopo discorda do canal resolvido e a solicitação retorna STREAM_KEY_SCOPE_MISMATCH |
| 400 | resposta de erro | Seu segmento de canal não é a forma canônica do ID do canal resolvido e a solicitação retorna STREAM_KEY_CHANNEL_MISMATCH |
| 400 | resposta de erro | O canal resolvido não é um canal de voz de guilda ou um canal privado e a solicitação retorna INVALID_CHANNEL_TYPE |
| 403 | resposta de erro | O chamador não mantém estado de voz correspondente ou tem um estado de associação de guilda não resolvível, cada um retornando ACCESS_DENIED |
| 403 | resposta de erro | O chamador não possui VIEW_CHANNEL, CONNECT ou STREAM e a solicitação retorna MISSING_PERMISSIONS |
| 403 | resposta de erro | A restrição de idade resolvida de um canal de guilda não é satisfeita e a solicitação retorna NSFW_CONTENT_AGE_RESTRICTED |
| 404 | resposta de erro | O canal nomeado pela chave da transmissão não existe, ou o chamador não é um destinatário do canal privado, cada um retornando UNKNOWN_CHANNEL, ou a guilda proprietária do canal não existe e a solicitação retorna UNKNOWN_GUILD |
Efeitos colaterais
Seção intitulada “Efeitos colaterais”A chamada não tem efeito sobre onde a transmissão é colocada. O Decoding Chat não valida a região contra a lista de regiões acessíveis do chamador. A operação não emite Gateway Dispatch.
Limite de taxa
Seção intitulada “Limite de taxa”20 solicitações por 10 segundos para cada usuário autenticado e chave de transmissão, no bucket channel:stream:update::stream_key.
Obter visualização da transmissão
Seção intitulada “Obter visualização da transmissão”GET/v1/streams/{stream_key}/previewRetorna os bytes de visualização armazenados para uma transmissão. O chamador deve satisfazer o limite de acesso de leitura.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| stream_key | string | Chave de transmissão cuja visualização é retornada, de 1 a 256 caracteres |
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 200 | bytes de visualização | Uma visualização armazenada existe |
| 400 | resposta de erro | A chave de transmissão é malformada e a solicitação retorna INVALID_STREAM_KEY_FORMAT, seu escopo não concorda com o canal resolvido e a solicitação retorna STREAM_KEY_SCOPE_MISMATCH, o canal resolvido não é um canal de voz de guilda ou um canal privado e a solicitação retorna INVALID_CHANNEL_TYPE, ou seu segmento de canal não é a forma canônica do ID do canal resolvido e a solicitação retorna STREAM_KEY_CHANNEL_MISMATCH |
| 403 | resposta de erro | O chamador tem um estado de associação à guilda não resolvível e a solicitação retorna ACCESS_DENIED, o chamador não tem VIEW_CHANNEL ou CONNECT e a solicitação retorna MISSING_PERMISSIONS, ou a restrição de idade resolvida de um canal de guilda não é satisfeita e a solicitação retorna NSFW_CONTENT_AGE_RESTRICTED |
| 404 | vazio | Nenhuma visualização é armazenada para esta chave de transmissão |
| 404 | resposta de erro | O canal nomeado pela chave de transmissão não existe, ou o chamador não é um destinatário do canal privado, cada um retornando UNKNOWN_CHANNEL, ou a guilda proprietária do canal não existe e a solicitação retorna UNKNOWN_GUILD |
O 200 também tem Cache-Control: no-store, private e Pragma: no-cache.
Uma visualização armazenada expira um dia após ser gravada, e uma leitura após esse ponto responde com um 404 vazio. Um objeto armazenado que esteja ausente, temporariamente ilegível ou maior que 1000000 bytes também responde a um 404 vazio.
O Content-Type da resposta é o tipo de mídia registrado quando a visualização foi gravada e o padrão é image/jpeg quando nenhum foi registrado. Fazer upload de visualização de transmissão aceita um tipo de mídia declarado nomeando JPEG sem inspecionar os bytes, e o caminho do recurso (capability path) de Criar URL de upload de visualização de transmissão não inspeciona nada. Portanto, um cliente NÃO DEVE tratar este cabeçalho como prova do formato da carga útil e DEVE decodificar de forma defensiva.
Limite de taxa
Seção intitulada “Limite de taxa”60 solicitações por 10 segundos para cada usuário autenticado e chave de transmissão, no bucket channel:stream:preview:get::stream_key.
Fazer upload de visualização da transmissão
Seção intitulada “Fazer upload de visualização da transmissão”POST/v1/streams/{stream_key}/previewSubstitui a visualização da transmissão por um JPEG enviado inline como base64 e retorna 204 com um corpo vazio. O chamador deve satisfazer o limite de acesso de mutação.
Para fazer upload dos bytes da imagem com uma solicitação PUT separada, use Criar URL de upload de visualização de transmissão.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| stream_key | string | Chave de transmissão que recebe a visualização, de 1 a 256 caracteres |
Corpo JSON
Seção intitulada “Corpo JSON”| Campo | Tipo | Descrição |
|---|---|---|
| channel_id1 | snowflake | O ID do canal em que a transmissão está ativa |
| thumbnail2 | base64 string | O JPEG codificado em base64 de 1 a 2000000 de caracteres |
| content_type?3 | string | O tipo de mídia declarado de 1 a 64 caracteres |
1 O canal que a rota resolve e verifica a permissão. Um valor que não seja o segmento de canal da chave de transmissão retorna 400 STREAM_KEY_CHANNEL_MISMATCH
2 Os bytes decodificados são no máximo 1000000. O Decoding Chat apara (trims) o valor antes de verificar o seu comprimento
3 Um valor contendo jpeg ou jpg em qualquer maiúscula/minúscula é aceito sem inspecionar os bytes. Qualquer outro valor, e um campo ausente, são aceitos apenas quando os bytes decodificados começam com FF D8 e terminam com FF D9
O Decoding Chat armazena o content_type aceito exatamente como recebido (verbatim) e o retorna de Obter visualização da transmissão. Quando o campo está ausente, o tipo de mídia armazenado é image/jpeg.
Um thumbnail que não seja um base64 canônico retorna 400 INVALID_STREAM_THUMBNAIL_PAYLOAD. O Decoding Chat recodifica os bytes decodificados e rejeita o valor quando o resultado não for o que o cliente enviou. O limite de 2000000 de caracteres admite 1500000 bytes decodificados, então um JPEG superdimensionado atinge a verificação de bytes e retorna FILE_SIZE_TOO_LARGE. A verificação de formato ocorre antes da verificação de tamanho. Uma carga útil grande demais que não é um JPEG retorna PREVIEW_MUST_BE_JPEG.
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 204 | vazio | A visualização foi aceita |
| 400 | resposta de erro | A chave de transmissão está malformada e a solicitação retorna INVALID_STREAM_KEY_FORMAT |
| 400 | resposta de erro | O escopo da chave não concorda com o canal resolvido e a solicitação retorna STREAM_KEY_SCOPE_MISMATCH |
| 400 | resposta de erro | O canal no corpo discorda da chave e a solicitação retorna STREAM_KEY_CHANNEL_MISMATCH |
| 400 | resposta de erro | O canal resolvido não é um canal de voz de guilda ou um canal privado e a solicitação retorna INVALID_CHANNEL_TYPE |
| 400 | resposta de erro | A carga útil não é um base64 canônico e a solicitação retorna INVALID_STREAM_THUMBNAIL_PAYLOAD |
| 400 | resposta de erro | A carga útil não é um JPEG e a solicitação retorna PREVIEW_MUST_BE_JPEG |
| 400 | resposta de erro | Ela excede 1000000 de bytes e a solicitação retorna FILE_SIZE_TOO_LARGE |
| 403 | resposta de erro | O chamador não tem estado de voz correspondente ou tem estado de associação de guilda não resolvível, cada um retornando ACCESS_DENIED |
| 403 | resposta de erro | O chamador não possui VIEW_CHANNEL, CONNECT ou STREAM e a solicitação retorna MISSING_PERMISSIONS |
| 403 | resposta de erro | A restrição de idade resolvida de um canal de guilda não é satisfeita e a solicitação retorna NSFW_CONTENT_AGE_RESTRICTED |
| 404 | resposta de erro | O canal nomeado no corpo channel_id não existe, ou o chamador não é um destinatário desse canal privado, cada um retornando UNKNOWN_CHANNEL, ou a guilda proprietária do canal não existe e a solicitação retorna UNKNOWN_GUILD |
Efeitos colaterais
Seção intitulada “Efeitos colaterais”Os bytes decodificados substituem qualquer visualização que a chave de transmissão já tivesse, e os metadados de visualização expiram um dia após a gravação. O Decoding Chat não emite nenhum Dispatch de Gateway, portanto, um visualizador observa a nova imagem em sua próxima leitura de Obter visualização da transmissão.
Um 204 não garante que a nova visualização seja legível. Uma falha temporária pode deixar a imagem anterior, tipo de conteúdo ou expiração no lugar, ou não deixar nenhuma visualização legível. Os publicadores devem continuar a fazer o upload no seu intervalo normal.
Limite de taxa
Seção intitulada “Limite de taxa”20 solicitações por 10 segundos para cada usuário autenticado e chave de transmissão, no bucket channel:stream:preview:post::stream_key.
Criar URL de upload de visualização de transmissão
Seção intitulada “Criar URL de upload de visualização de transmissão”POST/v1/streams/{stream_key}/preview/upload-urlRetorna um objeto de upload de visualização da transmissão garantindo um upload PUT limitado da visualização em JPEG. O chamador deve satisfazer o limite de acesso de mutação.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| stream_key | string | Chave de transmissão que recebe a visualização, de 1 a 256 caracteres |
Corpo JSON
Seção intitulada “Corpo JSON”| Campo | Tipo | Descrição |
|---|---|---|
| channel_id1 | snowflake | O ID do canal onde a transmissão está ativa |
| content_type?2 | string | O tipo de mídia declarado de 1 a 64 caracteres |
1 O canal que a rota resolve e verifica permissão. Um valor que não é o segmento do canal da chave de transmissão retorna 400 STREAM_KEY_CHANNEL_MISMATCH
2 Somente um valor contendo jpeg ou jpg em qualquer maiúscula/minúscula é aceito; um campo ausente significa image/jpeg e qualquer outro valor retorna 400 PREVIEW_MUST_BE_JPEG
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 200 | objeto de upload de visualização da transmissão | A capacidade de upload foi emitida |
| 400 | resposta de erro | A chave da transmissão é malformada e a solicitação retorna INVALID_STREAM_KEY_FORMAT |
| 400 | resposta de erro | O escopo da chave não está de acordo com o canal resolvido e a solicitação retorna STREAM_KEY_SCOPE_MISMATCH |
| 400 | resposta de erro | O canal no corpo discorda da chave e a solicitação retorna STREAM_KEY_CHANNEL_MISMATCH |
| 400 | resposta de erro | O canal resolvido não é um canal de voz de guilda ou um canal privado e a solicitação retorna INVALID_CHANNEL_TYPE |
| 400 | resposta de erro | O tipo de mídia declarado não é JPEG e a solicitação retorna PREVIEW_MUST_BE_JPEG |
| 403 | resposta de erro | O chamador não possui estado de voz correspondente ou tem um estado de associação de guilda não resolvível, cada um retornando ACCESS_DENIED |
| 403 | resposta de erro | O chamador não possui VIEW_CHANNEL, CONNECT ou STREAM e a solicitação retorna MISSING_PERMISSIONS |
| 403 | resposta de erro | A restrição de idade resolvida de um canal de guilda não é satisfeita e a solicitação retorna NSFW_CONTENT_AGE_RESTRICTED |
| 404 | resposta de erro | O canal nomeado no corpo channel_id não existe, ou o chamador não é um destinatário desse canal privado, cada um retornando UNKNOWN_CHANNEL, ou a guilda proprietária do canal não existe e a solicitação retorna UNKNOWN_GUILD |
Efeitos colaterais
Seção intitulada “Efeitos colaterais”Não há chamada de conclusão separada. Após o PUT ser bem-sucedido, Obter visualização da transmissão retorna a imagem enviada. Até lá, ele retorna um 404 vazio ou a imagem anterior.
Um cliente DEVE enviar o content_type retornado com o PUT e NÃO DEVE exceder max_bytes. Os metadados de visualização expiram um dia após esta chamada, então uma capacidade usada mais tarde do que isso grava um objeto que nenhuma leitura pode encontrar. O Decoding Chat não emite Gateway Dispatch.
Limite de taxa
Seção intitulada “Limite de taxa”20 solicitações por 10 segundos para cada usuário autenticado e chave de transmissão, no bucket channel:stream:preview:upload_url::stream_key.
Excluir visualização da transmissão
Seção intitulada “Excluir visualização da transmissão”DELETE/v1/streams/{stream_key}/previewExclui a visualização armazenada para uma transmissão e retorna 204 com um corpo vazio. Excluir uma visualização ausente também retorna 204. O chamador deve satisfazer o limite de acesso de mutação.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| stream_key | string | Chave de transmissão cuja visualização é excluída, de 1 a 256 caracteres |
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 204 | vazio | A visualização foi excluída ou nenhuma estava armazenada |
| 400 | resposta de erro | A chave da transmissão é malformada e a solicitação retorna INVALID_STREAM_KEY_FORMAT |
| 400 | resposta de erro | Seu escopo não está de acordo com o canal resolvido e a solicitação retorna STREAM_KEY_SCOPE_MISMATCH |
| 400 | resposta de erro | Seu segmento de canal não é a forma canônica do ID do canal resolvido e a solicitação retorna STREAM_KEY_CHANNEL_MISMATCH |
| 400 | resposta de erro | O canal resolvido não é um canal de voz de guilda ou um canal privado e a solicitação retorna INVALID_CHANNEL_TYPE |
| 403 | resposta de erro | O chamador não possui estado de voz correspondente ou possui um estado de associação de guilda não resolvível, cada um retornando ACCESS_DENIED |
| 403 | resposta de erro | O chamador não possui VIEW_CHANNEL, CONNECT ou STREAM e a solicitação retorna MISSING_PERMISSIONS |
| 403 | resposta de erro | A restrição de idade resolvida de um canal de guilda não é satisfeita e a solicitação retorna NSFW_CONTENT_AGE_RESTRICTED |
| 404 | resposta de erro | O canal nomeado pela chave da transmissão não existe, ou o chamador não é um destinatário do canal privado, cada um retornando UNKNOWN_CHANNEL, ou a guilda proprietária do canal não existe e a solicitação retorna UNKNOWN_GUILD |
Efeitos colaterais
Seção intitulada “Efeitos colaterais”A visualização deixa de ser legível. Nenhum Gateway Dispatch é emitido, portanto, os visualizadores observam a remoção em sua próxima solicitação de Obter visualização da transmissão.
Limite de taxa
Seção intitulada “Limite de taxa”20 solicitações por 10 segundos para cada usuário autenticado e chave da transmissão, no bucket channel:stream:preview:delete::stream_key.