Log inStart Free Trial
easyCoexistence Official APIs

Alt text on Instagram posts through the API

Instagram's API adds alternative text to an image post through the alt_text parameter, set when the media container is created. It takes up to 1,000 characters and works on a single photo or on each image in a carousel, while Reels and Stories do not support it. Meta added the field on 24 March 2025.

easyCoexistence publishes photos and carousels with publish_instagram_post from Claude, ChatGPT or your own code.

1,000

Most characters of alternative text one image can carry through the API.

24 Mar 2025

When Meta introduced the alt_text field for image posts on the media endpoint.

Images only

alt_text works on single images and carousel images; Reels and Stories are not supported.

alt_text

Field on published media that returns an image's descriptive text, for accessibility.

What is alt text on an Instagram post?

A written description of an image, which Meta's media reference calls descriptive text for images, for accessibility. Through the API it is set per image with the alt_text parameter when the container is created, and read back from the alt_text field once the post is published.

How is alt text added?

With alt_text on the image's container. POST /<IG_ID>/media with image_url, the caption and alt_text creates it, and POST /<IG_ID>/media_publish publishes it as usual. For a carousel, set alt_text on each image item's container, the ones created with is_carousel_item set to true, before creating the carousel container.

An image container with alt text
POST https://graph.instagram.com/<IG_ID>/media
Content-Type: application/json

{
  "image_url": "https://example.com/photo.jpg",
  "caption": "<CAPTION>",
  "alt_text": "<WHAT_THE_IMAGE_SHOWS>"
}

Which posts support alt text?

Image posts only, as Meta's reference describes the parameter:

  • A single image post: supported, up to 1,000 characters.
  • Images in a carousel: supported, each with its own text.
  • Videos, including video items in a carousel: not supported.
  • Reels and Stories: not supported.
  • The carousel container itself: the text goes on its image items instead.

How do you read alt text back?

Request the alt_text field on the published image, GET /<IG_MEDIA_ID>?fields=alt_text. It is a public field of the media object, so it can also be requested for a carousel's images through the children edge, which lists the photos and videos inside the post.

Can alt text be changed after publishing?

Meta documents no way to. The only update its media reference lists for a published post turns comments on or off, so the alt text is written into the container before the post goes live, alongside the caption and the image URL.

Common mistakes

  • Sending alt_text with a Reel or a Story. Meta supports it on image posts only.
  • Putting it on the carousel container. Alt text belongs to each image item inside the carousel.
  • Writing past 1,000 characters. That is the most one image's alternative text can hold.
Doing this with EasyCoexistence

The tool takes no alt_text, so the description is added in the Instagram app, from the post's Edit option. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

How long can alt text be through the Instagram API?

Up to 1,000 characters per image, set with alt_text on each image's container, so each image in a carousel takes its own text.

Can a Reel have alt text through the API?

No. Meta does not support alt_text on Reels or Stories.

How do I add alt text to a carousel?

Set alt_text on the container of each image item, created with is_carousel_item set to true, before you create the carousel container.

When did Instagram's API add alt text?

Meta introduced the alt_text field for image posts on 24 March 2025.

Keep reading

Connect your first channel in two minutes.

No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.

  • 3 days free
  • Cancel any time
  • Official APIs only
  • Monitored 24/7

Verified on