Como adicionar texto alternativo do Mastodon no app web e na API

O que é o texto alternativo do Mastodon?

Escrever o texto alternativo do Mastodon significa preencher a descrição de mídia que todo anexo de uma publicação no Mastodon carrega, um campo de texto simples que os leitores de tela falam no lugar da imagem, do vídeo ou do áudio. O guia de publicação do próprio Mastodon diz que essas descrições "will be shown when the media fails to load for any reason, or when accessed by screen readers and other assistive technology."

A descrição pertence ao anexo de mídia, e não ao texto da publicação. Quando você anexa um arquivo, o Mastodon o envia como um objeto de anexo separado, e a descrição fica gravada nesse objeto, ao lado do ponto focal. Uma publicação comporta até 4 anexos no mastodon.social, então uma publicação com quatro fotos carrega quatro descrições separadas.

A documentação da API define o campo em uma linha: "A plain-text description of the media, for accessibility purposes." Texto simples quer dizer sem links, menções nem formatação dentro da descrição.

Como adicionar texto alternativo a uma imagem no Mastodon?

Você adiciona texto alternativo no app web do Mastodon clicando no botão ALT ou Edit de uma imagem anexada, digitando a descrição na caixa de diálogo "Add alt text" e clicando em Done antes de publicar. Os passos no Mastodon 4.7:

1. Abra o compositor e anexe um arquivo de imagem, vídeo ou áudio.
2. Olhe a miniatura. Um botão ALT fica no canto dela e mostra um ícone de aviso enquanto o arquivo não tem descrição.
3. Clique em ALT, ou em Edit no canto superior. Os dois abrem a mesma caixa de diálogo.
4. Digite a descrição na caixa de texto, que diz "Describe this for people with visual impairments" para imagens e "Describe this for people with hearing impairments" para áudio e vídeo.
5. Em uma imagem que contém texto, clique em "Add text from image" para preencher a caixa com o texto que o Mastodon lê da foto e depois corrija o resultado.
6. Clique em Done. O ícone de aviso some do botão ALT.
7. Repita para cada anexo e depois clique em Post.

A mesma caixa de diálogo define o ponto focal, o trecho que o Mastodon mantém visível quando recorta a miniatura de pré-visualização. Os apps de terceiros para Mastodon colocam o campo de descrição em lugares próprios, mas todos gravam o mesmo campo description no anexo.

Qual pode ser o tamanho do texto alternativo do Mastodon?

O texto alternativo do Mastodon pode ter o tamanho do description_limit do seu servidor, que o código do Mastodon fixou em 1,500 caracteres até a versão 4.5 e em 10,000 caracteres da versão 4.6 em diante. Cada servidor roda a sua própria versão do Mastodon, então o limite que você tem depende do servidor de onde publica, e não do Mastodon como um todo.

Versão do Mastodon	Limite de descrição no código	Onde ele aparece
4.2 a 4.3	1,500 caracteres	Não é publicado na API
4.4 a 4.5	1,500 caracteres	description_limit em /api/v2/instance
4.6 em diante	10,000 caracteres	description_limit em /api/v2/instance

O limite fica em MediaAttachment::MAX_DESCRIPTION_LENGTH no código-fonte do Mastodon, e o servidor rejeita uma descrição mais longa vinda dos próprios usuários. A documentação da entidade Instance ainda mostra 1,500 no exemplo de resposta, enquanto o mastodon.social informava 10,000 em 9 de outubro de 2026, rodando uma build nightly da 4.8. No Mastodon 4.6 em diante, o contador de caracteres do compositor web vai até 10,000.

Descrições longas são permitidas, não obrigatórias. Descreva o que a imagem mostra e qualquer texto que ela tenha, e pare aí. O texto de uma publicação tem o seu próprio limite, explicado em o limite de caracteres do Mastodon, e a descrição não conta para ele.

Como verificar o limite de texto alternativo do seu servidor?

Você verifica o limite de texto alternativo de um servidor lendo configuration.media_attachments.description_limit na resposta de GET /api/v2/instance, que não exige login. A documentação da entidade Instance descreve o campo como "The maximum size of a description, in characters," e informa que ele foi adicionado no Mastodon 4.4.0.

Abra https://your.server/api/v2/instance no navegador e procure description_limit no JSON. Um servidor na 4.3 ou anterior não inclui o campo na resposta, mas continua aplicando 1,500 caracteres no código. O mesmo bloco traz os limites de tamanho de imagem e vídeo do servidor e os tipos de arquivo aceitos, então uma só requisição responde tanto "qual pode ser o tamanho da minha descrição" quanto "este arquivo vai subir".

Como enviar texto alternativo pela API do Mastodon?

Você envia texto alternativo pela API do Mastodon no campo de formulário description de POST /api/v2/media, a chamada que sobe o arquivo antes de você anexá-lo a uma publicação. Todos os lugares onde o campo aparece:

Chamada	O que ela faz com a descrição
POST /api/v2/media	Define a descrição quando você sobe o arquivo
PUT /api/v1/media/:id	Altera a descrição "before it is attached to a status and posted"
PUT /api/v1/statuses/:id	Altera a descrição depois da publicação, por meio de media_attributes[][], um array que "includes id, description, and focus"

A chamada de upload devolve um anexo de mídia com um id, e você passa esse id em media_ids[] quando cria o status. Imagens pequenas voltam com HTTP 200 e ficam prontas na hora. Vídeo, vídeo no estilo GIF e áudio voltam com 202 e terminam de processar em segundo plano, então o cliente espera o processamento antes de publicar. Se você agenda pela API, a regra de 5 minutos do scheduled_at do Mastodon define o quão perto do momento atual uma publicação pode entrar na fila, e a mídia e a sua descrição são anexadas à publicação agendada do mesmo jeito.

Por que a cultura do Mastodon espera texto alternativo?

A cultura do Mastodon espera texto alternativo porque o próprio software pede isso a cada passo: o compositor sinaliza mídia sem descrição, uma caixa de confirmação interrompe a publicação e os leitores veem quais imagens têm descrição. Esses padrões moldam o que os usuários tratam como normal.

Os sinais que um usuário do Mastodon encontra:

• O aviso no ALT. Um anexo sem descrição mostra um ícone de aviso no botão ALT do compositor.
• A verificação ao publicar. Clicar em Post com mídia sem descrição abre "Add alt text?" com a mensagem "Your post contains media without alt text. Adding descriptions helps make your content accessible to more people." Você escolhe "Add alt text" ou "Post anyway".
• O padrão. A verificação é controlada por "Warn me before posting media without alt text" em Preferences, depois Appearance, e vem ativada em toda conta nova.
• O selo ALT. Imagens descritas mostram um selo ALT na timeline, e clicar nele abre a descrição, então os leitores veem de relance quem pulou essa etapa.
• A documentação. O guia de publicação chama as descrições de opcionais, mas diz que "it is a good idea to add media descriptions that briefly describe what is in contained in the media."

O resultado é uma rede onde uma foto sem descrição chama a atenção. Para quem vem de redes que escondem o campo alt mais fundo, essa diferença é o principal ajuste, e a comparação em Mastodon vs Bluesky cobre as outras diferenças. Os hábitos mais amplos de descrever imagens, legendar vídeos e manter o contraste legível valem em toda rede, e o guia de acessibilidade em redes sociais passa por cada um deles.

O que acontece quando você publica mídia sem descrição

Anexar um arquivo

Ícone de aviso no ALT

Clique em Post

Diálogo "Add alt text?"

Add alt text ou Post anyway

Como adicionar texto alternativo do Mastodon a publicações agendadas?

Um agendador adiciona texto alternativo do Mastodon subindo cada imagem para o seu servidor com a sua descrição no campo description e depois anexando esses uploads à publicação quando ela sai. O AdaptlyPost faz isso com um botão "Add alt text" em cada imagem do compositor, com uma caixa de diálogo que pede "Describe the image for people who use screen readers."

O agendador de publicações para Mastodon publica em qualquer servidor Mastodon: você digita o endereço do seu servidor, como mastodon.social, e faz login nele. Cada publicação aceita até 4 imagens, cada uma com o seu próprio texto alternativo, e em uma publicação com vídeo o AdaptlyPost espera o servidor terminar de processar o arquivo antes de publicar. O compositor e a API do AdaptlyPost aceitam até 1,000 caracteres por descrição, o que cabe abaixo de todos os limites da tabela acima. A nota do compositor no campo de texto alternativo diz "Sent to X, Bluesky, Mastodon, LinkedIn, Facebook, Instagram and Threads," então uma descrição por imagem vai para cada rede da publicação que aceita uma.

Perguntas frequentes

Como adiciono texto alternativo no Mastodon?

Anexe um arquivo no compositor, clique no botão ALT ou Edit da miniatura, digite a descrição e clique em Done. O ícone de aviso do botão ALT some quando o arquivo passa a ter descrição. Repita para cada anexo antes de clicar em Post.

Qual é o limite de caracteres do texto alternativo do Mastodon?

O limite é definido por servidor como description_limit em /api/v2/instance. O código do Mastodon fixou 1,500 caracteres até a versão 4.5 e 10,000 a partir da 4.6, então o número depende da versão que o seu servidor roda. O mastodon.social informava 10,000 em 9 de outubro de 2026.

O texto alternativo é obrigatório no Mastodon?

Não. O Mastodon aceita publicações sem descrição de mídia, e o guia de publicação as chama de opcionais. O app web mostra a caixa "Add alt text?" antes de publicar mídia sem descrição, e esse aviso vem ativado por padrão em Preferences, depois Appearance.

Dá para editar o texto alternativo do Mastodon depois de publicar?

Dá, pela API. PUT /api/v1/statuses/:id recebe media_attributes[][] com o id, a descrição e o foco do anexo, então um cliente com suporte a edição altera a descrição de uma publicação já no ar. Antes de publicar, PUT /api/v1/media/:id altera a descrição de um upload ainda não anexado.

O que significa o selo ALT nas imagens do Mastodon?

O selo ALT significa que quem publicou escreveu uma descrição para aquele anexo. Clicar nele abre o texto da descrição. Imagens sem descrição não mostram selo.

O AdaptlyPost envia texto alternativo para o Mastodon?

Sim. O AdaptlyPost envia ao seu servidor Mastodon o texto alternativo que você escreve para cada imagem junto com o upload, até 4 imagens por publicação. Cada descrição pode ter até 1,000 caracteres no compositor e na API, o que cabe abaixo tanto do limite de 1,500 quanto do de 10,000 no código do Mastodon.

O texto alternativo conta no limite de caracteres do Mastodon?

A descrição não conta no limite de caracteres da publicação. O texto do post e cada descrição de mídia têm limites separados. Seu servidor define o limite das descrições como description_limit.

Como desativo o aviso de texto alternativo do Mastodon?

Abra Preferences, depois Appearance, e desative "Warn me before posting media without alt text". A opção vem ativada em toda conta nova. Com ela desligada, o Mastodon publica mídia sem descrição sem mostrar o diálogo "Add alt text?".

O texto alternativo do Mastodon pode ter links ou hashtags?

Não como links ou hashtags funcionais. A API define a descrição como "A plain-text description of the media, for accessibility purposes." Texto simples significa sem links, menções ou formatação dentro da descrição.

Como adiciono texto alternativo a um vídeo ou áudio no Mastodon?

Anexe o arquivo, clique em ALT ou Edit na miniatura, digite a descrição e clique em Done. A caixa de texto para áudio e vídeo diz "Describe this for people with hearing impairments". Pela API, os uploads de vídeo e áudio retornam 202 e terminam o processamento em segundo plano, então o cliente espera antes de publicar.