Alt text support for Twitter Cards and the REST API

Tuesday, 29 March 2016

When we launched as a text-only service in 2006, Twitter content was easily accessible to people who were visually impaired. Over the years, we’ve extended the platform to support a range of media, but we haven’t provided our users and developers with the tools to provide alternative text (alt text) for images in Tweets.

Developers have tried different approaches to solve this problem. In 2014, Dennis Lembrée and Mark Sadecki created a workaround allowing EasyChirp users to post short and long descriptions of images. Alternatively, Cameron Cundiff’s Alt Text Bot lets people mention @alt_text_bot in a Tweet or Retweet with an attached image, and receive a reply with a text description. These (and other) solutions have a variety of limitations.


At last year’s Flight conference, @jack asked developers for ideas and requests. The ability to provide alternative text for images was the fourth most-requested feature. Today, we’re pleased to tell you we’re extending our platform products, both the REST API and Twitter Cards, so that our customers, publishers and third-party apps will be able to publish images to Twitter that are accessible to people who are visually impaired.

Twitter Cards

Alt text is a long-established standard, and many publishers already use it to make images accessible. To ensure the same content is accessible when published to Twitter, we’re adding support for twitter:image:alt as a companion to the existing twitter:image Cards metadata. The limit is 420 characters, and here’s an example from a BBC article:

<meta name="twitter:image:alt" content="Bill Gates">

Joining us as launch partners are The New York Times, The Associated Press, The BBC, and SkyNews, each having made use of the new metadata to describe images on articles across their sites.


In addition to Cards, we’ve added a new API endpoint for the creation of alt text for images posted to Twitter. As with Cards, the alt text is limited to 420 characters.

Creating Alt Text

  1. Upload an image using the media ingestion API (/1.1/media/upload.json). The server will respond with a media_id.
  2. Call the new media metadata API endpoint (/1.1/media/metadata/create.json) with the alt text and media_id. The server will validate and attach this alt text to the given media_id.  Full documentation for this endpoint will soon be published and linked directly once available.
  3. Send the Tweet using /1.1/statuses/update.json.



POST /1.1/media/metadata/create.json (content-type: application/json)

  "media_id": "650011250680795136",
  "alt_text": {
    "text": "dancing cat"

200 (success), 4xx (Bad Request), 5xx (server error)

Consuming Alt Text

Alt text is accessible to any Twitter app and is requested using the include_ext_alt_text parameter.


GET /1.1/statuses/show.json?id=696049944105320448&include_ext_alt_text=true


The alt text will appear as a top-level key of each media object in the extended_entities object. For example:

"extended_entities": {
  "media": [
      "id_str": "696049944105320448",


      "ext_alt_text": "A Faema Urania lever espresso machine"

If alt text isn’t available for a given image, the value for the property will be null.

This new API endpoint will enable users, publishers, and developers to publish images accessible to the visually impaired. Medium is using it to ensure images of pull quotes from articles have alt text when publishing to Twitter. SocialFlow has adopted the API endpoint to bring support for alt text to all of their publisher clients. And EasyChirp is using the API to render images with alt text.

We’re excited to offer this feature after hearing your feedback loud and clear via the #HelloWorld hashtag. If you have any questions about alt text or this new endpoint, please check out our developer forum at

Update July 12, 2016: As of today, the REST API will return alt text with a Tweet by default. Use of the include_ext_alt_text parameter is no longer necessary.