Jedes Limit, das die Instagram Reels API deinem Video setzt

Was nimmt die Instagram Reels API an?

Ein Video, das durch die Instagram Reels API geschoben wird, muss jede Zeile eines veröffentlichten Spezifikationsblocks erfüllen, bevor Meta es transcodiert, und dieser Block steht an einer Stelle: Reel Specifications, in der Referenz zu IG User Media. Verfehl eine davon, und der mit media_type=REELS erstellte Container kommt mit status_code auf ERROR statt auf FINISHED zurück.

Hier die ganze Liste, aus Metas Referenz übernommen.

Wie lang darf ein Reel über die API sein?

Fünfzehn Minuten. Metas Zeile lautet „Duration: 15 mins maximum, 3 seconds minimum", was die API-Decke weit höher ansetzt, als die meisten erwarten, und den Boden höher, als die meisten bemerken.

Die drei Sekunden Minimum sind das, was zubeißt. Ein auf zweieinhalb Sekunden getrimmter Clip ist überall sonst im Netz ein völlig gewöhnliches Asset und hier eine sofortige Ablehnung. Es gibt keine Teilpunkte und kein Auffüllen auf Metas Seite.

Die Decke von fünfzehn Minuten verdient einen Zusatz, den Meta nicht anhängt. Diese Zahl regelt, was die API in einen Container hineinlässt. Sie sagt nichts darüber, was die Instagram-App eine Person am Telefon hochladen lässt, und nichts darüber, was das Empfehlungssystem mit einem vierzehnminütigen Reel anstellt, sobald es existiert. Genau so eine Warnung hängt Meta an den Parameter share_to_feed und merkt an, keiner der Werte „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." Dass die API eine Datei annimmt und dass Instagram sie ausspielt, sind zwei verschiedene Fragen.

Wie groß darf die Datei sein?

300 MB. Meta schreibt für Reels „File size: 300MB maximum", und die Zahl gilt speziell für Reels: Ein Story-Video ist auf derselben Seite bei „100MB maximum" gedeckelt und ein Bild bei „8 MB maximum".

Ist deine Quelldatei groß oder deine Verbindung unzuverlässig, bietet Meta einen zweiten Upload-Weg statt einer höheren Decke. upload_type=resumable am Container-Aufruf liefert sowohl eine id als auch eine uri zurück, und die Bytes schiebst du dann mit den Headern offset und file_size an rupload.facebook.com:

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 beschreibt die fortsetzbare Session als gedacht für „large videos from an area with frequent network interruptions or other transmission failures" und beschränkt sie auf Apps, die Facebook Login for Business umgesetzt haben. Die Decke von 300 MB gilt weiterhin.

Welcher Container und welche Codecs funktionieren?

Nur MOV oder MP4, mit H264 oder HEVC als Video und AAC als Audio. Zwei Teilsätze in Metas Container-Regel verursachen mehr Fehlschläge als die Codec-Namen.

Der erste ist „moov atom at the front of the file." Das moov-Atom hält den Index, der einem Player sagt, wo alles andere liegt. Encoder schreiben es standardmäßig ans Ende, weil die Größen erst nach dem Encode feststehen. Es nach vorn zu holen heißt bei FFmpeg -movflags +faststart, und ohne das muss Meta die ganze Datei lesen, bevor es anfangen kann, was eine häufige Quelle des Download-Timeout-Fehlers ist statt eines Formatfehlers.

Der zweite ist „no edit lists." Eine Edit List ist eine Zuordnungstabelle, die sagt, welche Teile einer Spur wann abgespielt werden. Trimm-Werkzeuge lassen häufig eine zurück, statt neu zu encodieren. Die Datei läuft in jedem Desktop-Player korrekt und wird hier abgelehnt.

Der Rest der Videoregel, „progressive scan, closed GOP, 4:2:0 chroma subsampling", schließt interlaced Material und Open-GOP-Encodes aus. Ein normaler H264-Export in 4:2:0 erfüllt alle drei, ohne dass du etwas tust.

Welche Bildrate und welches Seitenverhältnis verlangt Meta?

Die Bildrate muss zwischen 23 und 60 FPS liegen. Meta schreibt „Frame rate: 23-60 FPS", was die 15 FPS ausschließt, die Bildschirmrekorder und etliche KI-Videowerkzeuge standardmäßig ausgeben, und ebenso die 120 FPS, die ein Telefon im Zeitlupenmodus aufnimmt.

Beim Seitenverhältnis werden Metas eigene Zahlen seltsam. Die Reels-Regel lautet „Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16 to avoid cropping or blank space." Ein Verhältnis von 0,01:1 ist ein Video, das hundertmal höher als breit ist. Die Story Video Specifications direkt darunter, die dieselbe Transcoding-Pipeline beschreiben, setzen dieselbe Grenze auf „between 0.1:1 and 10:1." Die beiden Zahlen unterscheiden sich um den Faktor zehn, und beide stehen live auf derselben Seite.

Keine der Grenzen ist eine Gestaltungsregel. 9:16 ist die Gestaltungsregel, und die maximale Breite von 1920 Pixeln ist das, was die Auflösung in der Praxis deckelt. Unser Text zu vertikalen Videomaßen zeigt, woher 1080 mal 1920 kommt, und der Beitrag zur Instagram-Bildgröße behandelt den getrennten Bereich von 4:5 bis 1,91:1, der Feed-Fotos regelt.

Welchen Fehler liefert welcher Verstoß?

Meta veröffentlicht eine Subcode-Tabelle für die Instagram API, und gegen die Reels-Specs gehalten legt sie eine Lücke frei. Einige Verstöße haben einen eigenen Fehler. Mehrere nicht.

Die Dauer steht nicht in dieser Tabelle. Die Dateigröße auch nicht, die Bildrate nicht und das Reels-Seitenverhältnis nicht. Meta dokumentiert einen Subcode fürs Seitenverhältnis, 2207009, aber seine eigene empfohlene Lösung beschreibt Bilder: „Advise the app user to try again with an image that falls withing a 4:5 to 1.91:1 range." Ein Gegenstück für Reels ist nicht aufgeführt.

Auch der Verweis der Tabelle ist kaputt. Metas Fix für 2207026 lautet „Advise the app user to upload an MOV or MP4 (MPEG-4 Part 14). See Video Specifications", und der Link landet auf einem Anker #video-specifications der Referenz zu IG User Media. Diese Seite trägt inzwischen Image Specifications, Reel Specifications, Story Image Specifications und Story Video Specifications. Einen Abschnitt Video Specifications zum Landen gibt es nicht.

Die praktische Folge: Ein zu langes oder zu großes Reel taucht meist als 2207053 auf, der unbekannte Upload-Fehler, dessen dokumentiertes Mittel „Generate a new container and use it to try again" lautet. Das ist eine nutzlose Meldung für eine Datei, die ohnehin nie angenommen worden wäre, und genau das ist das Argument dafür, Dauer und Größe lokal zu prüfen, bevor du überhaupt POST /<IG_ID>/media aufrufst.

Woran erkennst du, dass ein Reel durchgekommen ist?

Frag den Container ab. Metas Referenz ist deutlich: „Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful", und du bestätigst es, indem du status_code abfragst und auf FINISHED wartest. Die vollständige Werteliste und die von Meta empfohlene Abfragefrequenz stehen im Text zum status_code des Instagram-Containers. Wenn du den ganzen Ablauf verdrahtest statt eine einzelne Datei zu debuggen, deckt die Anleitung zum Planen von Instagram Reels die umliegenden Aufrufe ab.

Häufig gestellte Fragen

Wie lang darf ein Reel über die API maximal sein?

Fünfzehn Minuten. Metas Reel Specifications lauten „Duration: 15 mins maximum, 3 seconds minimum."

Wie groß darf die Datei eines Reels maximal sein?

300 MB. Story-Videos sind in derselben Referenz niedriger gedeckelt, bei 100 MB.

Nimmt die API WebM oder AVI an?

Nein. Meta führt nur MOV und MP4 auf und liefert für alles andere den Subcode 2207026 mit der Meldung The video format is not supported.

Kann ein Reel in einem Karussell erscheinen?

Nein. Metas Reels-Einschränkungen halten fest: „Reels cannot appear in carousels."

Welches Seitenverhältnis sollte ein Reel haben?

9:16. Metas eigener akzeptierter Bereich ist viel weiter, „between 0.01:1 and 10:1", aber derselbe Satz empfiehlt 9:16, „to avoid cropping or blank space."

Braucht ein Reel ein Coverbild?

Nein. Du kannst cover_url oder thumb_offset übergeben, und Meta setzt thumb_offset standardmäßig auf 0, das erste Bild. Werden beide geliefert, nimmt Meta cover_url und ignoriert thumb_offset.

Was passiert, wenn ein Reel auf unter drei Sekunden gekürzt wird?

Meta lehnt es direkt ab. Die Reel Specifications legen ein Minimum von 3 Sekunden fest, und es gibt dafür keine Kulanz oder automatisches Auffüllen seitens Meta. Ein Clip, der überall sonst im Netz problemlos funktioniert, scheitert hier allein an der Länge.

Warum liefert ein zu großes Reel den Fehler "unknown upload error" statt einer klaren Meldung?

Metas Subcode-Tabelle enthält keinen eigenen Eintrag für Verstöße gegen Dauer oder Dateigröße. Ein zu langes oder zu großes Reel taucht meist als Subcode 2207053 auf, dessen einzige dokumentierte Lösung lautet, einen neuen Container zu erzeugen und es erneut zu versuchen. Das hilft bei einer Datei, die ohnehin nie akzeptiert worden wäre, nicht weiter, weshalb sich eine lokale Prüfung von Dauer und Größe vor dem API-Aufruf lohnt.

Wie unterscheidet sich die Dateigrößengrenze eines Reels von der einer Story oder eines Bildes?

Ein Reel darf bis zu 300 MB groß sein. Ein Story-Video ist auf 100 MB begrenzt und ein Bild auf 8 MB, beide auf derselben Seite der IG User Media Reference. Die Grenze für Reels liegt damit beim Dreifachen des Story-Limits.

Warum wird ein Video, das auf dem Computer einwandfrei läuft, von der API abgelehnt?

Zwei Container-Details verursachen die meisten dieser Fehler. Eine von Schnittprogrammen zurückgelassene Edit List oder ein moov-Atom am Ende statt am Anfang der Datei laufen in gewöhnlichen Desktop-Playern problemlos, scheitern aber an Metas Referenz oder führen zu einem Timeout. Ein erneuter Export mit dem moov-Atom am Anfang, FFmpegs -movflags +faststart, und ohne Edit List behebt beide Probleme.