Toutes les limites que l'API Reels d'Instagram impose à votre vidéo

Qu'accepte l'API Reels d'Instagram ?

Une vidéo poussée par l'API Reels d'Instagram doit franchir chaque ligne d'un bloc de spécifications publié avant que Meta ne la transcode, et ce bloc tient en un seul endroit : Reel Specifications, dans la référence IG User Media. Ratez-en une et le conteneur que vous avez créé avec media_type=REELS revient avec status_code réglé sur ERROR au lieu de FINISHED.

Voici la liste entière, copiée de la référence de Meta.

Quelle durée peut faire un reel par l'API ?

Quinze minutes. La ligne de Meta est « Duration: 15 mins maximum, 3 seconds minimum », ce qui place le plafond de l'API bien plus haut que la plupart des gens l'imaginent et le plancher plus haut que la plupart ne le remarquent.

Le minimum de trois secondes est celui qui mord. Un clip coupé à deux secondes et demie est un fichier parfaitement ordinaire partout ailleurs sur Internet et un refus immédiat ici. Pas de demi-mesure, et aucun remplissage ajouté du côté de Meta.

Le plafond de quinze minutes mérite une réserve que Meta n'y attache pas. Ce chiffre gouverne ce que l'API accepte dans un conteneur. Il ne dit rien de ce que l'application Instagram laissera une personne envoyer depuis un téléphone, ni de ce que le système de recommandation fera d'un reel de quatorze minutes une fois qu'il existera. Meta attache exactement ce type d'avertissement au paramètre share_to_feed, en notant qu'aucune des deux valeurs « determines whether the reel actually appears in the Reels tab because the reel may not meet eligibilty requirements or may not be selected by our algorithm. » Que l'API accepte un fichier et qu'Instagram le diffuse sont deux questions différentes.

Quelle taille peut faire le fichier ?

300 Mo. Meta écrit « File size: 300MB maximum » pour les reels, et le chiffre est propre aux reels : une vidéo de story est plafonnée à « 100MB maximum » et une image à « 8 MB maximum » sur la même page.

Si votre fichier source est gros ou votre connexion peu fiable, Meta propose une seconde voie d'envoi plutôt qu'un plafond plus haut. Régler upload_type=resumable sur l'appel de conteneur renvoie à la fois un id et une uri, et vous poussez ensuite les octets vers rupload.facebook.com avec les en-têtes offset et file_size :

curl -X POST "https://rupload.facebook.com/ig-api-upload/v25.0/<IG_CONTAINER_ID>" \
     -H "Authorization: OAuth <ACCESS_TOKEN>" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Meta décrit la session reprenable comme destinée aux « large videos from an area with frequent network interruptions or other transmission failures », et la réserve aux apps qui ont implémenté Facebook Login for Business. Le plafond de 300 Mo s'applique toujours.

Quels conteneur et codecs fonctionnent ?

MOV ou MP4 uniquement, avec de la vidéo H264 ou HEVC et de l'audio AAC. Deux clauses de la règle de conteneur de Meta causent plus d'échecs que les noms de codecs.

La première est « moov atom at the front of the file. » L'atome moov contient l'index qui dit au lecteur où se trouve tout le reste. Les encodeurs l'écrivent à la fin par défaut, parce que les tailles ne sont connues qu'une fois l'encodage terminé. Le déplacer en tête, c'est ce que FFmpeg appelle -movflags +faststart, et sans cela Meta doit lire le fichier entier avant de pouvoir commencer, ce qui est une source courante de l'erreur de délai de téléchargement plutôt que d'une erreur de format.

La seconde est « no edit lists. » Une edit list est une table de correspondance qui dit quelles parties d'une piste jouer et quand. Les outils de découpe en laissent souvent une derrière eux au lieu de réencoder. Le fichier se lit correctement dans tous les lecteurs de bureau et se fait refuser ici.

Le reste de la règle vidéo, « progressive scan, closed GOP, 4:2:0 chroma subsampling », exclut les images entrelacées et les encodages à GOP ouvert. Un export H264 standard en 4:2:0 satisfait les trois sans que vous ayez rien à faire.

Quelle fréquence d'images et quel rapport d'aspect Meta exige-t-il ?

La fréquence d'images doit se situer entre 23 et 60 FPS. Meta écrit « Frame rate: 23-60 FPS », ce qui exclut la sortie à 15 FPS que produisent par défaut les enregistreurs d'écran et plusieurs outils vidéo par IA, et exclut les 120 FPS d'un téléphone en mode ralenti.

Le rapport d'aspect est là où les propres chiffres de Meta deviennent étranges. La règle Reels est « Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16 to avoid cropping or blank space. » Un rapport de 0.01:1 est une vidéo cent fois plus haute que large. Les Story Video Specifications, juste en dessous, qui décrivent le même pipeline de transcodage, fixent la même borne à « between 0.1:1 and 10:1. » Les deux chiffres diffèrent d'un facteur dix et les deux sont en ligne sur la même page.

Aucune des deux bornes n'est une règle de conception. 9:16 est la règle de conception, et la largeur maximale de 1920 pixels est ce qui plafonne la résolution en pratique. Notre note sur les dimensions de la vidéo verticale explique d'où vient le 1080 par 1920, et l'article sur la taille des images Instagram couvre la plage séparée de 4:5 à 1.91:1 qui gouverne les photos du fil.

Quelle erreur renvoie chaque infraction ?

Meta publie un tableau de sous-codes pour l'API Instagram, et le confronter aux specs des reels expose un trou. Certaines infractions ont une erreur dédiée. Plusieurs n'en ont pas.

La durée n'est pas dans ce tableau. La taille de fichier non plus, ni la fréquence d'images, ni le rapport d'aspect des reels. Meta documente un sous-code de rapport d'aspect, 2207009, mais sa propre solution recommandée décrit des images : « Advise the app user to try again with an image that falls withing a 4:5 to 1.91:1 range. » Aucun équivalent pour les reels n'est listé.

Le renvoi du tableau est cassé lui aussi. Le correctif de Meta pour 2207026 dit « Advise the app user to upload an MOV or MP4 (MPEG-4 Part 14). See Video Specifications », et le lien atterrit sur une ancre #video-specifications de la référence IG User Media. Cette page porte désormais Image Specifications, Reel Specifications, Story Image Specifications et Story Video Specifications. Il n'y a aucune section Video Specifications sur laquelle atterrir.

La conséquence pratique : un reel trop long ou trop lourd remonte le plus souvent en 2207053, l'erreur d'envoi inconnue, dont le remède documenté est « Generate a new container and use it to try again. » C'est un message inutile pour un fichier qui n'allait jamais être accepté, et c'est l'argument pour valider la durée et la taille en local avant même d'appeler POST /<IG_ID>/media.

Comment savoir qu'un reel est passé ?

Sondez le conteneur. La référence de Meta est explicite : « Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful », et vous confirmez en demandant status_code et en attendant FINISHED. L'ensemble des valeurs et la cadence de sondage recommandée par Meta sont dans l'article sur le status_code du conteneur Instagram. Si vous câblez tout le flux plutôt que de déboguer un fichier, le pas-à-pas sur la planification des reels Instagram couvre les appels qui l'entourent.

Questions fréquentes

Quelle est la durée maximale d'un reel par l'API ?

Quinze minutes. Les Reel Specifications de Meta disent « Duration: 15 mins maximum, 3 seconds minimum. »

Quelle est la taille de fichier maximale d'un reel ?

300 Mo. Les vidéos de story sont plafonnées plus bas, à 100 Mo, dans la même référence.

L'API accepte-t-elle le WebM ou l'AVI ?

Non. Meta ne liste que MOV et MP4, et renvoie le sous-code 2207026 avec le message The video format is not supported pour tout le reste.

Un reel peut-il figurer dans un carrousel ?

Non. Les limitations des reels de Meta disent « Reels cannot appear in carousels. »

Quel rapport d'aspect un reel doit-il utiliser ?

9:16. La plage acceptée par Meta est bien plus large, « between 0.01:1 and 10:1 », mais la même phrase recommande 9:16 « to avoid cropping or blank space. »

Un reel a-t-il besoin d'une image de couverture ?

Non. Vous pouvez passer cover_url ou thumb_offset, et Meta règle thumb_offset sur 0 par défaut, la première image. Si les deux sont fournis, Meta utilise cover_url et ignore thumb_offset.

Que se passe-t-il si un reel est coupé à moins de trois secondes ?

Meta le rejette directement. Les Reel Specifications fixent un minimum de 3 secondes, sans aucune tolérance ni remplissage automatique du côté de Meta. Un extrait qui fonctionne partout ailleurs sur internet échoue ici uniquement à cause de sa durée.

Pourquoi un reel trop volumineux renvoie-t-il "unknown upload error" plutôt qu'un message clair ?

La table des sous-codes de Meta ne comporte aucune entrée dédiée aux infractions de durée ou de taille de fichier. Un reel trop long ou trop lourd ressort le plus souvent sous le sous-code 2207053, dont le seul remède documenté consiste à générer un nouveau conteneur et réessayer. Cela ne règle rien pour un fichier qui n'allait de toute façon jamais être accepté, d'où l'intérêt de vérifier la durée et la taille en local avant d'appeler l'API.

Comment la limite de taille d'un reel se compare-t-elle à celle d'une story ou d'une image ?

Un reel peut peser jusqu'à 300 Mo. Une vidéo de story est plafonnée à 100 Mo et une image à 8 Mo, les trois figurant sur la même page de l'IG User Media Reference. La limite des reels correspond au triple de celle des stories.

Pourquoi une vidéo qui se lit sans problème sur un ordinateur est-elle rejetée par l'API ?

Deux détails du conteneur causent la plupart de ces échecs. Une edit list laissée par un logiciel de montage, ou un atome moov écrit à la fin du fichier plutôt qu'au début, se lisent normalement dans n'importe quel lecteur de bureau mais échouent ou expirent face à la référence de Meta. Réexporter avec l'atome moov placé au début, l'option -movflags +faststart de FFmpeg, et sans edit list règle les deux problèmes.