Memes

Um meme é um recurso de imagem, vídeo ou áudio salvo como favorito. O Decoding Chat armazena uma cópia da mídia junto com o meme. A cópia permanece disponível mesmo após a URL ou a mensagem de origem ser excluída.

As rotas aqui são de uso exclusivo do usuário e operam na própria coleção do autor da chamada. O Decoding Chat rejeita um token de bot com 403 ACCESS_DENIED. Criar mensagem envia um meme armazenado através do campo favorite_meme_id, e a API de provedor de GIFs pesquisa no provedor configurado por um GIF a ser salvo.

Limites da coleção

O Decoding Chat limita uma coleção ao teto configurado na instância pelo limite max_favorite_memes, com fallback de 50. Ambas as operações de criação verificam a contagem antes de consultar o canal ou a mensagem e antes de buscar a URL de origem, portanto uma conta que atingiu seu limite é recusada com 400 MAX_FAVORITE_MEMES mesmo que o restante da solicitação apresentasse erro. O corpo do erro informa em max_favorite_memes o teto atingido.

Um meme possui no máximo max_favorite_meme_tags tags, com fallback de 10. O Decoding Chat rejeita uma lista mais longa com 400 INVALID_FORM_BODY e o código de validação MAX_FAVORITE_MEME_TAGS_EXCEEDED no caminho tags.

O Decoding Chat normaliza e remove espaços das bordas de uma tag antes de contá-la, e o resultado deve ter de 1 a 30 caracteres. Uma tag que normaliza para uma string vazia falha com 400 INVALID_FORM_BODY e STRING_LENGTH_INVALID.

Deduplicação

Um meme é identificado pelo hash de conteúdo dos seus bytes armazenados. Os mesmos bytes alcançados por meio de uma URL diferente ou de uma mensagem diferente ainda são considerados duplicados. Salvar um recurso cujo hash já existe na coleção da conta retorna 400 INVALID_FORM_BODY com o código de validação MEDIA_ALREADY_IN_FAVORITE_MEMES no caminho media. O meme existente não é retornado e nada é criado.

Objeto Meme

Um recurso de mídia pertencente a uma conta. O Decoding Chat resolve todos os campos de mídia no momento da criação, e apenas o nome, o texto alternativo (alt text) e as tags podem mudar depois.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do meme
user_id	snowflake	O ID da conta proprietária
name¹	string	O nome de exibição do meme (1-100 caracteres)
alt_text²	?string	A descrição de acessibilidade da mídia, ou nulo quando nenhuma foi definida
tags	array[string]	As tags de busca armazenadas no meme, cada uma com 1-30 caracteres
attachment_id³	snowflake	O ID do anexo que guarda a cópia durável no Decoding Chat
filename	string	O nome de arquivo da cópia armazenada
content_type	string	O tipo MIME da cópia armazenada
content_hash	?string	O hash de conteúdo usado para deduplicação, ou nulo quando não estiver disponível
size	integer	O tamanho armazenado da cópia em bytes
width	?integer	A largura da mídia em pixels, ou nulo quando não aplicável ou desconhecido
height	?integer	A altura da mídia em pixels, ou nulo quando não aplicável ou desconhecido
duration	?number	A duração da mídia em segundos, ou nulo quando não aplicável ou desconhecido
url³	string	A URL de anexo no Decoding Chat da cópia armazenada
is_gifv⁴	boolean	Se a mídia armazenada é animada ou um vídeo convertido a partir de um GIF
gif_slug⁵	?string	O slug emitido pelo provedor de onde este meme se originou, ou nulo
gif_provider⁵	?string	O nome do provedor de GIF que emitiu `gif_slug`, ou nulo
media⁶	?map[string, objeto formato de mídia GIF]	O mapa de formatos do provedor para um meme originado de GIF, ou nulo
placeholder	?string	O placeholder thumbhash compacto registrado no momento do salvamento, ou nulo

¹ Obrigatório em Salvar meme da mensagem. Salvar meme a partir de URL o deriva do filename, truncado para 100 caracteres, quando for omitido ou nulo

² Salvar meme da mensagem utiliza como fallback a descrição do próprio anexo selecionado caso o corpo não forneça um alt text não vazio

³ url é o endpoint de mídia seguido por attachments/{user_id}/{attachment_id}/{filename}, e o Decoding Chat a assina a cada leitura como uma URL de anexo assinada

⁴ Definido quando o anexo ou incorporação (embed) de origem já era animado, e quando o Proxy de Mídia relata a cópia armazenada como animada

⁵ Ambos os campos ficam nulos juntos. klipy é o único valor registrado em novos memes, e tenor aparece apenas em registros legados

⁶ Indexado pelo nome de formato de mídia GIF. Armazenado apenas por Salvar meme a partir de URL, sendo nulo em qualquer meme originado de mensagem

Um meme originado de mensagem registra um slug somente quando o embed selecionado for do tipo gifv cuja URL é reconhecida pelo provedor configurado. Uma seleção de anexo nunca registra um slug.

O horário de criação é o timestamp embutido no id, conforme definido em Snowflakes.

Exemplo

{
  "id": "1501314428688998182",
  "user_id": "1501314428688990000",
  "name": "party_parrot.gif",
  "alt_text": null,
  "tags": ["parrot", "party"],
  "attachment_id": "1501314428688998183",
  "filename": "party_parrot.gif",
  "content_type": "image/gif",
  "size": 40213,
  "width": 320,
  "height": 240,
  "is_gifv": true,
  "gif_slug": "party-parrot-1234",
  "gif_provider": "klipy",
  "placeholder": "3PcNNYYONWQPFxrsUeUcRh4"
}

Objeto formato de mídia GIF

Um descritor que define uma codificação de um GIF do provedor. Um provedor retorna diversas variantes do mesmo GIF para que o cliente possa escolher a menor codificação que conseguir decodificar.

Estrutura

Campo	Tipo	Descrição
src	string	A URL direta da mídia deste formato
proxy_src	string	A URL do Proxy de Mídia deste formato
width¹	integer	A largura deste formato em pixels
height¹	integer	A altura deste formato em pixels

¹ Um valor não negativo de no máximo 2147483647. Um descritor com src ou proxy_src vazio, ou dimensão zero, é ignorado quando o Decoding Chat escolhe o formato de pré-visualização para Resolver URLs de GIF

Um cliente que envia um mapa de formatos para Salvar meme a partir de URL deve fornecer todos os membros de cada descritor; qualquer descritor incompleto falha na validação com 400 INVALID_FORM_BODY.

Nomes de formatos de mídia GIF

Valor	Descrição
webm	Vídeo WebM em tamanho total
mp4	Vídeo MP4 em tamanho total
webp	Imagem WebP em tamanho total
gif	Imagem GIF em tamanho total
mediumwebm	Vídeo WebM médio
mediummp4	Vídeo MP4 médio
mediumwebp	Imagem WebP média
mediumgif	Imagem GIF média
tinywebm	Vídeo WebM pequeno
tinymp4	Vídeo MP4 pequeno
tinywebp	Imagem WebP pequena
tinygif	Imagem GIF pequena
nanowebm	Menor vídeo WebM
nanomp4	Menor vídeo MP4
nanowebp	Menor imagem WebP
nanogif	Menor imagem GIF
loopedmp4	Vídeo MP4 em loop contínuo

Um mapa contém apenas os formatos retornados pelo provedor, portanto nenhuma chave é garantida. O cliente deve percorrer uma lista de prioridades até encontrar uma chave disponível no mapa. Clientes que não puderem decodificar formatos de vídeo DEVEM preferir tinywebp, tinygif, mediumwebp, mediumgif, webp, gif, nanowebp e nanogif, nessa ordem.

Objeto entrada de GIF resolvido

Uma entrada que descreve uma URL submetida a Resolver URLs de GIF.

Estrutura

Campo	Tipo	Descrição
url¹	string	A URL do GIF de origem
proxy_url	string	A URL assinada do Proxy de Mídia para o formato de pré-visualização
width²	integer	A largura do formato de pré-visualização em pixels
height²	integer	A altura do formato de pré-visualização em pixels
media³	map[string, objeto formato de mídia GIF]	Os formatos disponíveis para a URL, indexados pelo nome de formato de mídia GIF
content_type⁴	string	O tipo MIME da mídia apontada por `proxy_url`
placeholder	?string	O placeholder thumbhash compacto, ou nulo se o Proxy de Mídia não tiver emitido nenhum

¹ A URL canônica do próprio provedor caso a URL submetida tenha sido resolvida através do provedor de GIF configurado, ou a própria URL submetida caso contrário

² Zero caso as dimensões não tenham sido determinadas

³ Vazio quando a URL não pertencer a nenhum provedor de GIF registrado e nenhum formato direto individual puder ser derivado dela

⁴ Uma string vazia indica tipo desconhecido, e o cliente deve tratar como image/gif

Um formato direto é derivado somente para video/webm, video/mp4, image/webp e image/gif, e apenas se ambas as dimensões forem positivas.

O formato de pré-visualização é o primeiro descritor utilizável na ordem: tinywebm, tinymp4, mediumwebm, mediummp4, webm, mp4, loopedmp4, nanowebm, nanomp4, tinywebp, tinygif, mediumwebp, webp, mediumgif, gif, nanowebp, nanogif. Caso nenhuma chave dessa lista seja utilizável, o Decoding Chat seleciona o primeiro descritor utilizável na ordem do mapa. Se o mapa não contiver nada utilizável, seleciona a mídia de nível superior do próprio provedor.

Listar memes

GET/v1/users/@me/memes

Retorna todos os objetos de meme da conta atual, em ordem decrescente de ID, de modo que o salvo mais recentemente apareça primeiro.

O limite da coleção da conta restringe quantos itens o array contém.

Resposta

Status	Corpo	Condição
200	array[objeto meme]	A coleção foi retornada, possivelmente como um array vazio
403	resposta de erro	O autor da chamada é um bot ou apresenta credencial bearer e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A conta possui uma ação pendente obrigatória e a requisição retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`

Limite de taxa

60 requisições a cada 10 segundos por usuário autenticado, no bucket favorite_meme:list.

Salvar meme a partir de URL

POST/v1/users/@me/memes

Busca uma URL de mídia absoluta, armazena uma cópia durável no Decoding Chat e retorna o objeto de meme criado. Emite um evento de Gateway Favorite Meme Create.

Corpo JSON

Campo	Tipo	Descrição
url	string	A URL absoluta da mídia a ser obtida e armazenada
name?¹	?string	O nome de exibição do meme (1-100 caracteres)
alt_text?	?string	A descrição de acessibilidade da mídia (0-500 caracteres)
tags?²	?array[string]	As tags de busca a armazenar, cada uma com 1-30 caracteres
gif_slug?³	?string	O slug emitido pelo provedor ou token slug-id para o GIF (1-300 caracteres)
gif_provider?³	?string	O nome estável do provedor que emitiu `gif_slug` (1-32 caracteres)
media?⁴	?map[string, objeto formato de mídia GIF]	O mapa de formatos do provedor capturado pelo cliente no momento do salvamento

¹ Quando omitido ou nulo, o nome será o filename armazenado truncado em 100 caracteres

² Um valor omitido ou nulo resulta em uma lista de tags vazia

³ O Decoding Chat usa o par fornecido apenas quando ambos estão presentes e gif_provider corresponde ao provedor configurado. Caso contrário, extrai um slug da url usando o provedor configurado

⁴ Armazenado apenas quando a solicitação for resolvida para um GIF de provedor e o mapa não for vazio; descartado caso contrário

O nome do arquivo é derivado da URL e do tipo de mídia. Utilize o filename retornado em vez de gerar um manualmente.

Uma URL que não resolva para nenhuma mídia utilizável falha com 400 MEDIA_METADATA_ERROR. Salvar uma mídia já presente na coleção falha conforme descrito em Deduplicação.

Resposta

Status	Corpo	Condição
201	objeto meme	O meme foi criado
400	resposta de erro	O corpo falha na validação com `INVALID_FORM_BODY`⁵
400	resposta de erro	A URL não resolve para nenhuma mídia utilizável com `MEDIA_METADATA_ERROR`
400	resposta de erro	A coleção atingiu seu limite máximo com `MAX_FAVORITE_MEMES`
403	resposta de erro	O autor da chamada é um bot ou apresenta credencial bearer e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A conta possui uma ação pendente obrigatória e a requisição retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`

⁵ Incluindo MAX_FAVORITE_MEME_TAGS_EXCEEDED no caminho tags e MEDIA_ALREADY_IN_FAVORITE_MEMES no caminho media

Efeitos colaterais

A operação emite um evento Favorite Meme Create com o objeto criado para as sessões do próprio autor da chamada.

Limite de taxa

20 requisições por minuto por usuário autenticado, no bucket favorite_meme:create:url.

Salvar meme da mensagem

POST/v1/channels/{channel_id}/messages/{message_id}/memes

Copia um anexo ou recurso de incorporação (embed) de uma mensagem legível para a coleção do próprio usuário e retorna o objeto de meme criado. Requer VIEW_CHANNEL em canais de servidor. Emite um evento de Gateway Favorite Meme Create.

Um autor de chamada em servidor sem READ_MESSAGE_HISTORY só pode selecionar mídias de mensagens enviadas a partir do limite de histórico de mensagens do servidor. Anexos e incorporações presentes em mensagens encaminhadas podem ser selecionados juntamente com os da própria mensagem.

Parâmetros de rota

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal que contém a mensagem
message_id	snowflake	O ID da mensagem que contém a mídia selecionada

Corpo JSON

Campo	Tipo	Descrição
name	string	O nome de exibição do meme (1-100 caracteres)
attachment_id?¹	?snowflake	O ID de um anexo na mensagem ou em seus encaminhamentos
embed_index?¹ ²	?integer	O índice baseado em zero de um embed na mensagem ou em seus encaminhamentos
alt_text?³	?string	A descrição de acessibilidade da mídia (0-500 caracteres)
tags?	?array[string]	As tags de busca a serem armazenadas, cada uma com 1-30 caracteres

¹ Pelo menos uma das chaves deve estar presente; corpo sem nenhuma falha na validação. Ambas podem ser nulas, o que não seleciona nada explicitamente

² embed_index tem precedência quando ambos possuem valor, e um índice fora dos limites falha com EMBED_INDEX_OUT_OF_BOUNDS

³ Obtido a partir da descrição do próprio anexo selecionado caso o valor fornecido seja omitido, nulo, vazio ou somente espaços em branco

Quando nenhuma chave seleciona algo explicitamente, o Decoding Chat escolhe o primeiro anexo da mensagem. Ele escolhe o primeiro embed utilizável se a mensagem não possuir anexos, ou se o anexo não tiver um tipo de mídia suportado. Uma seleção de embed não possui alt text próprio.

Apenas recursos image/*, video/* ou audio/* podem ser salvos. attachment_id só é validado se a mensagem contiver ao menos um anexo. Um ID que não coincida com nenhum falha com ATTACHMENT_ID_NOT_FOUND_IN_MESSAGE no caminho attachment_id. Caso a mensagem não tenha nenhum anexo, o Decoding Chat ignora o ID e seleciona o primeiro embed utilizável. Apenas o anexo selecionado é testado; caso possua tipo não suportado, a busca passa para os embeds. Uma seleção que não resulte em nenhuma mídia suportada falha com NO_VALID_MEDIA_IN_MESSAGE no caminho media.

A seleção de embed utiliza imagem, vídeo ou thumbnail, nessa ordem. Mídias cujos metadados não puderem ser resolvidos falham com 400 MEDIA_METADATA_ERROR.

Resposta

Status	Corpo	Condição
201	objeto meme	O meme foi criado
400	resposta de erro	O corpo ou a seleção falham na validação com `INVALID_FORM_BODY`⁴
400	resposta de erro	Metadados da mídia externa não puderam ser resolvidos com `MEDIA_METADATA_ERROR`
400	resposta de erro	A coleção atingiu seu limite máximo com `MAX_FAVORITE_MEMES`
403	resposta de erro	O autor da chamada é um bot ou apresenta credencial bearer e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A conta possui uma ação pendente obrigatória e a requisição retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
403	resposta de erro	O autor da chamada não é membro do servidor ou não possui `VIEW_CHANNEL`, retornando `MISSING_PERMISSIONS`
403	resposta de erro	O canal exige verificação de idade não concluída pela conta e retorna `NSFW_CONTENT_AGE_RESTRICTED`
404	resposta de erro	O canal não está disponível ou o autor não tem acesso a ele com `UNKNOWN_CHANNEL`
404	resposta de erro	A mensagem não está disponível ou não é legível com `UNKNOWN_MESSAGE`

⁴ O código de validação é ATTACHMENT_ID_NOT_FOUND_IN_MESSAGE, EMBED_INDEX_OUT_OF_BOUNDS, NO_VALID_MEDIA_IN_MESSAGE, MEDIA_ALREADY_IN_FAVORITE_MEMES ou MAX_FAVORITE_MEME_TAGS_EXCEEDED

Efeitos colaterais

O meme recebe sua própria cópia do recurso selecionado. Ler a mensagem de origem renova seu prazo de expiração de anexo quando o decaimento estiver ativado. A mensagem de origem permanece inalterada em todos os outros aspectos.

A operação emite um evento Favorite Meme Create com o objeto criado para as sessões do próprio autor da chamada.

Limite de taxa

10 requisições por minuto por usuário autenticado, no bucket favorite_meme:create:message.

Obter meme

GET/v1/users/@me/memes/{meme_id}

Retorna um objeto de meme pertencente à conta atual.

Parâmetros de rota

Campo	Tipo	Descrição
meme_id	snowflake	O ID do meme

Resposta

Status	Corpo	Condição
200	objeto meme	O meme foi retornado
403	resposta de erro	O autor da chamada é um bot ou apresenta credencial bearer e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A conta possui uma ação pendente obrigatória e a requisição retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
404	resposta de erro	O meme é desconhecido ou pertence a outra conta com `UNKNOWN_FAVORITE_MEME`

Limite de taxa

100 requisições a cada 10 segundos por usuário autenticado, no bucket favorite_meme:get.

Modificar meme

PATCH/v1/users/@me/memes/{meme_id}

Altera o nome, alt text ou tags de um meme pertencente à conta atual e retorna o objeto de meme atualizado. Emite um evento de Gateway Favorite Meme Update.

Parâmetros de rota

Campo	Tipo	Descrição
meme_id	snowflake	O ID do meme

Corpo JSON

Campo	Tipo	Descrição
name?	string	O nome de exibição substituto (1-100 caracteres)
alt_text?¹	?string	A descrição de acessibilidade substituta (0-500 caracteres), ou nulo para limpá-la
tags?²	?array[string]	As tags substitutas, cada uma com 1-30 caracteres

¹ Um campo omitido preserva o valor já armazenado, e um valor nulo explícito o limpa

² Um valor omitido ou nulo preserva as tags já armazenadas

O Decoding Chat verifica a cota de tags em relação à lista resultante, portanto uma solicitação que omitir tags verifica novamente as tags já armazenadas. Um meme que exceda uma cota reduzida posteriormente falha com 400 INVALID_FORM_BODY e MAX_FAVORITE_MEME_TAGS_EXCEEDED até que o chamador envie uma lista menor.

Resposta

Status	Corpo	Condição
200	objeto meme	O meme foi atualizado
400	resposta de erro	Rota, nome, alt text ou comprimento de tag falham na validação com `INVALID_FORM_BODY`³
403	resposta de erro	O autor da chamada é um bot ou apresenta credencial bearer e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A conta possui uma ação pendente obrigatória e a requisição retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
404	resposta de erro	O meme é desconhecido ou pertence a outra conta com `UNKNOWN_FAVORITE_MEME`

³ Incluindo MAX_FAVORITE_MEME_TAGS_EXCEEDED no caminho tags

Efeitos colaterais

A operação modifica os campos fornecidos e preserva todos os campos omitidos. Emite um evento Favorite Meme Update com o objeto atualizado para as sessões do próprio usuário.

Limite de taxa

30 requisições a cada 10 segundos por usuário autenticado, no bucket favorite_meme:update.

Excluir meme

DELETE/v1/users/@me/memes/{meme_id}

Exclui um meme pertencente à conta atual e retorna 204 com corpo vazio. Emite um evento de Gateway Favorite Meme Delete.

Um meme desconhecido, ou pertencente a outra conta, é considerado um sucesso sem ação operacional (no-op).

Parâmetros de rota

Campo	Tipo	Descrição
meme_id	snowflake	O ID do meme

Resposta

Status	Corpo	Condição
204	vazio	O meme foi excluído, ou não existia meme próprio associado
403	resposta de erro	O autor da chamada é um bot ou apresenta credencial bearer e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A conta possui uma ação pendente obrigatória e a requisição retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`

Efeitos colaterais

O meme é removido da coleção mesmo que sua cópia armazenada não possa ser excluída.

Emite um evento Favorite Meme Delete com meme_id para as sessões do próprio usuário. Uma solicitação para um meme que a conta não possui não emite nenhum evento.

Limite de taxa

30 requisições a cada 10 segundos por usuário autenticado, no bucket favorite_meme:delete.

Resolver URLs de GIF

POST/v1/users/@me/favorite-gifs/resolve

Resolve um lote de URLs de GIF em objetos de entrada de GIF resolvido com URLs assinadas do Proxy de Mídia e metadados de pré-visualização.

Um cliente utiliza essa rota para transformar URLs de GIFs favoritos armazenadas em opções renderizáveis no seletor de mídia sem precisar salvá-las previamente.

Cabeçalhos da requisição

Campo	Tipo	Descrição
Accept-Language?¹	string	A localidade preferida usada para consulta no provedor de GIF

¹ O Decoding Chat usa a localidade salva da conta caso exista. Caso contrário, compara este cabeçalho com o registro de localidades suportadas, com fallback para en-US

O Decoding Chat deriva um código de país de duas letras a partir do endereço de IP requisitante via geolocalização, com US como fallback.

Corpo JSON

Campo	Tipo	Descrição
urls	array[string]	As URLs absolutas de GIF a resolver (1-200)

Corpo da resposta

Campo	Tipo	Descrição
entries¹	array[objeto entrada de GIF resolvido]	Uma entrada para cada URL enviada

¹ Exatamente uma entrada por URL enviada, na ordem enviada, permitindo ao cliente indexar o resultado por posição

Uma URL não resolvida ainda retorna uma entrada contendo sua URL de proxy assinada e um mapa media vazio. Dimensões indisponíveis são reportadas como zero e um content_type desconhecido é reportado como string vazia. A falha de uma URL não invalida o lote inteiro.

Resposta

Status	Corpo	Condição
200	corpo da resposta	Uma entrada foi retornada para cada URL, incluindo URLs não resolvidas
403	resposta de erro	O autor da chamada é um bot ou apresenta credencial bearer e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A conta possui uma ação pendente obrigatória e a requisição retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`

Limite de taxa

30 requisições por minuto por usuário autenticado, no bucket favorite_gif:resolve.