Meta impose ses exigences d'images de l'API Instagram dès l'envoi

Quelles sont les exigences d'images de l'API Instagram ?

Quatre règles composent les exigences d'images de l'API Instagram, et Meta les imprime toutes les quatre dans un même bloc sous « Image Specifications » sur la référence POST /<IG_ID>/media : format JPEG, taille de fichier de 8 MB maximum, un ratio compris entre 4:5 et 1.91:1, et une largeur entre 320 et 1440 pixels. Citées telles que Meta les publie :

Format: JPEG

File size: 8 MB maximum.

Aspect ratio: Must be within a 4:5 to 1.91:1 range

Minimum width: 320 (will be scaled up to the minimum if necessary)

Maximum width: 1440 (will be scaled down to the maximum if necessary)

Height: Varies, depending on width and aspect ratio

Color Space: sRGB. Images using other color spaces will have their color spaces converted to sRGB.

Le guide Content Publishing répète la règle de format en des termes plus abrupts sous son propre titre Limitations : « JPEG is the only image format supported. Extended JPEG formats such as MPO and JPS are not supported. »

Relisez le bloc et une séparation apparaît. Deux de ces règles rejettent la requête. Deux autres réécrivent discrètement votre fichier. Le format, la taille de fichier et le ratio sont des contrôles, et un échec revient sous forme de HTTP 400 avec un code et un sous-code. La largeur et l'espace colorimétrique sont des conversions, et Meta le dit entre parenthèses : agrandie, réduite, convertie en sRGB. Rien ne vous signale que c'est arrivé.

Cette distinction décide de la façon dont vous validez avant d'appeler l'API. Vous attrapez le premier groupe en lisant l'erreur. Vous n'attrapez le second qu'en mesurant le fichier vous-même.

Quel code d'erreur renvoie chaque violation ?

Chaque échec d'image documenté par Meta arrive avec le statut HTTP 400 et un objet JSON error portant code, error_subcode, error_user_title et error_user_msg. La référence des codes d'erreur Instagram les associe un à un.

L'exemple d'erreur que Meta imprime en haut de cette référence est celui de la taille de fichier, et il vaut la peine d'être recopié mot pour mot parce que la formulation diffère de la fiche de spécification :

{
  "error": {
    "message": "The image size is too large.",
    "type": "OAuthException",
    "code": 36000,
    "error_subcode": 2207004,
    "is_transient": false,
    "error_user_title": "Image size too large",
    "error_user_msg": "The image is too large to download. It should be less than 8 MiB.",
    "fbtrace_id": "A6LJylpZRKw2xKLFsAP-cJh"
  }
}

Une ligne de ce tableau porte une erreur dans la documentation de Meta elle-même. La colonne Recommended Solution pour 36001 sous-code 2207005, le rejet de format, indique « Possible permission error due to missing permission or expired token. Generate a new container and use it to try again. » C'est le texte de solution du code 24 sous-code 2207006, un échec complètement différent, collé dans la ligne du format. Un PNG ne devient pas un JPEG quand vous rafraîchissez un token. Ignorez la colonne solution sur cette ligne et lisez le message utilisateur à la place.

La limite est-elle de 8 MB ou de 8 MiB ?

Meta publie les deux chiffres sur deux pages en ligne. La référence média dit « File size: 8 MB maximum. » La référence des codes d'erreur dit que l'image « should be less than 8 MiB » dans la réponse d'exemple, et la colonne Recommended Solution de la même ligne dit « Image exceeded maximum file size of 8MiB. »

Ce ne sont pas le même plafond. 8 MB font 8 000 000 octets. 8 MiB font 8 388 608 octets. L'écart entre les deux est de 388 608 octets, soit une bande large d'environ un tiers de mégaoctet où la fiche de spécification dit non et le texte d'erreur dit oui.

Développez contre 8 000 000 octets. La plus basse de deux limites publiées est celle qui ne peut pas vous surprendre, et la marge abandonnée est minime à côté d'une publication qui échoue à l'étape du conteneur. Si vous compressez à l'entrée, visez nettement en dessous : un JPEG qui atterrit à 6 MB survit à un réencodage côté Meta sans approcher ni l'un ni l'autre des deux chiffres. Le même réflexe défensif s'applique à la limite de 2 200 caractères de légende et sa sous-règle des 20 tags @, où le champ est vérifié à la création du conteneur plutôt qu'à la publication.

Que se passe-t-il quand l'image est trop large ou trop étroite ?

Rien que vous puissiez attraper dans la réponse. Meta rééchantillonne le fichier et continue.

La largeur minimale est de 320 pixels et la maximale de 1440, et les deux lignes se terminent par la même promesse : l'image « will be scaled up to the minimum if necessary » et « will be scaled down to the maximum if necessary. » Aucun code d'erreur n'existe dans un sens comme dans l'autre. Une photographie large de 4000 pixels est acceptée, rééchantillonnée à 1440 et publiée à une résolution que vous n'avez pas choisie. Une vignette de 200 pixels est acceptée, étirée à 320 et publiée floue.

La hauteur n'est un chiffre fixe nulle part dans la spécification. Meta écrit « Height: Varies, depending on width and aspect ratio », ce qui veut dire que la hauteur est une conséquence des deux règles réellement appliquées plutôt qu'une règle à part entière. Fixez la largeur à 1440 et le ratio à 4:5, et la hauteur suit à 1800 pixels, le cadre le plus haut que l'endpoint du fil accepte.

L'espace colorimétrique se comporte de la même façon. Tout ce qui n'est pas sRGB est converti, sans avertissement et sans erreur. Un export Display P3 sorti d'un téléphone ou d'un éditeur photo se publie sans encombre et se publie plus terne qu'il ne l'était à l'écran. Convertissez en sRGB avant l'envoi pour que la conversion soit celle que vous avez maîtrisée. Le même principe guide les dimensions en pixels qui tiennent sur toutes les surfaces Instagram : choisissez la taille à laquelle Meta ne touchera pas.

En quoi les règles de l'API diffèrent-elles de ce qu'accepte l'application Instagram ?

Meta donne à l'application un autre jeu de chiffres sur une autre page. L'article du centre d'aide Instagram « Image resolution of photos you share on Instagram » dit aux gens d'« Upload a photo with a width of at least 1080 pixels with an aspect ratio between 1.91:1 and 3:4. »

Mettez les deux côte à côte.

C'est le bord vertical qui mord. 4:5 vaut 0,8. 3:4 vaut 0,75. Un recadrage portrait en 3:4 que l'application accepte sans broncher revient de l'API en code 36003, sous-code 2207009, parce qu'il tombe hors de la plage documentée. Quiconque porte un workflow mobile vers un workflow API bute là-dessus en premier.

Les règles de largeur s'arrêtent à des endroits différents. Les deux documents partent de 320, et le centre d'aide précise qu'une photo plus étroite est agrandie à 320. Au-dessus, elles divergent : l'API ramène à 1440 tout ce qui dépasse 1440, tandis que l'application ramène à 1080 tout ce qui dépasse 1080. Exportez en 1080 pixels de large et aucun des deux documents n'a de raison de toucher au fichier. AdaptlyPost publie sur Instagram via cette API, donc le même plafond s'applique à tout ce qui est planifié plutôt que posté à la main.

Deux autres fonctions de l'application sont absentes de l'API par conception. Le guide Content Publishing énonce clairement que « Shopping tags are not supported » et « Filters are not supported. » Ni l'une ni l'autre ne renvoie d'erreur utile, parce que ni l'un ni l'autre paramètre n'existe.

Quelles règles changent pour les Stories, les couvertures de Reels et les carrousels ?

Le plafond de 8 MB et la règle du JPEG tiennent partout. La règle de ratio, non.

Les Stories abandonnent entièrement la plage imposée. Meta écrit seulement qu'il est « recommended 9:16 to avoid cropping or blank space », ce qui veut dire qu'une image carrée se publie en Story avec des bandes plutôt qu'avec une erreur.

Les couvertures de Reels sont recadrées deux fois. Meta dit que si la couverture n'est pas en 9:16, « we crop the image and use the middle most 9:16 rectangle as the cover photo for the reel », et que partager le Reel dans le fil déclenche un second recadrage, « the middle most 1:1 square. » Tout ce qui est important près d'un bord a disparu au moment où il atteint la grille.

Les carrousels ignorent le ratio de toutes les diapositives sauf la première. Le guide est explicite : « Carousel images are all cropped based on the first image in the carousel, with the default being a 1:1 aspect ratio. » Ordonnez vos enfants délibérément, parce que la diapositive un fixe le cadre des dix. Cette contrainte voisine avec le nombre de conteneurs et le quota de publication qui gouvernent un carrousel, où un carrousel de dix images ne dépense qu'une seule publication. Et si vous renseignez le texte alternatif dans la même requête, le champ alt_text porte son propre plafond distinct, qui n'a rien à voir avec l'image elle-même.

Questions fréquentes

L'API Instagram accepte-t-elle les images PNG ?

Non. Meta écrit « JPEG is the only image format supported » dans le guide Content Publishing. Un PNG renvoie le code 36001, sous-code 2207005, avec le message « The image format {current-image-format} is not supported. Supported formats are: {format}. »

Quelle est la taille de fichier maximale d'une image sur l'API Instagram ?

Meta publie deux chiffres. La référence média dit « File size: 8 MB maximum. » La référence des codes d'erreur dit que l'image « should be less than 8 MiB », soit 8 388 608 octets. Développez contre le plus petit des deux, 8 000 000 octets.

Quels ratios l'API Instagram rejette-t-elle ?

Tout ce qui sort de la plage 4:5 à 1.91:1. Cela rejette le 3:4, le 9:16 et le 2:1 sur les images de fil, et renvoie le code 36003, sous-code 2207009.

Une image large de 4000 pixels échoue-t-elle sur l'API Instagram ?

Non. Meta la réduit au maximum de 1440 pixels et la publie. Aucun code d'erreur n'existe pour une largeur hors plage, dans un sens comme dans l'autre.

Les fichiers MPO et JPS sont-ils acceptés comme des JPEG ?

Non. Le guide Content Publishing les nomme directement : « Extended JPEG formats such as MPO and JPS are not supported. »

Les images de Story et de carrousel suivent-elles la même règle de ratio que les posts de fil ?

Non. Les Stories n'ont aucune plage imposée publiée, seulement une recommandation en 9:16. Les diapositives de carrousel sont recadrées pour correspondre à la première image du carrousel, avec le 1:1 par défaut.

À quelle hauteur une image est-elle publiée via l'API Instagram ?

Meta ne fixe aucune hauteur dans la spécification, le texte dit seulement "Height: Varies, depending on width and aspect ratio". La hauteur découle des deux règles réellement appliquées, la largeur et le ratio, plutôt que d'être une règle à part. Si la largeur atteint le maximum de 1440 pixels et le ratio 4:5, l'image se publie à 1800 pixels de haut, le cadre le plus haut que le endpoint du fil accepte.

Peut-on se fier à la colonne Recommended Solution de la référence des codes d'erreur de Meta ?

Pas sur toutes les lignes. Le texte à côté du code 36001, le rejet de format, décrit en réalité le code 24, une erreur de permission, et conseille de générer un nouveau conteneur et de réessayer. Un PNG ne devient pas un JPEG parce qu'on renouvelle un jeton, mieux vaut donc lire le champ error_user_msg plutôt que la colonne solution sur cette ligne.

Une photo de couverture de reel est-elle recadrée plus d'une fois ?

Elle peut être recadrée deux fois. Meta recadre d'abord toute couverture qui n'est pas en 9:16 sur le rectangle 9:16 le plus central, puis la recadre une seconde fois sur le carré 1:1 le plus central si le reel est aussi partagé dans le fil. Ce qui se trouve près du bord de l'image d'origine disparaît avant d'atteindre la grille.

L'application Instagram impose-t-elle une limite de taille de fichier comme l'API ?

L'article du Centre d'aide sur la résolution des photos ne publie aucun chiffre de taille de fichier. Seule la Graph API en documente un, 8 MB dans la spécification et 8 MiB dans le texte d'erreur, la limite de taille de fichier est donc une règle propre à l'API, sans équivalent publié côté application.