Cómo añadir texto alternativo de Mastodon en la app web y en la API

¿Qué es el texto alternativo de Mastodon?

Escribir el texto alternativo de Mastodon consiste en rellenar la descripción que lleva cada archivo adjunto de un post de Mastodon, un campo de texto plano que los lectores de pantalla leen en lugar de la imagen, el vídeo o el audio. La guía de publicación de Mastodon dice que estas descripciones "will be shown when the media fails to load for any reason, or when accessed by screen readers and other assistive technology."

La descripción pertenece al archivo adjunto, no al texto del post. Cuando adjuntas un archivo, Mastodon lo sube como un objeto adjunto aparte, y la descripción se guarda en ese objeto junto a su punto focal. Un post admite hasta 4 archivos adjuntos en mastodon.social, así que un post con cuatro fotos lleva cuatro descripciones distintas.

La documentación de la API define el campo en una línea: "A plain-text description of the media, for accessibility purposes." Texto plano significa que la descripción no admite enlaces, menciones ni formato.

¿Cómo se añade texto alternativo a una imagen en Mastodon?

En la app web de Mastodon añades texto alternativo haciendo clic en el botón ALT o Edit de una imagen adjunta, escribiendo la descripción en el diálogo "Add alt text" y haciendo clic en Done antes de publicar. Los pasos en Mastodon 4.7:

1. Abre el compositor y adjunta una imagen, un vídeo o un archivo de audio.
2. Mira la miniatura. En su esquina hay un botón ALT, que muestra un icono de aviso mientras el archivo no tiene descripción.
3. Haz clic en ALT, o en Edit en la esquina superior. Los dos abren el mismo diálogo.
4. Escribe la descripción en el cuadro de texto, que dice "Describe this for people with visual impairments" en las imágenes y "Describe this for people with hearing impairments" en el audio y el vídeo.
5. Si la imagen contiene texto, haz clic en "Add text from image" para rellenar el cuadro con el texto que Mastodon lee de la imagen, y luego corrígelo.
6. Haz clic en Done. El icono de aviso desaparece del botón ALT.
7. Repite con cada archivo adjunto y luego haz clic en Post.

El mismo diálogo fija el punto focal, la zona que Mastodon mantiene a la vista cuando recorta la miniatura de vista previa. Las apps de Mastodon de terceros colocan el campo de descripción en sitios distintos, pero todas escriben el mismo campo description del archivo adjunto.

¿Qué longitud puede tener el texto alternativo de Mastodon?

El texto alternativo de Mastodon puede ser tan largo como el description_limit de tu servidor, que el código de Mastodon fijó en 1,500 caracteres hasta la versión 4.5 y en 10,000 caracteres a partir de la 4.6. Cada servidor ejecuta su propia versión de Mastodon, así que el límite que tienes depende del servidor desde el que publicas, no de Mastodon en conjunto.

Versión de Mastodon	Límite de descripción en el código	Dónde lo ves
4.2 a 4.3	1,500 caracteres	No se publica en la API
4.4 a 4.5	1,500 caracteres	description_limit en /api/v2/instance
4.6 y posteriores	10,000 caracteres	description_limit en /api/v2/instance

El límite vive en MediaAttachment::MAX_DESCRIPTION_LENGTH en el código fuente de Mastodon, y el servidor rechaza una descripción más larga de sus propios usuarios. La documentación de la entidad Instance sigue mostrando 1,500 en su respuesta de ejemplo, mientras que mastodon.social devolvía 10,000 el 9 de octubre de 2026, con una compilación nightly de la 4.8. En Mastodon 4.6 y posteriores, el contador de caracteres del compositor web llega a 10,000.

Las descripciones largas están permitidas, no son obligatorias. Describe lo que muestra la imagen y cualquier texto que contenga, y para ahí. El texto de un post tiene su propio límite, explicado en el límite de caracteres de Mastodon, y la descripción no cuenta para ese límite.

¿Cómo compruebas el límite de texto alternativo de tu servidor?

Compruebas el límite de texto alternativo de un servidor leyendo configuration.media_attachments.description_limit en su respuesta de GET /api/v2/instance, que no requiere iniciar sesión. La documentación de la entidad Instance describe el campo como "The maximum size of a description, in characters," y lo indica como añadido en Mastodon 4.4.0.

Abre https://your.server/api/v2/instance en un navegador y busca description_limit en el JSON. Un servidor con la 4.3 o anterior omite el campo en la respuesta, pero sigue aplicando 1,500 caracteres en su código. El mismo bloque recoge los límites de tamaño de imagen y vídeo del servidor y los tipos de archivo que admite, así que una sola petición responde a "qué longitud puede tener mi descripción" y a "se subirá este archivo".

¿Cómo se envía el texto alternativo a través de la API de Mastodon?

Envías el texto alternativo a través de la API de Mastodon como el campo de formulario description en POST /api/v2/media, la llamada que sube el archivo antes de adjuntarlo a un post. Todos los sitios donde aparece el campo:

Llamada	Qué hace con la descripción
POST /api/v2/media	Fija la descripción al subir el archivo
PUT /api/v1/media/:id	La cambia "before it is attached to a status and posted"
PUT /api/v1/statuses/:id	La cambia después de publicar, mediante media_attributes[][], un array que "includes id, description, and focus"

La llamada de subida devuelve un archivo adjunto con un id, y pasas ese id en media_ids[] al crear el status. Las imágenes pequeñas vuelven con HTTP 200 y están listas al momento. El vídeo, el vídeo tipo GIF y el audio vuelven con 202 y terminan de procesarse en segundo plano, así que un cliente espera a que acabe el procesamiento antes de publicar. Si programas a través de la API, la regla de 5 minutos de scheduled_at en Mastodon fija con cuánta cercanía al momento actual puedes poner un post en cola, y los archivos y su descripción se adjuntan al post programado de la misma forma.

¿Por qué la cultura de Mastodon espera texto alternativo?

La cultura de Mastodon espera texto alternativo porque el propio software lo pide en cada paso: el compositor marca los archivos sin describir, un diálogo de confirmación interrumpe la publicación y los lectores ven qué imágenes tienen descripción. Esos valores por defecto moldean lo que los usuarios consideran normal.

Las señales que encuentra un usuario de Mastodon:

• El aviso en ALT. Un archivo adjunto sin descripción muestra un icono de aviso en su botón ALT dentro del compositor.
• La comprobación al publicar. Hacer clic en Post con archivos sin describir abre "Add alt text?" con el mensaje "Your post contains media without alt text. Adding descriptions helps make your content accessible to more people." Eliges "Add alt text" o "Post anyway".
• El valor por defecto. La comprobación depende de "Warn me before posting media without alt text", en Preferences y luego Appearance, y viene activada en todas las cuentas nuevas.
• La insignia ALT. Las imágenes descritas muestran una insignia ALT en la cronología, y al hacer clic se abre la descripción, así que los lectores ven de un vistazo quién se la saltó.
• La documentación. La guía de publicación dice que las descripciones son opcionales, pero añade que "it is a good idea to add media descriptions that briefly describe what is in contained in the media."

El resultado es una red donde una foto sin descripción llama la atención. Para quien llega desde redes que esconden más el campo alt, esa diferencia es el principal ajuste, y la comparación de Mastodon vs Bluesky cubre las demás diferencias. Los hábitos generales de describir imágenes, subtitular vídeos y mantener un contraste legible sirven en cualquier red, y la accesibilidad en redes sociales los repasa uno a uno.

Qué pasa cuando publicas contenido sin descripción

Adjuntar un archivo

Icono de aviso en ALT

Clic en Post

Diálogo "Add alt text?"

Add alt text o Post anyway

¿Cómo se añade texto alternativo de Mastodon a los posts programados?

Un programador añade el texto alternativo de Mastodon subiendo cada imagen a tu servidor con tu descripción en el campo description y adjuntando luego esas subidas al post cuando se publica. AdaptlyPost lo hace con un botón "Add alt text" en cada imagen del compositor, con un diálogo que te pide "Describe the image for people who use screen readers."

El programador de posts para Mastodon publica en cualquier servidor de Mastodon: escribes la dirección de tu servidor, por ejemplo mastodon.social, e inicias sesión allí. Cada post admite hasta 4 imágenes, cada una con su propio texto alternativo, y en un post con vídeo AdaptlyPost espera a que tu servidor termine de procesar el archivo antes de publicar. El compositor y la API de AdaptlyPost aceptan hasta 1,000 caracteres por descripción, por debajo de todos los límites de la tabla anterior. La nota del compositor junto al campo de texto alternativo dice "Sent to X, Bluesky, Mastodon, LinkedIn, Facebook, Instagram and Threads," así que una descripción por imagen llega a cada red del post que la acepta.

Preguntas frecuentes

¿Cómo añado texto alternativo en Mastodon?

Adjunta un archivo en el compositor, haz clic en el botón ALT o Edit de su miniatura, escribe la descripción y haz clic en Done. El icono de aviso del botón ALT desaparece cuando el archivo ya tiene descripción. Repite con cada archivo adjunto antes de hacer clic en Post.

¿Cuál es el límite de caracteres del texto alternativo de Mastodon?

Cada servidor fija el límite como description_limit en /api/v2/instance. El código de Mastodon lo fijó en 1,500 caracteres hasta la versión 4.5 y en 10,000 desde la 4.6, así que la cifra depende de la versión que ejecute tu servidor. mastodon.social devolvía 10,000 el 9 de octubre de 2026.

¿Es obligatorio el texto alternativo en Mastodon?

No. Mastodon acepta posts sin descripción de los archivos, y la guía de publicación dice que son opcionales. La app web muestra un diálogo "Add alt text?" antes de publicar archivos sin describir, y ese aviso viene activado por defecto en Preferences, dentro de Appearance.

¿Se puede editar el texto alternativo de Mastodon después de publicar?

Sí, a través de la API. PUT /api/v1/statuses/:id acepta media_attributes[][] con el id, la descripción y el punto focal del archivo adjunto, así que un cliente que permita editar cambia la descripción de un post ya publicado. Antes de publicar, PUT /api/v1/media/:id la cambia en una subida que aún no está adjunta.

¿Qué significa la insignia ALT en las imágenes de Mastodon?

La insignia ALT significa que quien publicó escribió una descripción para ese archivo adjunto. Al hacer clic se abre el texto de la descripción. Las imágenes sin descripción no muestran insignia.

¿AdaptlyPost envía el texto alternativo a Mastodon?

Sí. AdaptlyPost envía a tu servidor de Mastodon el texto alternativo que escribes para cada imagen junto con la subida, hasta 4 imágenes por post. Cada descripción puede tener hasta 1,000 caracteres en el compositor y en la API, por debajo tanto del límite de 1,500 como del de 10,000 del código de Mastodon.

¿El texto alternativo cuenta para el límite de caracteres de Mastodon?

La descripción no cuenta para el límite de caracteres del post. El texto del post y cada descripción de medio tienen límites separados. Tu servidor fija el límite de las descripciones como description_limit.

¿Cómo desactivo el aviso de texto alternativo de Mastodon?

Abre Preferences, luego Appearance, y desactiva "Warn me before posting media without alt text". El ajuste viene activado en toda cuenta nueva. Con él desactivado, Mastodon publica los medios sin descripción sin mostrar el diálogo "Add alt text?".

¿Puede el texto alternativo de Mastodon incluir enlaces o hashtags?

No como enlaces ni hashtags funcionales. La API define la descripción como "A plain-text description of the media, for accessibility purposes." Texto plano significa sin enlaces, menciones ni formato dentro de la descripción.

¿Cómo añado texto alternativo a un vídeo o audio en Mastodon?

Adjunta el archivo, haz clic en ALT o Edit en su miniatura, escribe la descripción y pulsa Done. El cuadro de texto para audio y vídeo dice "Describe this for people with hearing impairments". Por la API, las subidas de vídeo y audio devuelven 202 y se procesan en segundo plano, así que el cliente espera antes de publicar.