Cómo funciona el máximo de elementos de carrusel de la API de Threads

¿Cuál es el límite máximo de elementos de carrusel de la API de Threads?

Meta sitúa el techo del máximo de elementos de carrusel de la API de Threads en 20 hijos, con un suelo de 2, y enuncia la pareja cuatro veces repartidas en dos páginas. La guía de posts abre su sección de carruseles con "You may publish up to 20 images, videos, or a mix of the two in a carousel post", y luego lista la regla dos veces más bajo Limitations: "Carousels are limited to 20 images, videos, or a mix of the two" y "Carousels require a minimum of two children."

La página general dice lo mismo en una línea bajo Other Limitations: "Carousel posts must have a maximum of 20 children and a minimum of 2 children." La descripción del parámetro children lo repite por cuarta vez: "Carousels must have at least 2 and no more than 20 total images, videos, or a mix of the two."

Cuatro afirmaciones, un número. Ese nivel de acuerdo es raro en la documentación de publicación de Meta y significa que una integración puede escribir a fuego la comprobación de límites sin preocuparse por cuál de las páginas está desactualizada.

¿Cuándo pasó a ser 20 el tope de carrusel de Threads?

El 19 de septiembre de 2024, y Meta registró el cambio en el changelog de Threads: "Carousel posts are now allowed up to 20 images, videos, or a mix of the two." Antes de esa entrada el techo era 10, igual que en Instagram.

Esa fecha importa al auditar código antiguo. Un 10 escrito a fuego es lo primero que hay que buscar en cualquier integración de Threads escrita antes de septiembre de 2024 o portada desde una librería de publicación de Instagram, porque parte en silencio un conjunto de 16 imágenes en dos posts que queman cada uno un espacio de la cuota diaria de publicación.

¿Cómo funciona el flujo de contenedores por elemento?

Publicar un carrusel de Threads son tres llamadas, una más que un post normal. Meta lo describe como crear "the individual media containers for each image and video", luego "a single carousel container to contain the media containers", y después la publicación.

El paso 1 crea un contenedor por elemento. El parámetro que lo distingue es is_carousel_item=true, y aquí media_type acepta IMAGE o VIDEO:

curl -i -X POST \
  -d "image_url=<IMAGE_URL>" \
  -d "is_carousel_item=true" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Cada llamada devuelve un ID de contenedor. Repítela para cada elemento, hasta 20.

El paso 2 crea el contenedor del carrusel en sí, con media_type=CAROUSEL y una lista children separada por comas con los IDs del paso 1. El text del post va en esta llamada, no en los elementos individuales:

curl -i -X POST \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>,..." \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

El paso 3 publica el contenedor del carrusel pasando su ID como creation_id a POST /{threads-user-id}/threads_publish, que devuelve el ID del medio publicado. Meta aconseja esperar "on average 30 seconds before publishing a Threads media container to give our server enough time to fully process the upload", y para elementos de video recomienda consultar GET /{threads-container-id}?fields=status,error_message "once per minute, for no more than 5 minutes".

¿Dónde se contradicen las propias páginas de Meta sobre los elementos de carrusel?

is_carousel_item recibe dos clasificaciones distintas en dos páginas vivas. La guía de posts lo marca "Required" en la tabla de parámetros de los posts de hilo simple, con los valores true y false (default). La referencia de POST /{threads-user-id}/threads marca el mismo parámetro "Optional", con los valores true y false (default).

Como las dos páginas coinciden en que el valor por defecto es false, la coherente es la referencia: un parámetro con valor por defecto no puede ser obligatorio. Esa misma tabla en la sección de carruseles también arrastra una nota copiada de la tabla de posts simples, "CAROUSEL is not available for single thread posts", que es cierta pero no tiene nada que ver con un elemento de carrusel. Lee las tablas de parámetros para los valores y la referencia para saber si un campo es obligatorio.

¿Qué devuelve un carrusel demasiado grande?

Meta no documenta ningún error para una lista children que rompa los límites. El índice de la referencia de la API de Threads lista nueve páginas de endpoints y ninguna página de códigos de error, y developers.facebook.com/documentation/threads/reference/error-codes no resuelve. La página de troubleshooting cubre solo dos cosas: valores de status de contenedor y fallos de procesamiento de medios.

Todos ellos describen un único archivo de medios, no una lista children mal formada. El único código de error del camino de publicación que Meta nombra en toda la documentación de Threads es THREADS_API__LINK_LIMIT_EXCEEDED, que salta cuando un post lleva más de cinco enlaces.

Así que no hay nada que capturar por nombre. Valida la longitud de children antes de la llamada del paso 2, rechaza en local cualquier cosa por debajo de 2 o por encima de 20, y trata lo que devuelva la API para una lista fuera de límites como comportamiento no documentado que puede cambiar sin entrada en el changelog.

¿Un carrusel cuenta como un post o como veinte?

Como uno. Meta lo dice en los dos sitios donde se buscaría la regla: "Carousel posts count as a single post against a profile's rate limit" en la sección de carruseles, y "Publishing a carousel counts as a single post" en la nota sobre el paso 3.

Eso convierte al carrusel en la mayor palanca que existe sobre el volumen de publicación en Threads. Un perfil limitado a 250 posts publicados por la API dentro de un periodo móvil de 24 horas puede mover 5.000 piezas de medios si cada publicación es un carrusel completo de 20 elementos, frente a 250 si cada post lleva una imagen. Veinte posts sueltos cuestan veinte espacios; esas mismas veinte imágenes como un carrusel cuestan uno.

¿Cómo se compara el carrusel de Threads con el de Instagram?

Los dos corren sobre infraestructura de Meta y ninguno de los techos coincide con el otro. La guía de publicación de contenido de Instagram afirma "Carousels are limited to 10 images, videos, or a mix of the two", la mitad del número de Threads, y su cuota de publicación también es menor.

Publicar el mismo conjunto en ambas necesita por tanto una regla de partición, ya que un carrusel de 18 imágenes de Threads no cabe en un post de Instagram. La parte de esa aritmética que toca a Instagram, incluida la segunda frase con recuento de posts que Meta deja sin resolver en su propia página, está cubierta en el límite de 100 posts por 24 horas de la API de Instagram.

¿Qué tiene que cumplir cada elemento del carrusel?

El techo de 20 elementos es un recuento, no un presupuesto de tamaño, y cada hijo se valida por su cuenta contra las mismas especificaciones de medios que rigen los posts simples. Las imágenes tienen que ser JPEG o PNG, 8 MB como máximo, relación de aspecto dentro de 10:1, con un ancho mínimo de 320 y un máximo de 1440 que Meta escala automáticamente. Los videos tienen que ser MOV o MP4, 1 GB como máximo, 300 segundos como máximo, de 23 a 60 FPS y con un máximo de 1920 píxeles horizontales.

Un solo hijo demasiado grande hace fallar su propio contenedor en el paso 1, lo que significa que el contenedor del carrusel nunca llega a construirse. Validar los medios antes de la primera llamada sale más barato que descubrir en el paso 2 que falta uno de diecinueve IDs, un hábito que sirve para los posts de carrusel en cualquier red.

El texto del post tiene su propio techo aparte de 500 caracteres en el contenedor del carrusel, regido por las mismas reglas cubiertas en cómo trata el límite de 500 caracteres de la API de Threads a topic_tag.

Preguntas frecuentes

¿Un carrusel de Threads puede mezclar imágenes y videos?

Sí. La redacción de Meta es "20 images, videos, or a mix of the two" en todas las páginas que enuncian el límite, así que un carrusel puede llevar cualquier combinación mientras el total se quede entre 2 y 20 y cada elemento cumpla su propia especificación de medios.

¿Cuál es el número mínimo de elementos de un carrusel de Threads?

Dos. Meta afirma "Carousels require a minimum of two children" en la guía de posts y lo repite en la página general como "a minimum of 2 children". Un carrusel de un solo elemento no es un contenedor válido, así que publica una imagen suelta como post IMAGE normal.

¿Un carrusel de 20 elementos gasta 20 espacios de la cuota diaria de publicación?

No. Meta afirma que "Carousel posts count as a single post against a profile's rate limit", así que un carrusel completo de 20 elementos gasta una de las 250 publicaciones disponibles en un periodo móvil de 24 horas.

¿Dónde va el texto de un post de carrusel?

En el contenedor del carrusel creado en el paso 2, donde text aparece como parámetro opcional junto a media_type=CAROUSEL y children. Los contenedores de elementos individuales del paso 1 también aceptan text, y Meta nunca dice qué hace ese valor en un elemento de carrusel.

¿Crear contenedores de elementos de carrusel gasta alguna cuota?

Meta aplica el límite de publicación "on the POST /{threads-user-id}/threads_publish endpoint", que es el paso 3, así que los contenedores de elementos del paso 1 y el contenedor del carrusel del paso 2 no gastan cuota de publicación. Los contenedores sí caducan: uno sin publicar devuelve EXPIRED, descrito así: "The container was not published within 24 hours and has expired."

¿Dónde está documentado el límite de 20 elementos por carrusel?

En cuatro sitios repartidos en dos páginas de Meta. La guía de posts en developers.facebook.com/documentation/threads/posts lo indica en la introducción de carruseles, en su lista de Limitations y en la descripción del parámetro children; la página general en developers.facebook.com/documentation/threads/overview lo indica bajo Other Limitations. El cambio de 10 a 20 está registrado en el changelog de Threads bajo el 19 de septiembre de 2024.

¿El parámetro is_carousel_item es obligatorio u opcional?

Las propias páginas de Meta se contradicen. La guía de posts marca este parámetro como "Obligatorio" en su tabla, mientras que la referencia de POST /{threads-user-id}/threads marca el mismo parámetro como "Opcional" con un valor por defecto de false. Como ambas páginas coinciden en ese valor por defecto, un parámetro con un valor por defecto no puede ser obligatorio, así que la referencia es la página que hay que seguir.

¿Qué formatos de archivo y límites de tamaño aplican a un elemento de carrusel de Threads?

Cada elemento se valida con las mismas especificaciones de medios que un post individual, sin importar el carrusel al que pertenezca. Las imágenes deben ser JPEG o PNG, de hasta 8 MB, con una relación de aspecto dentro de 10:1. Los videos deben ser MOV o MP4, de hasta 1 GB y 300 segundos, entre 23 y 60 FPS.

¿Cuánto hay que esperar antes de publicar un contenedor de carrusel?

Meta recomienda esperar unos 30 segundos después de crear un contenedor antes de llamar a threads_publish, para dar tiempo a sus servidores a procesar la subida. Para elementos de video, hay que consultar GET /{threads-container-id}?fields=status,error_message una vez por minuto, durante un máximo de 5 minutos, antes de asumir que el contenedor está listo.

¿Existe un código de error con nombre para un carrusel con demasiados o muy pocos elementos?

Meta no documenta ninguno. El único código de error de publicación que Meta nombra en toda la documentación de Threads es THREADS_API__LINK_LIMIT_EXCEEDED, que salta cuando un post lleva más de cinco enlaces. Una lista de children fuera del rango de 2 a 20 no genera ningún error documentado, así que conviene validar la longitud localmente antes de la llamada del paso 2.