Comment fonctionne le maximum d'éléments d'un carrousel de l'API Threads

Quelle est la limite du maximum d'éléments d'un carrousel de l'API Threads ?

Meta place le maximum d'éléments d'un carrousel de l'API Threads à 20 enfants, avec un plancher de 2, et énonce la paire quatre fois sur deux pages. Le guide des posts ouvre sa section carrousel par « You may publish up to 20 images, videos, or a mix of the two in a carousel post », puis liste la règle deux fois de plus sous Limitations : « Carousels are limited to 20 images, videos, or a mix of the two » et « Carousels require a minimum of two children. »

La page de présentation dit la même chose en une ligne sous Other Limitations : « Carousel posts must have a maximum of 20 children and a minimum of 2 children. » La description du paramètre children le répète une quatrième fois : « Carousels must have at least 2 and no more than 20 total images, videos, or a mix of the two. »

Quatre énoncés, un seul nombre. Ce niveau de concordance est inhabituel dans la documentation de publication de Meta et il signifie qu'une intégration peut coder la vérification des bornes en dur sans se demander quelle page est périmée.

Quand le plafond des carrousels Threads est-il passé à 20 ?

Le 19 septembre 2024, et Meta a consigné le changement dans le changelog Threads : « Carousel posts are now allowed up to 20 images, videos, or a mix of the two. » Avant cette entrée, le plafond était de 10, comme sur Instagram.

Cette date compte quand on audite du code ancien. Un 10 codé en dur est la première chose à chercher dans toute intégration Threads écrite avant septembre 2024 ou portée depuis une bibliothèque de publication Instagram, parce qu'il découpe en silence un jeu de 16 images en deux posts qui brûlent chacun un créneau du quota de publication quotidien.

Comment fonctionne le flux de conteneurs par élément ?

Publier un carrousel Threads prend trois appels, un de plus qu'un post simple. Meta le décrit comme la création des « the individual media containers for each image and video », puis d'« a single carousel container to contain the media containers », puis de la publication.

L'étape 1 crée un conteneur par élément. Le paramètre distinctif est is_carousel_item=true, et media_type accepte ici IMAGE ou 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"

Chaque appel renvoie un ID de conteneur. Répétez-le pour chaque élément, jusqu'à 20.

L'étape 2 crée le conteneur de carrousel lui-même, avec media_type=CAROUSEL et une liste children séparée par des virgules des ID de l'étape 1. Le text du post appartient à cet appel, pas aux éléments individuels :

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"

L'étape 3 publie le conteneur de carrousel en passant son ID comme creation_id à POST /{threads-user-id}/threads_publish, qui renvoie l'ID du média publié. Meta conseille d'attendre « on average 30 seconds before publishing a Threads media container to give our server enough time to fully process the upload », et pour les éléments vidéo recommande d'interroger GET /{threads-container-id}?fields=status,error_message « once per minute, for no more than 5 minutes ».

Où les pages de Meta se contredisent-elles sur les éléments de carrousel ?

is_carousel_item reçoit deux classifications différentes sur deux pages en ligne. Le guide des posts le marque « Required » dans le tableau des paramètres des posts simples, avec les valeurs true et false (par défaut). La référence POST /{threads-user-id}/threads marque le même paramètre « Optional », avec les valeurs true et false (par défaut).

Comme les deux pages s'accordent sur une valeur par défaut à false, c'est la référence qui est cohérente : un paramètre doté d'une valeur par défaut ne peut pas être obligatoire. Le même tableau dans la section carrousel porte aussi une note recopiée depuis le tableau des posts simples, « CAROUSEL is not available for single thread posts », ce qui est vrai mais n'a rien à voir avec un élément de carrousel. Lisez les tableaux de paramètres pour les valeurs et la référence pour savoir si un champ est obligatoire.

Que renvoie un carrousel trop grand ?

Meta ne documente aucune erreur pour une liste children qui sort des bornes. L'index de l'API Reference de Threads liste neuf pages de points de terminaison et aucune page de codes d'erreur, et developers.facebook.com/documentation/threads/reference/error-codes ne répond pas. La page de dépannage ne couvre que deux choses : les valeurs de status d'un conteneur et les échecs de traitement média.

Chacune d'elles décrit un fichier média unique, pas une liste children malformée. Le seul code d'erreur du chemin de publication que Meta nomme quelque part dans la documentation Threads est THREADS_API__LINK_LIMIT_EXCEEDED, qui se déclenche quand un post porte plus de cinq liens.

Il n'y a donc rien à intercepter par son nom. Validez la longueur de children avant l'appel de l'étape 2, rejetez localement tout ce qui est sous 2 ou au-dessus de 20, et traitez ce que l'API renvoie pour une liste hors bornes comme un comportement non documenté qui peut changer sans entrée de changelog.

Un carrousel compte-t-il pour un post ou pour vingt ?

Pour un. Meta le dit aux deux endroits où l'on chercherait la règle : « Carousel posts count as a single post against a profile's rate limit » dans la section carrousel, et « Publishing a carousel counts as a single post » dans la note au-dessus de l'étape 3.

Cela fait du carrousel le plus gros levier disponible sur le volume de publication Threads. Un profil plafonné à 250 posts publiés par l'API sur une période mobile de 24 heures peut faire passer 5 000 pièces de média si chaque publication est un carrousel plein de 20 éléments, contre 250 si chaque post porte une seule image. Vingt posts simples coûtent vingt créneaux ; les mêmes vingt images en un carrousel en coûtent un.

Comment le carrousel Threads se compare-t-il à celui d'Instagram ?

Les deux tournent sur l'infrastructure Meta et aucun des deux plafonds ne correspond à l'autre. Le guide de publication de contenu d'Instagram dit « Carousels are limited to 10 images, videos, or a mix of the two », la moitié du nombre de Threads, et son quota de publication est plus bas aussi.

Publier le même jeu sur les deux réseaux demande donc une règle de découpe, puisqu'un carrousel Threads de 18 images n'entre pas dans un post Instagram. Le versant Instagram de cette arithmétique, y compris la seconde phrase sur le nombre de posts que Meta laisse en suspens sur sa propre page, est traité dans la limite de 100 posts par 24 heures de l'API Instagram.

Que doit respecter chaque élément d'un carrousel ?

Le plafond de 20 éléments est un compte, pas un budget de taille, et chaque enfant est validé pour lui-même contre les mêmes spécifications média qui régissent les posts simples. Les images doivent être en JPEG ou PNG, 8 Mo maximum, un rapport d'aspect dans les 10:1, avec une largeur minimale de 320 et un maximum de 1440 que Meta met à l'échelle automatiquement. Les vidéos doivent être en MOV ou MP4, 1 Go maximum, 300 secondes maximum, de 23 à 60 FPS, avec un maximum de 1920 pixels horizontaux.

Un seul enfant trop lourd fait échouer son propre conteneur à l'étape 1, ce qui veut dire que le conteneur de carrousel n'est jamais construit. Valider les médias avant le premier appel coûte moins cher que de découvrir à l'étape 2 qu'un ID sur dix-neuf manque, une habitude qui vaut pour les posts carrousel sur tous les réseaux.

Le texte du post a son propre plafond séparé de 500 caractères sur le conteneur de carrousel, régi par les mêmes règles que celles traitées dans comment la limite de 500 caractères de l'API Threads traite topic_tag.

Questions fréquentes

Un carrousel Threads peut-il mélanger images et vidéos ?

Oui. La formulation de Meta est « 20 images, videos, or a mix of the two » sur chaque page qui énonce la limite, un carrousel peut donc contenir n'importe quelle combinaison tant que le total reste entre 2 et 20 et que chaque élément respecte sa propre spécification média.

Quel est le nombre minimum d'éléments dans un carrousel Threads ?

Deux. Meta écrit « Carousels require a minimum of two children » dans le guide des posts et le répète sur la page de présentation sous la forme « a minimum of 2 children ». Un carrousel à un seul élément n'est pas un conteneur valide, publiez donc une image seule comme un post IMAGE normal.

Un carrousel de 20 éléments consomme-t-il 20 créneaux du quota de publication quotidien ?

Non. Meta indique que « Carousel posts count as a single post against a profile's rate limit », un carrousel plein de 20 éléments dépense donc une des 250 publications disponibles sur une période mobile de 24 heures.

Où va le texte d'un post carrousel ?

Sur le conteneur de carrousel créé à l'étape 2, où text est listé comme paramètre optionnel à côté de media_type=CAROUSEL et de children. Les conteneurs d'éléments individuels de l'étape 1 acceptent aussi text, et Meta ne dit jamais à quoi sert cette valeur sur un élément de carrousel.

Créer les conteneurs d'éléments de carrousel consomme-t-il du quota ?

Meta applique la limite de publication « on the POST /{threads-user-id}/threads_publish endpoint », c'est-à-dire à l'étape 3, les conteneurs d'éléments de l'étape 1 et le conteneur de carrousel de l'étape 2 ne dépensent donc pas de quota de publication. Les conteneurs expirent bien : un conteneur non publié renvoie EXPIRED, décrit comme « The container was not published within 24 hours and has expired. »

Où la limite de 20 éléments par carrousel est-elle documentée ?

À quatre endroits sur deux pages de Meta. Le guide des posts à developers.facebook.com/documentation/threads/posts l'énonce dans l'introduction de la section carrousel, dans sa liste Limitations et dans la description du paramètre children ; la page de présentation à developers.facebook.com/documentation/threads/overview l'énonce sous Other Limitations. Le passage de 10 à 20 est consigné dans le changelog Threads au 19 septembre 2024.

Le paramètre is_carousel_item est-il obligatoire ou optionnel ?

Les pages de Meta se contredisent sur ce point. Le guide des posts marque ce paramètre comme « Obligatoire » dans son tableau, tandis que la référence de POST /{threads-user-id}/threads marque le même paramètre comme « Optionnel » avec une valeur par défaut de false. Comme les deux pages s'accordent sur cette valeur par défaut, un paramètre avec une valeur par défaut ne peut pas être obligatoire, donc c'est la page de référence qu'il faut suivre.

Quels formats de fichiers et limites de taille s'appliquent à un élément de carrousel Threads ?

Chaque élément est validé selon les mêmes spécifications média qu'un post seul, quel que soit le carrousel auquel il appartient. Les images doivent être en JPEG ou PNG, jusqu'à 8 Mo, avec un rapport d'aspect dans une limite de 10:1. Les vidéos doivent être en MOV ou MP4, jusqu'à 1 Go et 300 secondes, entre 23 et 60 images par seconde.

Combien de temps attendre avant de publier un conteneur de carrousel ?

Meta recommande d'attendre environ 30 secondes après la création d'un conteneur avant d'appeler threads_publish, pour laisser à ses serveurs le temps de traiter l'upload. Pour les éléments vidéo, il faut interroger GET /{threads-container-id}?fields=status,error_message une fois par minute, pendant 5 minutes maximum, avant de considérer le conteneur comme prêt.

Existe-t-il un code d'erreur nommé pour un carrousel avec trop ou pas assez d'éléments ?

Meta n'en documente aucun. Le seul code d'erreur de publication nommé dans toute la documentation Threads est THREADS_API__LINK_LIMIT_EXCEEDED, qui se déclenche quand un post contient plus de cinq liens. Une liste children hors de la plage 2 à 20 ne déclenche aucune erreur documentée, mieux vaut donc valider la longueur en local avant l'appel de l'étape 2.