Jeder Twitter API media_category-Wert und was er erlaubt

Was ist der twitter api media_category-Parameter?

Acht Werte gibt es für den twitter api media_category-Parameter, und X beschreibt seine Aufgabe in einer Zeile: „The Media Category parameter defines the use case of the media file to be uploaded, and can affect file size limits or other constraints enforced for media uploads.“

Anwendungsfall, nicht Dateityp. media_type sagt X bereits, dass die Bytes ein MP4 sind. media_category sagt X, ob dieses MP4 auf einen Post, in eine Direct Message oder in eine Anzeige geht, und X wählt für jede Antwort eine andere Obergrenze.

Der Parameter ist auf POST /2/media/upload/initialize optional, und X dokumentiert den Rückfallweg: „If media category is not specified, the uploaded media is assumed to be media for a Post (tweet_image, tweet_video, or tweet_gif), depending on the content type.“

Dieser Standard deckt Posts ab und sonst nichts. Alles, was für eine DM, eine Anzeige oder eine Untertitelspur bestimmt ist, muss es ausdrücklich sagen, denn X kann es aus einem MP4 nicht ableiten.

Was erlaubt jeder twitter api media_category-Wert?

Jeder Wert steht für genau eine Oberfläche, und X veröffentlicht das vollständige Enum im Schema des initialize-Endpunkts.

Wert	Erlaubte Oberfläche	Standardgrenze	Grenze mit X Premium
tweet_image	Bild auf einem Post	5 MB	5 MB
tweet_gif	Animiertes GIF auf einem Post	15 MB	15 MB
tweet_video	Video auf einem Post	20 Min., 8 GB	125 Min., 16 GB
amplify_video	Anzeigen und beworbenes Video	20 Min., 8 GB	125 Min., 16 GB
dm_image	Bild in einer Direct Message	5 MB	5 MB
dm_gif	Animiertes GIF in einer Direct Message	15 MB	15 MB
dm_video	Video in einer Direct Message	140 s, 512 MB	10 Min., 1 GB
subtitles	Untertiteldatei	1 MB	1 MB

Die Mindestdauer für Video ist in jeder Kategorie gleich. X nennt sie mit „0.5 seconds“ und wiederholt sie als Untergrenze, nicht als Empfehlung.

Zwei Werte tragen eine Anweisung über ihre Grenzen hinaus. amplify_video ist für alles Beworbene Pflicht statt Option, und die Ads API sagt das seit 2015: „When uploading videos to be used in promoted content, the media_category parameter must be set with a value of amplify_video for all INIT command requests.“ tweet_gif ist der Schalter, der die asynchrone Verarbeitung für große animierte GIFs einschaltet, was X auf der Best-Practices-Seite ausschreibt: „In order to process larger GIFs, use the chunked upload endpoint with the media_category parameter. This allows the server to process the GIF file asynchronously, which is a requirement for processing larger files.“

Wie verändert media_category die Größen- und Dauergrenzen?

Die Kategorie wählt, welche Zeile der Limit-Tabelle von X gilt, und das Abo des Kontos wählt die Spalte. X benennt beide Eingaben: Die Grenzen hängen ab von „the authenticated user's X Premium / verified status, not your developer API plan“ und von „the media_category you pass when initializing the upload.“

Der Abstand zwischen den Kategorien ist groß. Ein Video, das mit tweet_video 20 Minuten lang sein darf, muss unter 140 Sekunden bleiben, um vom selben Konto als dm_video rauszugehen, und selbst mit Premium unter 10 Minuten. Gleiche Datei, gleiches Konto, gleicher Endpunkt und ein Faktor acht zwischen den beiden Grenzen.

Auch total_bytes wird gegen die Kategorie geprüft. X schreibt: „POST /2/media/upload/initialize accepts total_bytes up to 16 GB. Passing a larger total_bytes than the account is allowed to upload fails at initialize or finalize.“ Zwei Fehlerstellen werden genannt, und X sagt nicht, welche davon greift, behandle also sowohl INIT als auch FINALIZE als Ort, an dem eine Größenablehnung auftauchen kann.

An den Bildregeln ändert die Kategorie nichts. Bilder bleiben bei 5 MB und animierte GIFs bei 15 MB, ob sie für einen Post oder eine DM bestimmt sind, und Premium bewegt keine der beiden Zahlen. Nur Videodauer und Videodateigröße reagieren auf das Abo, was eine engere Wirkung ist, als der volle Umfang der X-Premium-Leistungen vermuten lässt.

Warum veröffentlicht X zwei verschiedene Grenzen für amplify_video?

Weil die Ads-API-Seite zu Creatives und die Mediendokumentation sich widersprechen und beide aktiv sind.

Die Medienseiten behandeln amplify_video als Gleichwertiges zu tweet_video. Die Best-Practices-Seite sagt es direkt: „For Posts, Premium and default duration/size caps are the same for tweet_video and amplify_video.“ Ihre Tabelle gibt beiden standardmäßig 20 Minuten und 8 GB, mit Premium 125 Minuten und 16 GB.

Die Ads-API-Seite zu Creatives nennt im Abschnitt Promoted Video in einem einzigen Aufzählungspunkt ein anderes Zahlenpaar: „The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less.“ Sie ergänzt eine Formatvorgabe, die die Medienseiten ebenfalls nicht erwähnen: „Uploaded video should be either mp4 or mov.“

Zehn Minuten gegen 125. Fünfhundert Megabyte gegen 16 Gigabyte. Keine der beiden Seiten nimmt die andere zur Kenntnis, und keine trägt ein Datum jenseits der 2015er-Notiz am Aufzählungspunkt darüber. Baue für das kleinere Paar, wenn das Video in eine Kampagne geht, denn die Ads-Pipeline ist diejenige, die es ablehnen würde.

Eine zweite Unstimmigkeit zeigt sich eine Ebene weiter. Die Upload-Endpunkte nehmen Werte in Kleinschreibung. Die Media Library der Ads API nimmt sie in Großschreibung: „There are four possible category values: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE, and TWEET_VIDEO.“ Dieselben vier Konzepte, zwei Schreibweisen, und die Liste der Media Library lässt die DM- und Untertitelkategorien komplett weg.

Was passiert, wenn du die falsche media_category wählst?

Der Upload gelingt und der nächste Aufruf scheitert. X nennt das als den häufigen Fall: „Using the wrong category (for example a DM category on a Post) is a common reason an upload succeeds and Post create then fails.“

So sieht fast jeder media_category-Fehler aus. INIT nimmt den Wert an, APPEND bewegt die Bytes, FINALIZE liefert ein sauberes processing_info, und die Ablehnung kommt bei POST /2/tweets mit einem 403, weil Upload und Posten getrennt durchgesetzt werden. Ein 403 mit dem Text „This user is not allowed to post a video longer than N minutes“ bei einem Video deutlich unter der Post-Grenze ist meist eine dm_video-Kategorie, die genau tut, was man ihr gesagt hat.

Drei kleinere Fallen sitzen im selben Parameter.

Die beiden Upload-Endpunkte sind sich nicht einig, ob der Parameter optional ist. Auf POST /2/media/upload/initialize ist er optional und das Enum hat acht Werte. Auf dem einfachen Endpunkt POST /2/media/upload listet das Schema media und media_category als Pflicht, und sein Enum hat sieben Werte, wobei amplify_video fehlt. Beworbenes Video kann den einfachen Upload-Weg also überhaupt nicht nehmen, was zum separaten Rat von X passt, für jedes Video ohnehin den Chunked Upload zu benutzen.

Wer den Wert bei einem großen GIF weglässt, verzichtet auf die asynchrone Verarbeitung, die große GIFs brauchen, denn X koppelt dieses Verhalten an das Senden von tweet_gif und nicht an die Datei selbst.

Und subtitles ist der Sonderfall. Es ist der einzige Wert im Enum, der weder Bild noch GIF noch Video ist, es endet bei 1 MB, und seine media_type-Werte sind text/srt und text/vtt. Eine Untertiteldatei, die ohne diesen Wert hochgeladen wird, erbt den Post-Standard und wird an Bildregeln gemessen, die sie nie erfüllen konnte.

Jedes Netzwerk löst das anders, und das Kategoriekonzept lässt sich nicht übertragen. Instagram verteilt dieselbe Entscheidung stattdessen auf media_type und die Reels-Spezifikation, und TikTok klärt die Dauer über den Status des Kontos statt über einen Upload-Parameter. Auf X steckt die ganze Entscheidung in einem optionalen String, den du einmal beim INIT sendest und danach nie mehr änderst. Wenn du ihn falsch setzt, beginnt die Upload-Anleitung wieder von vorn.

Wo eine falsche media_category tatsächlich scheitert

1

INIT. Akzeptiert den Wert, unabhängig davon, welche Oberfläche er benennt.

2

APPEND. Verschiebt die Bytes, ohne das Ziel zu prüfen.

3

FINALIZE. Liefert ein sauberes processing_info zurück.

4

POST /2/tweets. Lehnt mit einem 403 ab, weil Upload und Posten getrennt geprüft werden.

Häufig gestellte Fragen

Welche Werte akzeptiert der twitter api media_category-Parameter?

Acht: tweet_image, tweet_video, tweet_gif, amplify_video, dm_image, dm_video, dm_gif und subtitles. Das ist das Enum, das auf POST /2/media/upload/initialize veröffentlicht ist.

Ist media_category in der X API Pflicht?

Das hängt vom Endpunkt ab. POST /2/media/upload/initialize behandelt ihn als optional und rät eine Post-Kategorie anhand des Content-Type. Der einfache Endpunkt POST /2/media/upload führt ihn als Pflicht.

Was ist der Unterschied zwischen tweet_video und amplify_video?

Der Zweck, nicht die Größe. X verlangt amplify_video für alles, was in beworbenen Inhalten benutzt wird, und sagt, dass die Dauer- und Größengrenzen der beiden auf einem Post gleich sind. Die Ads-API-Seite zu Creatives nennt weiterhin eine niedrigere Obergrenze für beworbenes Video von 10 Minuten und 500 MB.

Wie lang darf ein dm_video in der X API sein?

140 Sekunden standardmäßig und 10 Minuten mit einem X-Premium- oder verifizierten Konto, bei Dateigrenzen von 512 MB und 1 GB. Die Mindestdauer liegt bei 0,5 Sekunden, genau wie bei jeder anderen Videokategorie.

Welchen Fehler bekommst du bei der falschen media_category?

Meist ein 403 Forbidden auf POST /2/tweets statt eines Fehlers beim Upload. X merkt an, dass eine DM-Kategorie auf einem Post ein häufiger Grund dafür ist, dass ein Upload gelingt und das Erstellen des Posts danach scheitert.

Wirkt sich media_category auf Bildgrößengrenzen aus?

Nein. Bilder bleiben bei 5 MB und animierte GIFs bei 15 MB über Posts und DMs hinweg, und X Premium hebt keine der beiden Grenzen an. Nur Videodauer und Videodateigröße ändern sich mit Kategorie und Abo.

Was ist der Unterschied zwischen media_type und media_category?

media_type sagt X, in welchem Format die Datei vorliegt, zum Beispiel video/mp4. media_category sagt X, wofür die Datei gedacht ist, für einen Post, eine Direktnachricht, eine Untertitelspur oder eine Anzeige. X nutzt media_category, nicht media_type, um zu entscheiden, welche Größen- und Dauergrenze gilt.

Wie kurz darf ein Video bei der X API mindestens sein?

Die Mindestdauer liegt bei 0,5 Sekunden, und X nennt sie eine feste Untergrenze, keine Empfehlung. Diese Grenze gilt gleich für jede Videokategorie, tweet_video, amplify_video, dm_video und die übrigen, ein Wechsel der Kategorie senkt sie nicht.

Welches Videoformat verlangt die X Ads API für Promoted Video?

Die Ads API Creatives-Seite verlangt mp4 oder mov für hochgeladenes Video in Promoted Content. Sie hält das direkt fest: uploaded video should be either mp4 or mov. Die Media-Dokumentation erwähnt diese Einschränkung an keiner anderen Stelle.

Kann Promoted Video über den einfachen Media-Upload-Endpunkt laufen?

Promoted Video kann nicht über den einfachen Upload-Endpunkt laufen. Dessen Enum listet sieben media_category-Werte und lässt amplify_video aus, während POST /2/media/upload/initialize alle acht behält. Das passt zu X eigenem Hinweis, für jedes Video unabhängig von der Kategorie den Chunked Upload zu verwenden.