Die Instagram-API-Bildanforderungen, die Meta beim Upload durchsetzt

Was sind die Instagram-API-Bildanforderungen?

Vier Regeln bilden die Instagram-API-Bildanforderungen, und Meta druckt alle vier in einem Block unter „Image Specifications“ in der Referenz zu POST /<IG_ID>/media: JPEG-Format, 8 MB maximale Dateigröße, ein Seitenverhältnis innerhalb einer Spanne von 4:5 bis 1,91:1 und eine Breite zwischen 320 und 1440 Pixeln. Zitiert, wie Meta sie veröffentlicht:

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.

Der Leitfaden zur Inhaltsveröffentlichung wiederholt die Formatregel unter der eigenen Überschrift Limitations in deutlicheren Worten: „JPEG is the only image format supported. Extended JPEG formats such as MPO and JPS are not supported.“

Lesen Sie den Block ein zweites Mal, und eine Trennlinie wird sichtbar. Zwei dieser Regeln weisen die Anfrage zurück. Zwei davon schreiben Ihre Datei stillschweigend um. Format, Dateigröße und Seitenverhältnis sind Prüfungen, und ein Fehlschlag kommt als HTTP 400 mit Code und Subcode zurück. Breite und Farbraum sind Umwandlungen, und Meta sagt es in den Klammern: hochskaliert, herunterskaliert, nach sRGB konvertiert. Nichts verrät Ihnen, dass es passiert ist.

Diese Unterscheidung entscheidet darüber, wie Sie vor dem API-Aufruf validieren. Die erste Gruppe fangen Sie ab, indem Sie den Fehler lesen. Die zweite Gruppe fangen Sie nur ab, indem Sie die Datei selbst vermessen.

Welchen Fehlercode gibt welcher Verstoß zurück?

Jeder Bildfehler, den Meta dokumentiert, kommt als HTTP-Status 400 mit einem JSON-error-Objekt, das code, error_subcode, error_user_title und error_user_msg trägt. Die Referenz der Instagram-Fehlercodes ordnet sie eins zu eins zu.

Der Beispielfehler, den Meta oben auf dieser Referenz abdruckt, ist der zur Dateigröße, und er lohnt sich wortwörtlich, weil die Formulierung vom Spezifikationsblatt abweicht:

{
  "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"
  }
}

Eine Zeile dieser Tabelle trägt einen Fehler in Metas eigener Dokumentation. Die Spalte Recommended Solution für 36001, Subcode 2207005, also die Formatablehnung, lautet „Possible permission error due to missing permission or expired token. Generate a new container and use it to try again.“ Das ist der Lösungstext für Code 24, Subcode 2207006, ein völlig anderer Fehlschlag, in die Formatzeile hineinkopiert. Ein PNG wird nicht zum JPEG, wenn Sie ein Token erneuern. Ignorieren Sie die Lösungsspalte in dieser Zeile und lesen Sie stattdessen die Nutzermeldung.

Liegt das Limit bei 8 MB oder 8 MiB?

Meta veröffentlicht beide Zahlen auf zwei aktiven Seiten. Die Medienreferenz sagt „File size: 8 MB maximum.“ Die Referenz der Fehlercodes sagt im Beispiel, das Bild „should be less than 8 MiB“, und die Spalte Recommended Solution derselben Zeile sagt „Image exceeded maximum file size of 8MiB.“

Das sind nicht dieselben Obergrenzen. 8 MB sind 8.000.000 Bytes. 8 MiB sind 8.388.608 Bytes. Dazwischen liegen 388.608 Bytes, ein Band von etwa einem Drittel Megabyte Breite, in dem das Spezifikationsblatt nein und der Fehlertext ja sagt.

Bauen Sie gegen 8.000.000 Bytes. Von zwei veröffentlichten Limits ist das niedrigere dasjenige, das Sie nicht überraschen kann, und der Spielraum, den Sie aufgeben, ist klein gegen eine Veröffentlichung, die am Container-Schritt scheitert. Wenn Sie beim Upload komprimieren, zielen Sie deutlich darunter: Ein JPEG, das bei 6 MB landet, übersteht auf Metas Seite eine Neukodierung, ohne einer der beiden Zahlen nahezukommen. Dieselbe defensive Gewohnheit gilt für die Obergrenze von 2.200 Zeichen in der Beschreibung und ihre Unterregel zu 20 @-Tags, wo das Feld bei der Container-Erstellung geprüft wird und nicht erst beim Veröffentlichen.

Was passiert, wenn das Bild zu breit oder zu schmal ist?

Nichts, das Sie in der Antwort abfangen können. Meta rechnet die Datei neu und macht weiter.

Die Mindestbreite liegt bei 320 Pixeln, die Maximalbreite bei 1440, und beide Zeilen enden mit demselben Versprechen: Das Bild „will be scaled up to the minimum if necessary“ und „will be scaled down to the maximum if necessary“. Für keine der beiden Richtungen existiert ein Fehlercode. Ein 4000 Pixel breites Foto wird angenommen, auf 1440 heruntergerechnet und in einer Auflösung veröffentlicht, die Sie nicht gewählt haben. Eine 200 Pixel breite Miniatur wird angenommen, auf 320 gestreckt und unscharf veröffentlicht.

Die Höhe ist nirgends in der Spezifikation eine feste Zahl. Meta schreibt „Height: Varies, depending on width and aspect ratio“, was bedeutet: Die Höhe ist eine Folge der beiden Regeln, die durchgesetzt werden, und keine eigene Regel. Setzen Sie die Breite auf 1440 und das Seitenverhältnis auf 4:5, dann ergibt sich die Höhe zu 1800 Pixeln, dem höchsten Rahmen, den der Feed-Endpunkt annimmt.

Der Farbraum verhält sich genauso. Alles, was nicht sRGB ist, wird konvertiert, ohne Warnung und ohne Fehler. Ein Display-P3-Export aus einem Telefon oder einem Bildbearbeitungsprogramm wird problemlos veröffentlicht und wirkt matter, als es auf Ihrem Bildschirm aussah. Konvertieren Sie vor dem Upload nach sRGB, damit die Konvertierung eine ist, die Sie gesteuert haben. Dasselbe Prinzip steht hinter den Pixelmaßen, die über die Instagram-Oberflächen hinweg halten: Wählen Sie die Größe, die Meta nicht anfasst.

Wie unterscheiden sich die API-Regeln von dem, was die Instagram-App akzeptiert?

Meta gibt der App auf einer anderen Seite einen anderen Satz Zahlen. Instagrams Hilfebereich-Artikel „Image resolution of photos you share on Instagram“ sagt den Leuten, sie sollen „Upload a photo with a width of at least 1080 pixels with an aspect ratio between 1.91:1 and 3:4.“

Stellen Sie beides nebeneinander.

Die hohe Kante ist die, die zubeißt. 4:5 sind 0,8. 3:4 sind 0,75. Ein 3:4-Hochformatzuschnitt, den die App klaglos nimmt, kommt von der API als Code 36003, Subcode 2207009, zurück, weil er außerhalb der dokumentierten Spanne liegt. Wer einen Telefon-Workflow in einen API-Workflow überträgt, läuft zuerst hier auf.

Bei der Breite enden die Regeln an unterschiedlichen Stellen. Beide Dokumente beginnen bei 320, und der Hilfebereich sagt, ein schmaleres Foto werde auf 320 vergrößert. Darüber laufen sie auseinander: Die API rechnet alles über 1440 auf 1440 herunter, die App alles über 1080 auf 1080. Exportieren Sie mit 1080 Pixeln Breite, dann hat keines der beiden Dokumente einen Grund, die Datei anzufassen. AdaptlyPost veröffentlicht über genau diese API auf Instagram, also gilt dieselbe Obergrenze für alles, was geplant statt von Hand gepostet wird.

Zwei weitere App-Funktionen fehlen der API absichtlich. Der Leitfaden zur Inhaltsveröffentlichung stellt klar: „Shopping tags are not supported“ und „Filters are not supported.“ Keine der beiden liefert einen hilfreichen Fehler, weil keiner der Parameter existiert.

Welche Regeln ändern sich für Stories, Reels-Cover und Karussells?

Die 8-MB-Grenze und die JPEG-Regel gelten überall. Die Regel zum Seitenverhältnis nicht.

Stories lassen die erzwungene Spanne ganz fallen. Meta schreibt nur, es sei „recommended 9:16 to avoid cropping or blank space“, was bedeutet: Ein quadratisches Bild erscheint als Story mit Balken statt als Fehler.

Reels-Cover werden zweimal zugeschnitten. Meta sagt, wenn das Cover nicht 9:16 ist, „we crop the image and use the middle most 9:16 rectangle as the cover photo for the reel“, und dass das Teilen des Reels in den Feed einen zweiten Zuschnitt auslöst, „the middle most 1:1 square“. Alles Wichtige nahe am Rand ist verschwunden, bis es im Raster ankommt.

Karussells ignorieren das Seitenverhältnis jeder Folie außer der ersten. Der Leitfaden ist eindeutig: „Carousel images are all cropped based on the first image in the carousel, with the default being a 1:1 aspect ratio.“ Ordnen Sie Ihre Elemente bewusst, denn Folie eins setzt den Rahmen für alle zehn. Diese Einschränkung steht neben der Container-Zählung und der Veröffentlichungsquote, die ein Karussell regieren, wo ein Karussell mit zehn Bildern trotzdem nur eine Veröffentlichung kostet. Und wenn Sie im selben Aufruf einen Alternativtext setzen, hat das Feld alt_text seine eigene, separate Obergrenze, die mit dem Bild selbst nichts zu tun hat.

Häufig gestellte Fragen

Akzeptiert die Instagram API PNG-Bilder?

Nein. Meta schreibt im Leitfaden zur Inhaltsveröffentlichung „JPEG is the only image format supported“. Ein PNG liefert Code 36001, Subcode 2207005, mit der Meldung „The image format {current-image-format} is not supported. Supported formats are: {format}.“

Wie groß darf eine Bilddatei in der Instagram API maximal sein?

Meta veröffentlicht zwei Werte. Die Medienreferenz sagt „File size: 8 MB maximum.“ Die Referenz der Fehlercodes sagt, das Bild „should be less than 8 MiB“, also 8.388.608 Bytes. Bauen Sie gegen die kleinere Zahl, 8.000.000 Bytes.

Welche Seitenverhältnisse lehnt die Instagram API ab?

Alles außerhalb der Spanne von 4:5 bis 1,91:1. Damit fallen 3:4, 9:16 und 2:1 bei Feed-Bildern durch, und es kommt Code 36003, Subcode 2207009, zurück.

Scheitert ein 4000 Pixel breites Bild an der Instagram API?

Nein. Meta skaliert es auf das Maximum von 1440 Pixeln herunter und veröffentlicht es. Für eine Breite außerhalb der Spanne existiert in keiner Richtung ein Fehlercode.

Werden MPO- und JPS-Dateien als JPEG akzeptiert?

Nein. Der Leitfaden zur Inhaltsveröffentlichung benennt sie direkt: „Extended JPEG formats such as MPO and JPS are not supported.“

Gilt für Story- und Karussellbilder dieselbe Regel zum Seitenverhältnis wie für Feed-Beiträge?

Nein. Für Stories ist keine erzwungene Spanne veröffentlicht, nur eine Empfehlung von 9:16. Karussellfolien werden auf das erste Bild im Karussell zugeschnitten, mit 1:1 als Standard.

Welche Höhe erreicht ein Bild über die Instagram API?

Meta legt in der Spezifikation keine feste Höhe fest, dort steht nur "Height: Varies, depending on width and aspect ratio." Die Höhe ergibt sich aus den beiden Regeln, die tatsächlich durchgesetzt werden, Breite und Seitenverhältnis, statt selbst eine eigene Regel zu sein. Wird die Breite auf das Maximum von 1440 Pixeln und das Seitenverhältnis auf 4:5 gesetzt, veröffentlicht das Bild mit 1800 Pixeln Höhe, dem höchsten Format, das der Feed-Endpunkt akzeptiert.

Kann man sich auf die Spalte Recommended Solution in Metas Fehlercode-Referenz verlassen?

Nicht bei jeder Zeile. Der Text zu Code 36001, der Formatablehnung, beschreibt eigentlich Code 24, einen Berechtigungsfehler, und rät dazu, einen neuen Container zu erstellen und es erneut zu versuchen. Ein PNG wird nicht zu einem JPEG, nur weil ein Token erneuert wird, deshalb zählt bei dieser Zeile das Feld error_user_msg und nicht die Lösungsspalte.

Wird ein Reels-Coverfoto mehr als einmal zugeschnitten?

Es kann zweimal zugeschnitten werden. Meta schneidet ein Cover, das nicht 9:16 ist, zunächst auf das mittlere 9:16-Rechteck zu und schneidet es ein zweites Mal auf das mittlere 1:1-Quadrat zu, wenn das Reel zusätzlich im Feed geteilt wird. Was nah am Rand des ursprünglichen Bildes liegt, ist verschwunden, bevor es im Raster ankommt.

Setzt die Instagram-App ein Dateigrößenlimit wie die API durch?

Der Help-Center-Artikel zur Bildauflösung nennt gar keine Dateigröße. Nur die Graph API dokumentiert eine, 8 MB in der Spezifikation und 8 MiB im Fehlertext, die Dateigrößengrenze ist also eine reine API-Regel ohne veröffentlichtes Gegenstück in der App.