Die Session für den Instagram Resumable Upload und der rupload-Host

Was ist ein Instagram Resumable Upload?

Meta nennt es einen Instagram Resumable Upload, und es ist ein Ablauf über zwei Hosts: POST /<IG_ID>/media mit upload_type=resumable legt den Container auf graph.facebook.com an und liefert ein Upload-Ziel zurück, dann gehen die Bytes in einer zweiten Anfrage, die du steuerst, an rupload.facebook.com.

Der Standard ist die umgekehrte Anordnung. Bei einem gewöhnlichen Upload übergibst du video_url, und Meta holt die Datei bei dir ab: „We will cURL your image using the passed in URL so it must be on a public server.“ Dein Server beantwortet eine Anfrage von Metas Crawler, und die Übertragung gelingt oder scheitert an einer Stelle, die du nicht sehen kannst. Resumable dreht das um. Du öffnest die Verbindung, du sendest die Bytes, und du bekommst eine Antwort darüber.

Metas erklärter Grund für den Ablauf steht in der Endpunktliste des Leitfadens zur Inhaltsveröffentlichung, Tippfehler inklusive: „upload_type=resumable Create a resumbable upload session to upload large videos from an area with frequent network interruptions or other transmission failures.“

Der Parameter selbst ist in der Medienreferenz als optional und als schreibungsabhängig dokumentiert: „An optional parameter for users want to upload video through the rupload protocol, values can be set to lowercase string value: resumable.“ Kleinschreibung zählt. RESUMABLE ist kein dokumentierter Wert.

Was sendet jeder Schritt des Ablaufs?

Vier Schritte, zwei Hosts und ein anderes Autorisierungsschema in jedem einzelnen.

Schritt eins unterscheidet sich von einer gewöhnlichen Container-Erstellung durch das, was er weglässt. Es gibt kein video_url, weil es für Meta noch nichts abzuholen gibt. Eine Reel-Session in voller Form:

POST https://graph.facebook.com/v25.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
  ?media_type=REELS
  &upload_type=resumable
  &caption=<IMAGE_CAPTION>
  &collaborators=<COLLABORATOR_USERNAMES>
  &cover_url=<COVER_URL>
  &audio_name=<AUDIO_NAME>
  &location_id=<LOCATION_PAGE_ID>
  &thumb_offset=<THUMB_OFFSET>
  &access_token=<USER_ACCESS_TOKEN>

Die Antwort trägt ein zweites Feld, das ein gewöhnlicher Container nicht zurückgibt:

{
  "id": "<IG_CONTAINER_ID>",
  "uri": "https://rupload.facebook.com/ig-api-upload/v25.0/<IG_CONTAINER_ID>"
}

Nutze die uri, die Meta dir gibt, statt den Pfad selbst zusammenzusetzen. Schritt zwei schickt die Datei dann dorthin:

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

Meta dokumentiert die beiden numerischen Header mit je einer Zeile. „offset is set to the first byte being upload, generally 0.“ „file_size is set to the size of your file in bytes.“ Eine bereits gehostete Datei überspringt den Body vollständig und verschiebt die Quelle stattdessen in einen dritten Header:

curl -X POST "https://rupload.facebook.com/ig-api-upload/v25.0/<IG_CONTAINER_ID>" \
  -H "Authorization: OAuth <USER_ACCESS_TOKEN>" \
  -H "file_url: <VIDEO_URL>"

Erfolg sind zwei Felder: {"success":true,"message":"Upload successful."}.

Warum ist der Authorization-Header auf rupload anders?

Weil Meta ihn für jeden Host anders schreibt, und die Beispiele stehen auf derselben Seite nebeneinander. Aufrufe an graph.facebook.com im Leitfaden zur Inhaltsveröffentlichung nutzen -H "Authorization: Bearer <ACCESS_TOKEN>". Jeder Aufruf an rupload.facebook.com auf derselben Seite nutzt -H "Authorization: OAuth <ACCESS_TOKEN>".

Gleiches Token, anderer Schemaname. Meta gibt keine Erklärung, und die rupload-Beispiele zeigen nie Bearer. Übernimm das Schema aus dem Beispiel, das zu dem Host passt, den du aufrufst.

Zwei weitere Details gehen in den Codeblöcken leicht verloren. Metas veröffentlichtes curl für den rupload-Schritt enthält ein verirrtes Backtick in der URL, zwischen dem Platzhalter für die Container-ID und dem schließenden Anführungszeichen. Das ist ein Tippfehler im Dokument, kein Stück Syntax. Und die Parameterliste des Leitfadens für den Upload-Schritt bricht mitten im Satz ab: Sie kündigt „the following parameters“ an, druckt access_token und endet dann auf einem leeren Aufzählungspunkt. Die vollständige Headerliste existiert nur in der Referenz des Medien-Endpunkts, nicht im Leitfaden.

Wann ist Resumable Pflicht statt Option?

Meta veröffentlicht nie eine Dateigröße, ab der es verpflichtend wird, und die ehrliche Antwort lautet: Die einzige harte Voraussetzung betrifft deinen Login-Ablauf, nicht deine Datei.

Der Leitfaden zur Inhaltsveröffentlichung beschränkt den gesamten Ablauf in einem Nebensatz: upload_type=resumable ist „Only for apps that have implemented Facebook Login for Business.“ Die Anforderungstabelle auf derselben Seite bestätigt das, indem sie Host-URLs je Login-Typ auflistet. Instagram API mit Instagram Login bekommt graph.instagram.com. Instagram API mit Facebook Login bekommt graph.facebook.com und rupload.facebook.com, mit dem Zusatz „(For resumable video uploads)“.

Eine App auf Basis von Business Login for Instagram kann Resumable also gar nicht nutzen. Video muss über video_url und Metas Abholung ankommen. Das ist eine Architekturentscheidung beim Login, die lange vor dem ersten Dateiupload fällt, und sie lässt sich nicht pro Anfrage umdrehen.

Wo Resumable verfügbar ist, bleibt Metas Rat qualitativ statt numerisch. Der Auslöser sind „large videos from an area with frequent network interruptions or other transmission failures“, ohne angehängte Byteschwelle. Die einzigen verwandten Zahlen, die Meta veröffentlicht, sind die Obergrenzen der Spezifikation: Reels enden bei 300 MB und 15 Minuten, Stories bei 100 MB und 60 Sekunden. Keine davon wird als Schwelle für Resumable beschrieben.

Praktisch gelesen: Nutze Resumable immer dann, wenn deine Quelldatei lokal liegt statt schon auf einem CDN, denn die Alternative verlangt, dass du die Datei für die Dauer von Metas Abholung öffentlich hostest. Das zählt am meisten bei allem Langen, und genau dort wird das Hochladen von langem Video auf Instagram unhandlich und dort treiben die Reel-Längen, die Meta testet die Dateigrößen nach oben.

Wie setzt man einen abgebrochenen Upload tatsächlich fort?

Meta dokumentiert es nicht. Das ist die größte Lücke der Funktion, und sie sitzt direkt unter ihrem Namen.

Der Header offset ist der einzige Mechanismus, der auf Teilübertragungen hindeutet, und beide Stellen, an denen Meta ihn beschreibt, zeigen auf denselben Wert: „offset is set to the first byte being upload, generally 0.“ Es gibt keine dokumentierte Chunk-Größe, keinen Endpunkt, der meldet, wie viele Bytes der Server bereits hält, keine zweite Anfrageform für die Fortsetzung einer abgebrochenen Übertragung und nirgends in der Dokumentation der Instagram Platform ein Beispiel, das einen Offset ungleich null übergibt. Eine Upload-Session namens „resumable“ ist, so wie sie veröffentlicht ist, ein einzelner POST der gesamten Datei mit einem Offset-Feld, das in den Beispielen immer null ist.

Was Meta dir gibt, ist ein Container, der einen Fehlschlag lange genug überlebt, um von vorn zu beginnen. Container verfallen nach 24 Stunden, und ein Konto kann in einem rollierenden 24-Stunden-Zeitraum 400 davon anlegen. Eine gescheiterte Byteübertragung kostet einen Container von diesen 400 und nicht eine Veröffentlichung aus deinem Tageskontingent, ein Neustart ist also in dem Budget, auf das es ankommt, günstig. Alles im Voraus Eingeplante muss dieselben Obergrenzen einhalten, weshalb geplante Instagram-Beiträge häufiger in der Container-Phase scheitern als beim Veröffentlichen.

Wie sieht ein gescheiterter Upload aus?

Ein Fehlschlag auf dem rupload-Host kommt nicht als gewöhnliches Graph-API-Fehlerobjekt zurück. Er kommt als debug_info-Umschlag, in dem der eigentliche Fehler als String steckt:

{
  "debug_info": {
    "retriable": false,
    "type": "ProcessingFailedError",
    "message": "{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

Lies zuerst retriable. Das ist das Feld, das dir sagt, ob ein erneuter Versuch den Container wert ist. false bedeutet, dass die Übertragung genauso wieder scheitern wird, und das Beispiel, das Meta gewählt hat, eine nicht autorisierte Nutzeranfrage, ist genau so ein Fehlschlag.

Fehler, die später auf der Graph-API-Seite auftauchen, nutzen die üblichen Paare aus Code und Subcode.

Meta grenzt 2207053 ausdrücklich auf diesen Ablauf ein: „An unknown error occured during upload. Generate a new container and use it to try again. This should only affect video uploads.“

Welche Fehler tauchen auf, nachdem der Upload gelungen ist?

Die aus der Verarbeitung, und du siehst sie nur durch Abfragen. Meta ist eindeutig, dass eine Container-ID nichts beweist: „Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful.“

GET /<IG_CONTAINER_ID>?fields=status_code gibt einen von fünf Werten zurück.

Nur FINISHED ist sicher zum Veröffentlichen. Das Feld status neben status_code abzufragen, ist den zusätzlichen Parameter wert, denn Meta definiert es als die Detailzeile: „If status_code is ERROR, this value will be an error subcode.“

Meta deckelt den Rat zum Abfragen auf eine feste Taktung: „We recommend querying a container's status once per minute, for no more than 5 minutes.“ Ein langes Reel kann danach immer noch in Verarbeitung sein, und Meta sagt nicht, was dann zu tun ist. Das brauchbare Muster ist, in größeren Abständen weiter abzufragen, bis der Container entweder fertig ist oder die 24-Stunden-Grenze erreicht, und genau so muss auch die Planung von Reels über die API gebaut werden und so verhalten sich Story-Container an ihrer eigenen 24-Stunden-Uhr.

Häufig gestellte Fragen

Was bewirkt upload_type=resumable in der Instagram API?

Es legt einen Container an, der erwartet, dass du das Video selbst zu rupload.facebook.com schiebst, statt dass Meta es von einer video_url abholt, die du hostest. Die Antwort enthält sowohl eine id als auch eine uri, die auf den Upload-Host zeigt.

Welcher Host wickelt Instagram Resumable Uploads ab?

rupload.facebook.com, unter dem Pfad /ig-api-upload/<API_VERSION>/<IG_CONTAINER_ID>. Container-Erstellung, Statusprüfungen und Veröffentlichung bleiben alle auf graph.facebook.com.

Welche Header braucht die rupload-Anfrage?

Authorization: OAuth <ACCESS_TOKEN> plus entweder offset und file_size für eine lokale Datei oder file_url für eine bereits öffentlich gehostete Datei. Beachte, dass die rupload-Beispiele OAuth nutzen, wo die Graph-API-Beispiele Bearer nutzen.

Können Apps mit Instagram Login Resumable Uploads nutzen?

Nein. Meta beschränkt upload_type=resumable auf Apps, die Facebook Login for Business umgesetzt haben, und führt rupload.facebook.com nur unter diesem Login-Typ auf.

Ab welcher Dateigröße verlangt Instagram einen Resumable Upload?

Meta veröffentlicht keine solche Schwelle. Der Leitfaden empfiehlt Resumable für „large videos from an area with frequent network interruptions“, ohne eine Größe zu nennen, und dokumentiert den Parameter selbst als optional.

Wie setzt man einen abgebrochenen Instagram-Upload fort?

Meta dokumentiert kein Verfahren dafür. Der Header offset existiert, aber jedes veröffentlichte Beispiel setzt ihn auf 0, und kein Endpunkt meldet, wie viele Bytes der Server schon erhalten hat. Erzeuge einen neuen Container und fang von vorn an.

Wie lange bleibt ein Instagram-Upload-Container gültig?

Ein Container läuft 24 Stunden nach der Erstellung ab, unabhängig davon, ob er veröffentlicht wurde. Verpasst man dieses Fenster, liefert Meta Code -2, Subcode 2207020, mit der Meldung, dass das Medium abgelaufen ist und man den Upload erneut versuchen muss. Das Feld status_code meldet aus demselben Grund EXPIRED.

Wie oft sollte man den Status eines Instagram-Containers abfragen?

Meta begrenzt die eigene Empfehlung auf einmal pro Minute, höchstens 5 Minuten lang. Ein langer Reel kann nach diesem Fenster immer noch IN_PROGRESS zeigen, und Meta dokumentiert nicht, was danach zu tun ist. In der Praxis fragt man in größeren Abständen weiter ab, bis der Container entweder FINISHED erreicht oder nach 24 Stunden abläuft.

Was bedeutet das Feld retriable bei einem rupload-Fehler?

Es ist das erste Feld, das man im debug_info-Umschlag prüft, den rupload bei einem Fehler zurückgibt. Der Wert false bedeutet, dass die Anfrage beim erneuten Senden auf dieselbe Weise scheitert, wie in Metas eigenem Beispiel einer nicht autorisierten Anfrage. Wer retriable vor einem erneuten Versuch prüft, verschwendet keinen Container auf eine Anfrage, die ohnehin nicht gelingen kann.

Bedeutet eine Container-ID, dass der Instagram-Upload erfolgreich war?

Eine Container-ID allein beweist nichts. Meta erklärt ausdrücklich, dass Video-Uploads asynchron sind, sodass der Erhalt einer Container-ID keinen erfolgreichen Upload garantiert. Der einzige Weg, es zu wissen, ist die Abfrage des Containers über GET /<IG_CONTAINER_ID>?fields=status_code, bis der Status FINISHED lautet, bevor man veröffentlicht.