How to Add Mastodon Alt Text in the Web App and the API

What is Mastodon alt text?

Writing Mastodon alt text means filling in the media description that every attachment on a Mastodon post carries, a plain-text field that screen readers speak in place of the image, video or audio. Mastodon's own posting guide says these descriptions "will be shown when the media fails to load for any reason, or when accessed by screen readers and other assistive technology."

The description belongs to the media attachment, not to the post text. When you attach a file, Mastodon uploads it as a separate attachment object, and the description is stored on that object next to its focal point. A post holds up to 4 attachments on mastodon.social, so a post with four photos carries four separate descriptions.

The API documentation defines the field in one line: "A plain-text description of the media, for accessibility purposes." Plain text means no links, mentions or formatting inside the description.

How do you add alt text to an image on Mastodon?

You add alt text in the Mastodon web app by clicking the ALT or Edit button on an attached image, typing the description in the "Add alt text" dialog and clicking Done before you post. The steps on Mastodon 4.7:

1. Open the composer and attach an image, video or audio file.
2. Look at the thumbnail. An ALT button sits in its corner, and it shows a warning icon while the file has no description.
3. Click ALT, or click Edit in the top corner. Both open the same dialog.
4. Type the description in the text box, which reads "Describe this for people with visual impairments" for images and "Describe this for people with hearing impairments" for audio and video.
5. For an image that contains text, click "Add text from image" to fill the box with the text Mastodon reads out of the picture, then correct it.
6. Click Done. The warning icon disappears from the ALT button.
7. Repeat for each attachment, then click Post.

The same dialog sets the focal point, the spot Mastodon keeps in view when it crops the preview thumbnail. Third-party Mastodon apps put the description field in their own places, but they all write the same description field on the attachment.

How long can Mastodon alt text be?

Mastodon alt text can be as long as your server's description_limit, which Mastodon's code set at 1,500 characters through version 4.5 and at 10,000 characters from version 4.6 onward. Each server runs its own Mastodon version, so the limit you get depends on the server you post from, not on Mastodon as a whole.

Mastodon version	Description limit in the code	Where you see it
4.2 to 4.3	1,500 characters	Not published in the API
4.4 to 4.5	1,500 characters	description_limit in /api/v2/instance
4.6 and later	10,000 characters	description_limit in /api/v2/instance

The limit lives in MediaAttachment::MAX_DESCRIPTION_LENGTH in Mastodon's source, and the server rejects a longer description from its own users. The Instance entity documentation still shows 1,500 in its example response, while mastodon.social reported 10,000 on October 9, 2026, running a 4.8 nightly build. On Mastodon 4.6 and later, the web composer's character counter runs to 10,000.

Long descriptions are allowed, not required. Describe what the image shows and any text in it, and stop there. A post's text has its own limit, covered in the Mastodon character limit, and a description does not count against it.

How do you check your server's alt text limit?

You check a server's alt text limit by reading configuration.media_attachments.description_limit from its GET /api/v2/instance response, which needs no sign-in. The Instance entity documentation describes the field as "The maximum size of a description, in characters," and lists it as added in Mastodon 4.4.0.

Open https://your.server/api/v2/instance in a browser and search the JSON for description_limit. A server on 4.3 or earlier leaves the field out of the response but still enforces 1,500 characters in its code. The same block lists the server's image and video size limits and its supported file types, so one request answers both "how long can my description be" and "will this file upload".

How do you send alt text through the Mastodon API?

You send alt text through the Mastodon API as the description form field on POST /api/v2/media, the call that uploads the file before you attach it to a post. The full set of places the field appears:

Call	What it does with the description
POST /api/v2/media	Sets the description when you upload the file
PUT /api/v1/media/:id	Changes it "before it is attached to a status and posted"
PUT /api/v1/statuses/:id	Changes it after posting, through media_attributes[][], an array that "includes id, description, and focus"

The upload call returns a media attachment with an id, and you pass that id in media_ids[] when you create the status. Small images come back with HTTP 200 and are ready at once. Video, GIF-style video and audio come back with 202 and finish processing in the background, so a client waits for processing before posting. If you schedule through the API, the Mastodon scheduled_at 5-minute rule sets how close to now a post can be queued, and the media and its description are attached to the scheduled post the same way.

Why does Mastodon culture expect alt text?

Mastodon culture expects alt text because the software itself asks for it at every step: the composer flags undescribed media, a confirmation dialog interrupts posting, and readers see which images have a description. Those defaults shape what users treat as normal.

The signals a Mastodon user meets:

• The ALT warning. An attachment without a description shows a warning icon on its ALT button in the composer.
• The posting check. Clicking Post with undescribed media opens "Add alt text?" with the message "Your post contains media without alt text. Adding descriptions helps make your content accessible to more people." You choose "Add alt text" or "Post anyway".
• The default. The check is controlled by "Warn me before posting media without alt text" under Preferences, then Appearance, and it is on for every new account.
• The ALT badge. Described images show an ALT badge in the timeline, and clicking it opens the description, so readers see at a glance who skipped it.
• The docs. The posting guide calls descriptions optional but says "it is a good idea to add media descriptions that briefly describe what is in contained in the media."

The result is a network where a photo without a description stands out. For posters coming from networks that hide the alt field deeper, the gap is the main adjustment, and the comparison in Mastodon vs Bluesky covers the other differences. The broader habits of describing images, captioning video and keeping contrast readable apply on every network, and social media accessibility walks through them.

What happens when you post media without a description

Attach a file

Warning icon on ALT

Click Post

"Add alt text?" dialog

Add alt text or Post anyway

How do you add Mastodon alt text to scheduled posts?

A scheduler adds Mastodon alt text by uploading each image to your server with your description in the description field, then attaching the uploads to the post when it publishes. AdaptlyPost does this through an "Add alt text" button on every image in the composer, with a dialog that asks you to "Describe the image for people who use screen readers."

The Mastodon post scheduler posts to any Mastodon server: you type your server address, such as mastodon.social, and sign in there. Each post takes up to 4 images, each with its own alt text, and for a video post AdaptlyPost waits until your server finishes processing the file before posting. The composer and the AdaptlyPost API take up to 1,000 characters per description, which fits under every limit in the table above. The composer's note on the alt text field reads "Sent to X, Bluesky, Mastodon, LinkedIn, Facebook, Instagram and Threads," so one description per image goes to every network in the post that accepts one.

Frequently asked questions

How do I add alt text on Mastodon?

Attach a file in the composer, click the ALT or Edit button on its thumbnail, type the description and click Done. The warning icon on the ALT button clears once the file has a description. Repeat for each attachment before you click Post.

What is the Mastodon alt text character limit?

The limit is set per server as description_limit in /api/v2/instance. Mastodon's code set 1,500 characters through version 4.5 and 10,000 from version 4.6, so the number depends on the version your server runs. mastodon.social reported 10,000 on October 9, 2026.

Is alt text required on Mastodon?

No. Mastodon accepts posts without media descriptions, and the posting guide calls them optional. The web app shows an "Add alt text?" dialog before posting undescribed media, and that warning is on by default under Preferences, then Appearance.

Can you edit Mastodon alt text after posting?

Yes, through the API. PUT /api/v1/statuses/:id takes media_attributes[][] with the attachment's id, description and focus, so a client that supports editing changes the description on a published post. Before posting, PUT /api/v1/media/:id changes it on an unattached upload.

What does the ALT badge on Mastodon images mean?

The ALT badge means the poster wrote a description for that attachment. Clicking it opens the description text. Images without a description show no badge.

Does AdaptlyPost send alt text to Mastodon?

Yes. AdaptlyPost sends the alt text you write for each image to your Mastodon server along with the upload, up to 4 images per post. Each description can be up to 1,000 characters in the composer and the API, which fits under both the 1,500 and 10,000 limits in Mastodon's code.

Does alt text count toward the Mastodon character limit?

A description does not count against the post's character limit. The post text and each media description have separate limits. The description limit is set by your server as description_limit.

How do I turn off the Mastodon alt text warning?

Open Preferences, then Appearance, and switch off "Warn me before posting media without alt text". The setting is on by default for every new account. With it off, Mastodon posts undescribed media without showing the "Add alt text?" dialog.

Can Mastodon alt text include links or hashtags?

Not as working links or hashtags. The API defines the description as "A plain-text description of the media, for accessibility purposes." Plain text means no links, mentions or formatting inside the description.

How do I add alt text to a video or audio file on Mastodon?

Attach the file, click ALT or Edit on its thumbnail, type the description and click Done. The text box for audio and video reads "Describe this for people with hearing impairments". Through the API, video and audio uploads return 202 and finish processing in the background, so a client waits before posting.