Toutes les valeurs de media_category de l'API Twitter et ce qu'elles autorisent

Qu'est-ce que le paramètre media_category de l'API Twitter ?

Huit valeurs existent pour le paramètre media_category de l'API Twitter, et X en définit le rôle en une ligne : « 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. »

Le cas d'usage, pas le type de fichier. media_type dit déjà à X que les octets forment un MP4. media_category dit à X si ce MP4 part sur un Post, dans un message privé ou dans une publicité, et X retient un plafond différent pour chaque réponse.

Le paramètre est facultatif sur POST /2/media/upload/initialize et X documente le repli : « 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. »

Ce défaut couvre les Posts et rien d'autre. Tout ce qui part vers un DM, une publicité ou une piste de sous-titres doit le déclarer, parce que X n'a aucun moyen de le déduire d'un MP4.

Qu'autorise chaque valeur de media_category de l'API Twitter ?

Chaque valeur correspond à une surface, et X publie l'énumération complète dans le schéma de l'endpoint initialize.

Valeur	Surface autorisée	Plafond par défaut	Plafond X Premium
tweet_image	Image sur un Post	5 Mo	5 Mo
tweet_gif	GIF animé sur un Post	15 Mo	15 Mo
tweet_video	Vidéo sur un Post	20 min, 8 Go	125 min, 16 Go
amplify_video	Publicités et vidéo sponsorisée	20 min, 8 Go	125 min, 16 Go
dm_image	Image dans un message privé	5 Mo	5 Mo
dm_gif	GIF animé dans un message privé	15 Mo	15 Mo
dm_video	Vidéo dans un message privé	140 s, 512 Mo	10 min, 1 Go
subtitles	Fichier de sous-titres	1 Mo	1 Mo

La durée minimale d'une vidéo est la même dans toutes les catégories vidéo. X l'énonce comme « 0.5 seconds » et la répète comme un plancher plutôt que comme une recommandation.

Deux valeurs portent une consigne au-delà de leurs limites. amplify_video est obligatoire et non facultative pour tout contenu sponsorisé, et l'Ads API le dit depuis 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 est l'interrupteur qui déclenche le traitement asynchrone des gros GIF animés, ce que X détaille sur sa page de bonnes pratiques : « 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. »

Comment media_category modifie-t-il les plafonds de taille et de durée ?

La catégorie sélectionne la ligne du tableau de limites de X qui s'applique, et l'abonnement du compte sélectionne la colonne. X nomme les deux entrées : les limites dépendent de « the authenticated user's X Premium / verified status, not your developer API plan » et de « the media_category you pass when initializing the upload. »

L'écart entre les catégories est large. Une vidéo qui tient dans tweet_video à 20 minutes doit descendre sous 140 secondes pour partir en dm_video depuis le même compte, et sous 10 minutes même avec Premium. Même fichier, même compte, même endpoint, et un facteur huit entre les deux plafonds.

total_bytes est lui aussi confronté à la catégorie. X écrit que « 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. » Deux points de rupture sont nommés et X ne dit pas lequel attrape le problème, donc traitez INIT et FINALIZE comme deux endroits où un refus de taille peut surgir.

La catégorie ne change pas les règles applicables aux images. Les images restent à 5 Mo et les GIF animés à 15 Mo, qu'ils partent sur un Post ou dans un DM, et Premium ne bouge ni l'un ni l'autre. Seules la durée et la taille des vidéos réagissent à l'abonnement, un effet plus étroit que l'ensemble des avantages X Premium ne le laisse croire.

Pourquoi X publie-t-il deux limites différentes pour amplify_video ?

Parce que la page creatives de l'Ads API et la documentation média se contredisent, et que les deux sont en ligne.

Les pages média traitent amplify_video comme l'égal de tweet_video. La page de bonnes pratiques le dit franchement : « For Posts, Premium and default duration/size caps are the same for tweet_video and amplify_video. » Son tableau donne aux deux 20 minutes et 8 Go par défaut, 125 minutes et 16 Go avec Premium.

La page creatives de l'Ads API, dans la section Promoted Video, donne un autre couple de chiffres en une seule puce : « The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less. » Elle ajoute une contrainte de format que les pages média ne mentionnent nulle part : « Uploaded video should be either mp4 or mov. »

Dix minutes contre 125. Cinq cents mégaoctets contre 16 gigaoctets. Aucune des deux pages ne reconnaît l'existence de l'autre, et aucune ne porte de date au-delà de la note de 2015 attachée à la puce du dessus. Construisez pour le couple le plus petit si la vidéo part en campagne, parce que c'est le pipeline publicitaire qui la rejetterait.

Un second décalage apparaît un cran plus loin. Les endpoints d'upload prennent des valeurs en minuscules. La media library de l'Ads API en prend en majuscules : « There are four possible category values: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE, and TWEET_VIDEO. » Quatre mêmes concepts, deux orthographes, et la liste de la media library omet entièrement les catégories DM et sous-titres.

Que se passe-t-il si vous choisissez la mauvaise media_category ?

L'upload réussit et l'appel suivant échoue. X désigne ce cas comme le plus courant : « Using the wrong category (for example a DM category on a Post) is a common reason an upload succeeds and Post create then fails. »

C'est la forme que prend presque toute erreur de media_category. INIT accepte la valeur, APPEND déplace les octets, FINALIZE renvoie un processing_info propre, et le refus arrive sur POST /2/tweets avec un 403, parce que l'upload et la publication sont contrôlés séparément. Un 403 qui dit « This user is not allowed to post a video longer than N minutes » sur une vidéo largement sous la limite d'un Post, c'est en général une catégorie dm_video qui fait exactement ce qu'on lui a demandé.

Trois pièges plus discrets se logent dans le même paramètre.

Les deux endpoints d'upload ne s'accordent pas sur le caractère facultatif du paramètre. Sur POST /2/media/upload/initialize, il est facultatif et l'énumération compte huit valeurs. Sur l'endpoint simple POST /2/media/upload, le schéma marque media et media_category comme obligatoires, et son énumération compte sept valeurs, amplify_video en moins. La vidéo sponsorisée ne peut donc pas emprunter le chemin d'upload simple, ce qui rejoint le conseil distinct de X d'utiliser l'upload en morceaux pour toute vidéo de toute façon.

Omettre la valeur sur un gros GIF revient à renoncer au traitement asynchrone dont les gros GIF ont besoin, parce que X rattache ce comportement au passage de tweet_gif et non au fichier lui-même.

Et subtitles est l'intrus. C'est la seule valeur de l'énumération qui n'est ni une image, ni un GIF, ni une vidéo, elle plafonne à 1 Mo, et ses valeurs de media_type sont text/srt et text/vtt. Un fichier de sous-titres téléversé sans elle hérite du défaut Post et se fait juger selon des règles d'image qu'il n'allait jamais satisfaire.

Chaque réseau règle cela à sa façon, et la notion de catégorie ne voyage pas. Instagram répartit la même décision entre media_type et la spécification des reels, et TikTok résout la durée par le statut du compte plutôt que par un paramètre d'upload. Sur X, toute la décision tient dans une chaîne facultative envoyée une fois, à l'INIT, et jamais modifiable ensuite. Si vous la réglez mal, tout le parcours d'upload repart de zéro.

Où une media_category erronée échoue vraiment

1

INIT. Accepte la valeur, quelle que soit la surface qu'elle désigne.

2

APPEND. Déplace les octets sans vérifier la destination.

3

FINALIZE. Renvoie un processing_info propre.

4

POST /2/tweets. Rejette avec un 403 car l'upload et la publication sont vérifiés séparément.

Questions fréquentes

Quelles valeurs le paramètre media_category de l'API Twitter accepte-t-il ?

Huit : tweet_image, tweet_video, tweet_gif, amplify_video, dm_image, dm_video, dm_gif et subtitles. C'est l'énumération publiée sur POST /2/media/upload/initialize.

media_category est-il obligatoire sur l'API X ?

Cela dépend de l'endpoint. POST /2/media/upload/initialize le traite comme facultatif et devine une catégorie Post d'après le type de contenu. L'endpoint simple POST /2/media/upload le déclare obligatoire.

Quelle différence entre tweet_video et amplify_video ?

L'usage, pas la taille. X impose amplify_video pour tout contenu sponsorisé et affirme que les plafonds de durée et de taille des deux sont identiques sur un Post. La page creatives de l'Ads API annonce toujours un plafond plus bas pour la vidéo sponsorisée, 10 minutes et 500 Mo.

Quelle durée peut faire une dm_video sur l'API X ?

140 secondes par défaut et 10 minutes pour un compte X Premium ou vérifié, avec des plafonds de taille de 512 Mo et 1 Go. La durée minimale est de 0,5 seconde, comme pour toutes les autres catégories vidéo.

Quelle erreur renvoie une mauvaise media_category ?

En général un 403 Forbidden sur POST /2/tweets plutôt qu'une erreur au moment de l'upload. X note qu'une catégorie DM utilisée sur un Post est une cause courante d'upload réussi suivi d'une création de Post en échec.

media_category influe-t-il sur les limites de taille des images ?

Non. Les images restent à 5 Mo et les GIF animés à 15 Mo, sur les Posts comme dans les DM, et X Premium ne relève ni l'un ni l'autre. Seules la durée et la taille des vidéos changent avec la catégorie et l'abonnement.

Quelle est la différence entre media_type et media_category ?

media_type indique à X le format du fichier, par exemple video/mp4. media_category indique à X à quoi ce fichier sert, un Post, un message direct, une piste de sous-titres ou une publicité. X se base sur media_category, pas sur media_type, pour choisir le plafond de taille et de durée applicable.

Quelle est la durée minimale de vidéo acceptée par l'API X ?

Le minimum est de 0,5 seconde, et X le présente comme un plancher, pas comme une recommandation. Ce minimum reste le même pour chaque catégorie de vidéo, tweet_video, amplify_video, dm_video et les autres, changer de catégorie ne l'abaisse pas.

Quel format vidéo l'API Ads de X exige-t-elle pour le promoted video ?

La page des créations de l'Ads API exige mp4 ou mov pour la vidéo envoyée dans du contenu promu. Elle le dit sans détour : uploaded video should be either mp4 or mov. Les pages de documentation media ne reprennent cette contrainte nulle part ailleurs.

Le promoted video peut-il passer par l'endpoint simple de media upload ?

Le promoted video ne peut pas passer par l'endpoint simple d'envoi. Son enum liste sept valeurs de media_category et laisse amplify_video de côté, alors que POST /2/media/upload/initialize en garde huit. Cela rejoint la recommandation à part de X d'utiliser le chunked upload pour toute vidéo, quelle que soit la catégorie.