Der X API INIT APPEND FINALIZE Media-Upload, Schritt für Schritt

Was ist der X API INIT APPEND FINALIZE Media-Upload?

Vier Aufrufe bilden den X API INIT APPEND FINALIZE Media-Upload: drei POSTs, die die Datei bewegen, und ein GET, der berichtet, was X danach damit gemacht hat. X listet sie in dieser Reihenfolge im Leitfaden zum Chunked Upload.

1. INIT, POST /2/media/upload/initialize, was X beschreibt als „start the session and get a media_id“
2. APPEND, POST /2/media/upload/{id}/append, „upload each chunk“
3. FINALIZE, POST /2/media/upload/{id}/finalize, „complete the upload“
4. STATUS, GET /2/media/upload, „wait for processing when processing_info is returned“

Die Kommandonamen haben den Wechsel auf v2 überlebt, der Transportweg nicht. X setzt die Warnung direkt unter die Liste: „Do not send command=INIT, command=APPEND, or command=FINALIZE to POST /2/media/upload. Those command-style parameters were the previous upload protocol. The v2 flow uses the dedicated paths above. command=STATUS is still used only on the status GET.“

Eines der vier Kommandos existiert also weiterhin als Query-Parameter und drei nicht. Code, der gegen v1.1 geschrieben wurde, scheitert an den drei POSTs und funktioniert beim Poll weiter, was eine verwirrende Art ist, kaputtzugehen.

Alle vier Aufrufe hängen am selben OAuth-2.0-Scope, media.write, einschließlich des Status-GET. Den Verarbeitungsstand des eigenen Uploads zu lesen braucht einen Schreib-Scope, und X veröffentlicht keine reine Lesealternative.

Was sendet und liefert jeder Schritt?

Jeder Schritt trägt andere Parameter, und nur zwei der vier liefern etwas, das Sie behalten.

INIT nimmt einen JSON-Body entgegen, keine Formularfelder, und X sagt das im Leitfaden: „Send a JSON body, not multipart form fields.“ Das media_type-Enum reicht von video/mp4 und video/quicktime über text/srt und text/vtt bis zu zwei 3D-Formaten, die den meisten nie auffallen, model/gltf-binary und model/vnd.usdz+zip. Das Feld total_bytes hat eine harte Schemagrenze von 17179869184, also 16 GiB.

{
  "data": {
    "id": "1880028106020515840",
    "media_key": "13_1880028106020515840",
    "expires_after_secs": 86400
  }
}

Diese expires_after_secs von 86400 im eigenen Beispiel von X sind die Uhr der Session: ein Tag vom INIT an, um das fertige Medium irgendwo anzuhängen. Die id entspricht dem Muster ^[0-9]{1,19}$, und der media_key stellt ihr eine Typnummer und einen Unterstrich voran, dieselbe Form mit 13_, die die Ads API dokumentiert, wenn sie den Wert eine Video-id nennt.

APPEND ist der einzige Schritt, dessen Antwort Ihnen nichts Nützliches über das Medium sagt. Sein Schema enthält ein einziges Feld, expires_at, beschrieben als „Epoch seconds when the upload session expires.“ Jeder andere Schritt meldet die Restlaufzeit der Session als expires_after_secs, eine relative Zahl. APPEND meldet sie als absoluten Zeitstempel. Dieselbe Angabe, zwei Einheiten, drei Feldschreibweisen über vier Endpunkte.

FINALIZE ist die leerste Anfrage im Ablauf. Sie nimmt die Pfad-id und sonst nichts, keinen Body und keine Query-Parameter, weshalb der ganze curl in zwei Zeilen passt:

curl -X POST "https://api.x.com/2/media/upload/1880028106020515840/finalize" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

Die Antwort darauf ist die Stelle, an der sich der Weg wirklich verzweigt. X fasst die Regel in einen Satz: „If processing_info is returned, proceed to Step 4 to wait for processing. If not, the media is ready to use.“ Ein Bild überspringt Schritt vier meistens. Ein Video nie.

Wie funktioniert segment_index?

segment_index ist ein einfacher Zähler, der Ihnen gehört, beginnt bei null, und das Schema legt beide Enden fest: „minimum: 0, maximum: 999.“

Die Empfehlung von X zur Chunk-Größe steht im Leitfaden statt im Schema: „Keep each segment at or below 5 MB (the server maximum is 8 MB). Segments are indexed from 0.“ Das Python-Beispiel im selben Leitfaden liest die Datei in 4-MB-Blöcken und erhöht den Index nach jedem erfolgreichen Aufruf.

curl -X POST "https://api.x.com/2/media/upload/1880028106020515840/append" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -F "segment_index=0" \
  -F "media=@/path/to/chunk0.mp4"

Der Body darf Multipart-Formulardaten wie oben oder JSON sein, denn das Request-Schema ist für beide Content-Types registriert. In JSON nimmt das Feld media Base64. In Multipart nimmt es rohe Bytes.

Multiplizieren Sie jetzt die beiden veröffentlichten Obergrenzen. Tausend Segmente zum Servermaximum von 8 MB sind 8 GB. Tausend Segmente zu den empfohlenen 5 MB sind 5 GB. Gleichzeitig akzeptiert POST /2/media/upload/initialize total_bytes bis 16 GiB, und X stellt klar fest, dass ein X-Premium- oder verifiziertes Konto ein 16-GB-Video auf einen Post laden darf. Diese beiden Tatsachen lassen sich über APPEND wie dokumentiert nicht gleichzeitig erfüllen, und X veröffentlicht keine größere Segmentgröße, keinen anderen Weg und keinen Hinweis, dass sich die 999er-Grenze bei großen Dateien verschiebt. Alles über 8 GB hat keinen dokumentierten Weg in den Ablauf.

Der Upload muss in keinem veröffentlichten Sinn sequenziell sein. X führt „Failed chunks can be retried individually“ und „Uploads can be paused and resumed“ unter den Vorteilen des Chunkings auf, sagt aber nie, ob ein wiederholtes Segment das frühere überschreibt, ob Indizes in falscher Reihenfolge ankommen dürfen oder was passiert, wenn Sie eine Nummer überspringen. Dieselbe Frage stellt sich bei anderen Netzwerken: Die resumable Upload-Session von Instagram hat einen Offset-Header, den jedes veröffentlichte Beispiel auf null setzt, und LinkedIn beantwortet sie, indem es Ihnen eine Liste von Upload-URLs gibt, eine pro Teil.

Was liefert das STATUS-Kommando zurück?

STATUS liefert ein processing_info-Objekt mit drei Feldern, und das, auf das Sie reagieren, ist state.

Der Leitfaden druckt den Idealweg als Pfeildiagramm: „pending to in_progress to succeeded or failed.“ Zwei dieser vier sind Endzustände. Das eigene Polling-Beispiel von X bricht die Schleife bei succeeded und bei failed ab und schläft bei allem anderen für check_after_secs, was die richtige Form ist, weil der Server das Intervall setzt und nicht Ihre Backoff-Regel. Das FINALIZE-Beispiel liefert "check_after_secs": 1, der erste Poll kommt also schnell.

curl "https://api.x.com/2/media/upload?command=STATUS&media_id=1880028106020515840" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

Zwei Lücken sollten Sie kennen, bevor Sie die Schleife bauen.

Die vier State-Werte stehen in einem Beschreibungstext, nicht in einem Enum. Das Schema typisiert state als einfachen String ohne Liste erlaubter Werte, die vier Namen, die X druckt, sind also Dokumentation und keine geschlossene Menge. Behandeln Sie einen unbekannten State als Aufforderung weiterzupollen, nicht als Fehler.

Die größere Lücke ist, dass processing_info keinen Platz für einen Fehlergrund hat. Sein Schema deklariert genau drei Properties und danach additionalProperties: false, eine Antwort mit "state": "failed" trägt also keinen Code, keine Meldung und keinen Subcode daneben. Das v1.1-Protokoll lieferte innerhalb von processing_info ein Fehlerobjekt mit Name und Meldung. Das v2-Schema hat in seiner veröffentlichten Form kein Feld dafür, womit „failed“ die gesamte Diagnose bleibt.

progress_percent ist in jedem processing_info-Schema der Medienreferenz dokumentiert und taucht in keiner Beispielantwort von X auf, rechnen Sie also damit, dass es fehlt, statt dass es null ist.

Warum scheitert ein fertiger Upload trotzdem an POST /2/tweets?

Weil X die Datei zweimal gegen zwei verschiedene Personen prüft und das auch zweimal sagt. Die Medieneinführung beginnt damit: „Upload and posting are separately enforced. A file that uploads successfully can still be rejected when you attach it to a Post.“

Die erste Prüfung läuft beim INIT und FINALIZE gegen den hochladenden Nutzer. Die zweite läuft gegen den postenden Nutzer, sobald die media_id bei POST /2/tweets ankommt. X benennt den Fehlschlag exakt:

{
  "title": "Forbidden",
  "detail": "This user is not allowed to post a video longer than 20 minutes.",
  "type": "about:blank",
  "status": 403
}

Zwanzig Minuten ist die Standardzahl in diesem String. X merkt an, dass sich die Zahl bewegt: „N is the posting user's duration cap (20 minutes by default, 125 minutes for Premium / verified).“ Das heißt, dieselbe media_id, einmal finalisiert und zu succeeded verarbeitet, hängt sich bei einem Konto an und liefert bei einem anderen 403. Die Berechtigung folgt dem Konto, und die Stufen, die über die Videolänge eines Kontos entscheiden, sind dieselben X-Premium-Stufen, nicht Ihr Developer-Plan.

Die Grenzen für die Zusammenstellung eines Posts greifen im selben Moment. X erlaubt „up to 4 photos, 1 animated GIF, or 1 video“ auf einem Post, und eine media_id, die diese Mischung verletzt, scheitert beim Anhängen, obwohl der Upload selbst sauber war. Der praktische Ablauf für alles Lange ist die komplette Anleitung, wie hochwertiges Video auf X landet, wobei der 403 als normaler Ausgang und nicht als Ausnahme behandelt wird.

Häufig gestellte Fragen

Welche Endpunkte ersetzen command=INIT und command=APPEND in der X API v2?

POST /2/media/upload/initialize und POST /2/media/upload/{id}/append. X hält fest, dass die Parameter im Kommandostil „were the previous upload protocol“ und nicht mehr an POST /2/media/upload gesendet werden dürfen.

Ist command=STATUS in der X API v2 noch gültig?

Ja, und es ist das einzige. X schreibt, dass „command=STATUS is still used only on the status GET“, also GET /2/media/upload?command=STATUS&media_id=. Das Schema markiert den Parameter command als optional, obwohl ihn jedes veröffentlichte Beispiel mitgibt.

Was ist der maximale segment_index am append-Endpunkt der X API?

999. Das Request-Schema von append setzt segment_index auf ein Minimum von 0 und ein Maximum von 999, eine Datei ist also auf 1000 Chunks begrenzt.

Wie groß darf jeder APPEND-Chunk sein?

X empfiehlt 5 MB und nennt 8 MB als Servermaximum. Das eigene Python-Beispiel liest die Datei in 4-MB-Blöcken.

Welche Verarbeitungszustände gibt es beim Media-Upload auf X?

pending, in_progress, succeeded und failed. X druckt den Ablauf als pending zu in_progress zu succeeded oder failed, auch wenn das Schema state als offenen String statt als Enum typisiert.

Warum scheitert eine erfolgreich finalisierte media_id an POST /2/tweets?

Upload und Posten werden getrennt gegen unterschiedliche Berechtigungen durchgesetzt. Wenn der postende Nutzer kein so langes Video anhängen darf, liefert die Post-Anfrage 403 Forbidden mit dem Detail „This user is not allowed to post a video longer than N minutes.“

Wie lange bleibt eine X-Media-Upload-Sitzung gültig, bevor sie abläuft?

Das eigene INIT-Beispiel von X liefert einen expires_after_secs-Wert von 86400, also einen Tag Zeit zwischen INIT und dem Anhängen des fertigen Medienobjekts. FINALIZE meldet die verbleibende Zeit auf die gleiche Art als expires_after_secs. APPEND weicht davon ab und liefert expires_at, einen absoluten Epoch-Zeitstempel statt eines Countdowns, sodass derselbe Sitzungs-Timer in zwei unterschiedlichen Einheiten auftaucht.

Muss man beim Hochladen eines Fotos auf X den STATUS-Endpunkt abfragen?

Meist nicht. Die Regel von X lautet: Liefert FINALIZE keinen processing_info-Block, ist das Medienobjekt einsatzbereit, und ein Bild-Upload kommt meistens ohne einen solchen Block zurück. Ein Video nie, Schritt vier ist also praktisch nur für Videos nötig.

Verwendet der STATUS-Endpunkt einen anderen OAuth-Scope als die Upload-Schritte?

Alle vier Aufrufe, INIT, APPEND, FINALIZE und STATUS, laufen über denselben Scope media.write. Das Abfragen des Verarbeitungsstatus des eigenen Uploads braucht also einen Schreib-Scope, und X veröffentlicht keine reine Lesealternative dazu.

Welche Medientypen lassen sich über den X-API-initialize-Endpunkt hochladen?

Das media_type-Enum bei INIT reicht von video/mp4 und video/quicktime über text/srt und text/vtt bis zu zwei 3D-Formaten, model/gltf-binary und model/vnd.usdz+zip. Damit deckt ein einziger Upload-Endpunkt Video-, Untertitel- und 3D-Dateien ab.