Meta fija en 1.000 el límite de caracteres de alt_text en la API de Instagram

¿Cuál es el límite de caracteres de alt_text en la API de Instagram?

La propia referencia de Meta fija el límite de caracteres de alt_text en la API de Instagram en 1.000 y restringe el campo a imágenes fijas. La descripción del parámetro en el endpoint de creación de medios dice, palabra por palabra: "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."

Una frase, tres reglas distintas. El techo es 1.000. El campo pertenece a una imagen, ya sea suelta o dentro de un carrusel. Reels y stories quedan excluidos por su nombre. Todo lo demás que la gente cree sobre el texto alternativo de Instagram viene de un sitio que no es esa frase.

El campo vive en la llamada de creación del contenedor:

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>

Pasas alt_text cuando creas el contenedor, no cuando lo publicas. El paso de publicación, POST /<IG_ID>/media_publish, recibe un creation_id y nada más que toque la accesibilidad. Si olvidas el campo en el contenedor, no hay segunda oportunidad en el mismo flujo.

Meta fecha la función con precisión. La guía de publicación de contenido 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." Todo lo escrito sobre la API de publicación de Instagram antes de esa fecha describe un mundo sin ningún texto alternativo programático.

Antes y después del 24 de marzo de 2025

Antes

• Sin campo alt_text en la API de publicación
• Sin forma programática de añadir descripciones de imagen

Después

• Campo alt_text activo en el endpoint de medios
• Hasta 1.000 caracteres, solo para imágenes

¿Qué tipos de medios de Instagram aceptan alt_text?

Solo imágenes. Esta es la tabla completa, sacada de la descripción del parámetro y de la lista de tipos de medio de la misma página de referencia.

Contenedor	alt_text aceptado	Lo que dice la documentación
Imagen suelta (sin media_type)	Sí	"Only supported on a single image"
Imagen dentro de un carrusel (is_carousel_item=true)	Sí	"or image media in a carousel"
Contenedor de carrusel (media_type=CAROUSEL)	No	El campo describe una imagen, y el contenedor guarda hijos, no píxeles
media_type=REELS	No	"Reels and stories are not supported"
media_type=STORIES	No	"Reels and stories are not supported"
Vídeo	No figura	El parámetro está acotado a "for an image", y no hay ningún contenedor de vídeo documentado que lo acepte

Lee la última fila con atención, porque es la que se cita mal. Meta no escribe las palabras "video is not supported". Escribe que el parámetro es texto alternativo "for an image", y nombra Reels y stories como las exclusiones. Este endpoint publica el vídeo suelto como REELS, que la frase descarta directamente. El resultado práctico coincide con el atajo que todo el mundo repite, pero la documentación llega ahí por alcance y no por prohibición, y una página de especificación debería decir cuál de las dos cosas es.

¿Por qué el número de la app es distinto del número de la API?

La documentación para desarrolladores de Meta publica exactamente un límite de texto alternativo: 1.000 caracteres, en el parámetro alt_text. No publica ningún límite para la casilla de texto alternativo dentro de la app de Instagram.

Esta es la brecha que conviene nombrar. Las guías de accesibilidad y los blogs de redes sociales hacen circular una cifra dentro de la app mucho más corta, citada sin ningún enlace de vuelta a Meta. Esa cifra no aparece por ninguna parte en la documentación para desarrolladores de Meta, y tampoco aparece en el changelog, que no tiene ninguna entrada sobre alt_text. Por eso esta página no la repite. Si necesitas saber cuántos caracteres acepta el compositor de la app, la respuesta disponible de Meta es que Meta no lo dice.

Lo que sí tienes es una cifra firme para la única superficie que se documenta a sí misma. Si tu texto alternativo pasa por la API, 1.000 caracteres es el presupuesto, y es el único presupuesto al que Meta se compromete por escrito. La restricción sobre la que la gente planifica resulta no ser la que existe.

¿Cómo se compara el límite de alt_text con el límite de caption?

La misma página de referencia documenta los dos, así que la comparación es directa.

Campo	Techo	Reglas adicionales
alt_text	1.000 caracteres	Solo imágenes. Ni Reels ni stories
caption	2.200 caracteres	Máximo 30 hashtags y 20 etiquetas @

La descripción de la caption de Meta es explícita sobre los recuentos de etiquetas: "Maximum 2200 characters, 30 hashtags, and 20 @ tags." La descripción de alt_text no lleva subreglas equivalentes. No hay tope de hashtags documentado, ni tope de menciones, ni tratamiento del marcado. Es un campo de texto plano con un techo.

Esa asimetría importa cuando construyes un compositor. Un validador de caption necesita tres contadores. Un validador de texto alternativo necesita uno, más una comprobación del tipo de medio que eligió la persona.

¿Dónde va alt_text en una publicación de carrusel?

En cada contenedor hijo, de uno en uno. Un carrusel se construye en dos etapas. Primero un contenedor por elemento con is_carousel_item=true, después el padre con media_type=CAROUSEL y un array children con esos ID. La nota de Meta sobre is_carousel_item dice: "Applies only to images and video. Set to true. Indicates image or video appears in a carousel."

El texto alternativo se engancha en el nivel del hijo, algo que se deduce de la descripción del parámetro, que cubre "image media in a carousel." Diez diapositivas significan diez valores alt_text separados, escritos para diez imágenes separadas. No hay ningún campo a nivel de padre que describa el conjunto, ni forma de escribir una sola cadena que cubra todo el deslizamiento. Los equipos que procesan carruseles por lotes con una herramienta de programación para Instagram chocan con esto de inmediato. El trabajo de texto alternativo escala con el número de diapositivas, no con el número de publicaciones.

Los hijos de vídeo dentro de un carrusel heredan el mismo problema de alcance que el vídeo suelto. El contenedor hijo acepta is_carousel_item, pero alt_text está documentado para medios de imagen.

¿Qué pasa con el texto alternativo en Reels y Stories?

Nada, porque el campo no existe ahí. Si envías alt_text en un contenedor REELS o STORIES, estás enviando un parámetro que el endpoint no documenta. No hay soporte parcial, ni truncado, ni recurso a la caption.

Esto deja un agujero real para quien publica vídeo a volumen a través de la API de publicación de Instagram. La descripción accesible tiene que vivir en otro sitio, lo que en la práctica significa la caption, el texto en pantalla o los subtítulos quemados en el propio vídeo. Son decisiones editoriales, no campos de la API, y pertenecen al calendario de contenidos con el que tu equipo ya trabaja.

¿Cómo se usan de verdad 1.000 caracteres?

La mayoría de los textos alternativos no los necesitan, y la longitud no es el objetivo. El valor de conocer el techo real es que elimina el motivo equivocado para ser breve. Cuando una fotografía lleva un gráfico, una carta, una lista de precios, un horario o texto denso sobre la imagen, ya no eliges entre una descripción y un resumen. Tienes sitio para las dos cosas.

Para una imagen densa, empieza por el sujeto y lo que está haciendo, luego el entorno, luego cualquier texto visible en el encuadre, transcrito en lugar de parafraseado. Sáltate "imagen de" y "foto de", porque la tecnología de asistencia ya anuncia el elemento. Deja la voz de marca en la caption, donde un redactor de captions con IA hace ese trabajo, y deja que el texto alternativo describa lo que hay.

El único número sobre el que diseñar es 1.000, por contenedor, solo imágenes. Todo lo demás sobre el texto alternativo de Instagram es criterio editorial o un comportamiento de la app sin documentar al que Meta no se ha comprometido por escrito.

Preguntas frecuentes

¿Cuál es la longitud máxima de alt_text en la API de Instagram?

1.000 caracteres. La referencia de Meta para el endpoint de creación de medios describe el parámetro como "Alternative text, up to 1000 character, for an image", y ese es el único techo de texto alternativo publicado en la documentación para desarrolladores.

¿La API de Instagram admite alt_text en Reels?

No. La documentación de Meta afirma con claridad que "Reels and stories are not supported" para el campo alt_text, tanto en la descripción del parámetro como en la nota de lanzamiento de la guía de publicación de contenido.

¿Se puede poner texto alternativo en cada diapositiva de un carrusel de Instagram?

Sí, en cada contenedor hijo. La descripción del parámetro cubre "image media in a carousel", así que pasas alt_text junto a is_carousel_item=true al crear cada hijo de imagen, antes de montar el contenedor padre CAROUSEL.

¿El límite de texto alternativo de la app de Instagram es el mismo que el de la API?

La documentación para desarrolladores de Meta no publica un límite de caracteres para el campo de texto alternativo de la app de Instagram, así que los dos no se pueden comparar desde una fuente citable. La cifra de 1.000 caracteres se aplica al parámetro alt_text de la API.

¿Cuándo añadió Instagram alt_text a su API de publicación?

El 24 de marzo de 2025. La guía de publicación de contenido recoge la fecha de lanzamiento y la acota a las publicaciones de imagen en el endpoint /<INSTAGRAM_PROFESSIONAL_ACCOUNT_ID>/media.

¿alt_text cuenta para el límite de caption de Instagram?

No. Son parámetros separados con techos separados en el mismo contenedor: caption permite 2.200 caracteres con un máximo de 30 hashtags y 20 etiquetas @, mientras que alt_text permite 1.000 caracteres sin subreglas documentadas.

¿Se puede añadir alt_text a una publicación de video independiente mediante la API?

El video no figura entre los contenedores que aceptan alt_text. La descripción del parámetro limita el campo a "para una imagen", y este endpoint publica el video independiente mediante un contenedor REELS, uno de los dos tipos que la documentación excluye por nombre.

¿En qué paso del flujo de publicación se configura alt_text?

alt_text se pasa al crear el contenedor, en el POST inicial a /<IG_ID>/media, no en el paso de publicación. La llamada media_publish solo acepta un creation_id, así que no hay una segunda oportunidad de añadir texto alternativo si el contenedor se creó sin él.

¿Qué ocurre si de todos modos se envía alt_text a un contenedor de Reels o Stories?

Nada útil, porque el endpoint no documenta el campo para esos tipos de contenedor. La referencia de Meta no describe soporte parcial, ni truncamiento, ni un respaldo que copie el texto a la leyenda.

¿El campo alt_text tiene reglas adicionales como el campo caption?

Carece de ellas. El parámetro caption documenta un tope de 30 hashtags y 20 menciones con @ además de su límite de caracteres, mientras que la descripción de alt_text no incluye nada de eso, solo el tope de 1.000 caracteres y el alcance limitado a imágenes.