Meta fixa em 1.000 o limite de caracteres do alt_text na API do Instagram

Qual é o limite de caracteres do alt_text na API do Instagram?

A própria referência da Meta fixa o limite de caracteres do alt_text na API do Instagram em 1.000 caracteres e restringe o campo a imagens estáticas. A descrição do parâmetro no endpoint de criação de mídia diz, palavra por palavra: "Alternative text, up to 1000 character, for an image. Only supported on a single image or image media in a carousel. Reels and stories are not supported."

Uma frase, três regras separadas. O teto é 1.000. O campo pertence a uma imagem, sozinha ou dentro de um carrossel. Reels e stories ficam excluídos pelo nome. Todo o resto que as pessoas acreditam sobre o texto alternativo do Instagram vem de algum lugar que não é essa frase.

O campo fica na chamada de criação do contêiner:

POST https://graph.facebook.com/v25.0/<IG_ID>/media
  ?image_url=https://example.com/photo.jpg
  &alt_text=A%20hand-drawn%20site%20plan%20pinned%20to%20a%20studio%20wall
  &caption=Week%20four
  &access_token=<TOKEN>

Você passa alt_text quando cria o contêiner, não quando publica. A etapa de publicação, POST /<IG_ID>/media_publish, recebe um creation_id e mais nada que envolva acessibilidade. Se esquecer o campo no contêiner, não há segunda chance no mesmo fluxo.

A Meta data o recurso com precisão. O guia de publicação de conteúdo afirma: "On March 24, 2025, we introduced the new alt_text field for image posts on the /<INSTAGRAM_PROFESSIONAL_ACCOUNT_ID>/media endpoint. Reels and stories are not supported." Tudo o que foi escrito sobre a API de publicação do Instagram antes dessa data descreve um mundo sem nenhum texto alternativo programático.

Antes e depois de 24 de março de 2025

Antes

• Nenhum campo alt_text na API de publicação
• Nenhuma forma programática de descrever imagens

Depois

• Campo alt_text ativo no endpoint de mídia
• Até 1.000 caracteres, apenas para imagens

Quais tipos de mídia do Instagram aceitam alt_text?

Só imagens. Aqui está a tabela completa, tirada da descrição do parâmetro e da lista de tipos de mídia na mesma página de referência.

Contêiner	alt_text aceito	O que a documentação diz
Imagem única (sem media_type)	Sim	"Only supported on a single image"
Imagem dentro de um carrossel (is_carousel_item=true)	Sim	"or image media in a carousel"
Contêiner de carrossel (media_type=CAROUSEL)	Não	O campo descreve uma imagem, e o contêiner guarda filhos, não pixels
media_type=REELS	Não	"Reels and stories are not supported"
media_type=STORIES	Não	"Reels and stories are not supported"
Vídeo	Não listado	O parâmetro está delimitado a "for an image", e nenhum contêiner de vídeo está documentado como aceitando o campo

Leia a última linha com atenção, porque é a que mais é citada errado. A Meta não escreve as palavras "video is not supported". Ela escreve que o parâmetro é texto alternativo "for an image", e cita Reels e stories como as exclusões. Esse endpoint publica vídeo avulso como REELS, o que a frase descarta diretamente. O resultado prático bate com o atalho que todo mundo repete, mas a documentação chega lá por escopo e não por proibição, e uma página de especificação deveria dizer qual dos dois vale.

Por que o número do app é diferente do número da API?

A documentação para desenvolvedores da Meta publica exatamente um limite de texto alternativo: 1.000 caracteres, no parâmetro alt_text. Ela não publica nenhum limite para a caixa de texto alternativo dentro do app do Instagram.

Essa é a lacuna que vale nomear. Guias de acessibilidade e blogs de redes sociais fazem circular um número no app bem mais curto, citado sem nenhum link de volta para a Meta. Esse número não aparece em lugar nenhum da documentação para desenvolvedores da Meta, e também não aparece no changelog, que não traz nenhuma entrada sobre alt_text. Por isso esta página não o repete. Se você precisa saber quantos caracteres o compositor do app aceita, a resposta disponível na Meta é que a Meta não diz.

O que você tem no lugar é um número firme para a única superfície que se documenta. Se o seu texto alternativo passa pela API, 1.000 caracteres é o orçamento, e é o único orçamento com que a Meta se compromete por escrito. A restrição em torno da qual as pessoas planejam acaba não sendo a que existe.

Como o limite do alt_text se compara ao limite da legenda?

A mesma página de referência documenta os dois, então a comparação é direta.

Campo	Teto	Regras extras
alt_text	1.000 caracteres	Só imagens. Sem Reels, sem stories
caption	2.200 caracteres	Máximo de 30 hashtags e 20 marcações @

A descrição da legenda pela Meta é explícita sobre a contagem de marcações: "Maximum 2200 characters, 30 hashtags, and 20 @ tags." A descrição do alt_text não traz subregras equivalentes. Nenhum teto de hashtags está documentado, nenhum teto de menções, nenhum tratamento de marcação. É um campo de texto simples com um teto.

Essa assimetria importa quando você monta um compositor. Um validador de legenda precisa de três contadores. Um validador de texto alternativo precisa de um, mais uma checagem de qual tipo de mídia a pessoa escolheu.

Onde o alt_text entra em um post carrossel?

Em cada contêiner filho, um de cada vez. Um carrossel se monta em duas etapas. Primeiro um contêiner por item com is_carousel_item=true, depois o pai com media_type=CAROUSEL e um array children com esses IDs. A nota da Meta sobre is_carousel_item diz: "Applies only to images and video. Set to true. Indicates image or video appears in a carousel."

O texto alternativo se prende no nível do filho, o que decorre da descrição do parâmetro cobrir "image media in a carousel." Dez slides significam dez valores alt_text separados, escritos para dez imagens separadas. Não existe campo no nível do pai que descreva o conjunto, nem jeito de escrever uma string única que cubra o deslize inteiro. Equipes que processam carrosséis em lote com uma ferramenta de agendamento para Instagram esbarram nisso na hora. O trabalho de texto alternativo escala com a quantidade de slides, não com a quantidade de posts.

Filhos de vídeo dentro de um carrossel herdam o mesmo problema de escopo do vídeo avulso. O contêiner filho aceita is_carousel_item, mas alt_text está documentado para mídia de imagem.

O que acontece com o texto alternativo em Reels e Stories?

Nada, porque o campo não existe lá. Mande alt_text em um contêiner REELS ou STORIES e você está mandando um parâmetro que o endpoint não documenta. Não há suporte parcial, nem corte de texto, nem recurso à legenda.

Isso deixa um buraco real para quem publica vídeo em volume pela API de publicação do Instagram. A descrição acessível precisa morar em outro lugar, o que na prática significa a legenda, o texto na tela ou as legendas queimadas no próprio vídeo. São decisões editoriais, não campos de API, e pertencem ao calendário de conteúdo com que sua equipe já trabalha.

Como usar de fato 1.000 caracteres?

A maior parte dos textos alternativos não precisa deles, e comprimento não é o objetivo. O valor de saber o teto real é que ele elimina o motivo errado para ser breve. Quando uma foto carrega um gráfico, um cardápio, uma tabela de preços, uma programação ou texto denso sobre a imagem, você não escolhe mais entre uma descrição e um resumo. Tem espaço para os dois.

Para uma imagem densa, comece pelo assunto e pelo que ele está fazendo, depois o cenário, depois qualquer texto visível no enquadramento, transcrito em vez de parafraseado. Pule "imagem de" e "foto de", já que a tecnologia assistiva anuncia o elemento sozinha. Deixe a voz da marca na legenda, onde um redator de legendas com IA faz esse trabalho, e deixe o texto alternativo descrever o que está ali.

O único número em torno do qual projetar é 1.000, por contêiner, só imagens. Todo o resto sobre texto alternativo no Instagram é ou julgamento editorial ou um comportamento não documentado do app com que a Meta não se comprometeu por escrito.

Perguntas frequentes

Qual é o tamanho máximo do alt_text na API do Instagram?

1.000 caracteres. A referência da Meta para o endpoint de criação de mídia descreve o parâmetro como "Alternative text, up to 1000 character, for an image", e esse é o único teto de texto alternativo publicado na documentação para desenvolvedores.

A API do Instagram suporta alt_text em Reels?

Não. A documentação da Meta afirma com clareza que "Reels and stories are not supported" para o campo alt_text, tanto na descrição do parâmetro quanto na nota de lançamento do guia de publicação de conteúdo.

Dá para definir texto alternativo em cada slide de um carrossel do Instagram?

Sim, em cada contêiner filho. A descrição do parâmetro cobre "image media in a carousel", então você passa alt_text junto de is_carousel_item=true ao criar cada filho de imagem, antes de montar o contêiner pai CAROUSEL.

O limite de texto alternativo do app do Instagram é o mesmo da API?

A documentação para desenvolvedores da Meta não publica limite de caracteres para o campo de texto alternativo no app do Instagram, então os dois não podem ser comparados a partir de uma fonte citável. O número de 1.000 caracteres vale para o parâmetro de API alt_text.

Quando o Instagram adicionou alt_text à API de publicação?

Em 24 de março de 2025. O guia de publicação de conteúdo registra a data de lançamento e a delimita a posts de imagem no endpoint /<INSTAGRAM_PROFESSIONAL_ACCOUNT_ID>/media.

O alt_text conta para o limite de legenda do Instagram?

Não. São parâmetros separados com tetos separados no mesmo contêiner: caption permite 2.200 caracteres com máximo de 30 hashtags e 20 marcações @, enquanto alt_text permite 1.000 caracteres sem subregras documentadas.

Dá para adicionar alt_text a um post de vídeo independente pela API?

O vídeo não está entre os containers que aceitam alt_text. A descrição do parâmetro restringe o campo a "para uma imagem", e esse endpoint publica vídeo independente por meio de um container REELS, um dos dois tipos que a documentação exclui pelo nome.

Em qual etapa do fluxo de publicação se define o alt_text?

O alt_text é passado na criação do container, no POST inicial para /<IG_ID>/media, não na etapa de publicação. A chamada media_publish só aceita um creation_id, então não há uma segunda chance de anexar o texto alternativo depois que o container é criado sem ele.

O que acontece se alt_text for enviado mesmo assim em um container de Reels ou Stories?

Nada de útil, porque o endpoint não documenta esse campo para esses tipos de container. A referência da Meta não descreve suporte parcial, truncamento ou um fallback que copie o texto para a legenda.

O campo alt_text carrega regras extras como o campo caption?

O caption documenta um teto de 30 hashtags e 20 marcações com @ além do limite de caracteres. A descrição do alt_text não traz nada disso, apenas o teto de 1.000 caracteres e o escopo limitado a imagens.