Passer au contenu principal
Ce guide vous aidera à effectuer vos premières requêtes pour téléverser des médias à l’aide des endpoint(s) de téléversement de médias de l’X API v2. Dans ce guide, les endpoints segmentés POST /2/media/upload sont utilisés pour téléverser une vidéo, ce qui nécessite un flux de travail différent de celui des téléversements d’image uniques. Pour les vidéos ou les téléversements segmentés, vous devez :
  1. Initialiser le téléversement avec la commande INIT
  2. Téléverser chaque segment d’octets avec la commande APPEND
  3. Finaliser le téléversement avec la commande FINALIZE
Remarque : Consultez cet exemple de code pour un exemple en Python.

​
Authentification

Pour exécuter les exemples fournis dans ce guide, vous devrez utiliser l’authentification OAuth 2. Vous trouverez vos CONSUMER_KEY, CONSUMER_SECRET, ACCESS_KEY et ACCESS_TOKEN dans l’App de votre Project, dans le developer portal dashboard.

​
Étape 1 : POST media/upload (INIT)

La requête INIT sert à démarrer une session de téléversement de fichier. Elle renvoie un media_id qui devra être utilisé pour toutes les requêtes ultérieures. L’étape suivante après un retour réussi de INIT est la commande APPEND. Voir Meilleures pratiques pour connaître les contraintes et exigences applicables aux fichiers média. Exemple de requête 
curl --location 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <VOTRE_JETON_ACCES>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=INIT' \
    --form 'media_type=video/mp4' \
    --form 'total_bytes=1024' \
    --form 'media_category=amplify_video'
Remarque : Pour les requêtes HTTP brutes, la requête doit utiliser les formats de POST multipart/form-data ou application/x-www-form-urlencoded.
Exemple de réponse 
{
    "data":
    {
        "id":"1880028106020515840",
        "media_key":"13_1880028106020515840",
        "expires_after_secs":1295999
    }
}
La réponse fournit les identifiants de média id (chaîne) et media_key (chaîne). L’intégralité du fichier doit être téléversée avant l’expiration, soit dans les expires_after_secs secondes.

​
Étape 2 : POST media/upload (APPEND)

La commande APPEND sert à téléverser un segment (plage d’octets consécutifs) du fichier média. Par exemple, un fichier de 3 Mo peut être découpé en 3 segments de 1 Mo et téléversé au moyen de 3 requêtes APPEND. Une fois le fichier entièrement téléversé, l’étape suivante consiste à appeler la commande FINALIZE.
Le téléversement d’un fichier média en petits segments présente plusieurs avantages :
  • Meilleure fiabilité et taux de réussite en cas de faible bande passante
  • Possibilité de mettre en pause et de reprendre les téléversements
  • Nouveaux essais possibles segment par segment
  • Possibilité d’ajuster la taille des segments pour s’adapter à l’évolution des conditions réseau, p. ex. sur des clients mobiles
Exemple de requête 
curl --location 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <VOTRE_JETON_ACCES>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=APPEND' \
    --form 'media_id=1880028106020515840' \
    --form 'segment_index=0' \
    --form 'media=@/chemin/vers/votre/fichier/media.mp4'
segment_index est l’indice ordonné du fragment de fichier. Sa valeur doit être comprise entre 0 et 999 inclus. Le premier segment a l’indice 0, le deuxième l’indice 1, et ainsi de suite. Continuez à téléverser les fragments du fichier jusqu’à ce que tous aient été téléversés.
Remarque : Pour les requêtes HTTP brutes, la requête doit être au format POST multipart/form-data.
Remarque : En cas de téléversement réussi, une réponse HTTP 2XX est renvoyée avec un corps vide.

​
Étape 3 : POST media/upload (FINALIZE)

La commande FINALIZE doit être appelée après que l’intégralité du fichier média a été téléversée à l’aide des commandes APPEND. Si, et seulement si, la réponse de la commande FINALIZE contient un champ processing_info, il peut également être nécessaire d’utiliser une commande STATUS et d’attendre qu’elle renvoie un succès avant de procéder à la création du Post. Exemple de requête 
curl --location --request POST 'https://api.x.com/2/media/upload' \
    --header 'Authorization: Bearer <VOTRE_JETON_ACCES>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'command=FINALIZE' \
    --form 'media_id=1880028106020515840'
Remarque : Lors de l’envoi de requêtes HTTP brutes, la requête doit utiliser les formats POST multipart/form-data ou application/x-www-form-urlencoded.
Exemple de réponse 
{
    "data": {
        "id": "1880028106020515840",
        "media_key": "13_1880028106020515840",
        "size": 1024,
        "expires_after_secs": 86400,
        "processing_info": {
            "state": "pending",
            "check_after_secs": 1
        }
    }
}
La réponse fournit un identifiant de média dans les champs media_id (entier 64 bits) et media_id_string (chaîne). Utilisez la valeur media_id_string fournie dans la réponse de l’API avec JavaScript et d’autres langages qui ne peuvent pas représenter fidèlement un entier long. Le media_id renvoyé n’est valide que pendant expires_after_secs secondes. Toute tentative d’utiliser mediaId après ce délai dans d’autres appels à l’API se traduira par une réponse Bad Request (HTTP 4xx). Si la réponse contient un champ processing_info, utilisez la commande STATUS pour interroger l’état de l’opération FINALIZE. L’approche d’achèvement asynchrone est utilisée lorsque le traitement du média nécessite plus de temps. À l’avenir, tous les traitements de vidéos et de GIF animés ne seront pris en charge qu’avec l’achèvement asynchrone. Ce comportement est activé si une session de téléversement a été initialisée avec un paramètre media_category, et lorsque le type de média est une vidéo ou un GIF animé.
Remarque : Si aucun champ processing_info n’est renvoyé dans la réponse, alors media_id est prêt à être utilisé dans d’autres endpoints de l’API.

​
Étape 4 : GET media/upload (STATUS)

La commande STATUS sert à interroger périodiquement l’avancement du traitement des médias. Une fois que la réponse de la commande STATUS indique succeeded, vous pouvez passer à l’étape suivante, qui consiste généralement à créer un Post avec media_id.
Remarque : N’utilisez la commande STATUS que si la réponse de la commande FINALIZE, ou d’une précédente commande STATUS, contenait un champ processing_info.

​
Exemple de requête

curl --location --request GET 'https://api.x.com/2/media/upload?command=STATUS&media_id=1880028106020515840' \
    --header 'Authorization: Bearer <VOTRE_JETON_D_ACCES>'

​
Exemple de réponse

{
    "data":{
        "id":"1880028106020515840",
        "media_key":"13_1880028106020515840",
        "processing_info":{
            "state":"uploading" // le flux de transition d'état est pending -> in_progress -> [failed|succeeded]
        }
    }
}
Le corps de la réponse contient le champ processing_info, qui fournit des informations sur l’état actuel de l’opération de traitement des médias. Il inclut un champ state dont le flux de transition est : pending -> in_progress -> [failed | succeeded]. Vous ne pouvez pas utiliser le media_id pour créer un Post ou d’autres entités tant que le champ state n’est pas défini sur succeeded.

​
Étape 5 : Publier un Tweet avec média

Crée un Post à l’aide de l’endpoint POST /2/tweets, en incluant le media_id pour le compte d’un utilisateur authentifié. Exemple de requête 
curl --location 'https://api.x.com/2/tweets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
--data '{
    "text": "J'ai publié un Post avec des médias !",
     "media": {
       "media_ids": [
            "1880028106020515840"
        ]
    }
}'
Exemple de réponse 
{
    "data": {
        "edit_history_tweet_ids": [
            "1880028106020515840"
        ],
        "id": "1880028106020515840",
        "text": "J'ai publié un Post avec des médias ! https://t.co/DqNyXX"
    }
}

​
Dépannage

Pour les problèmes liés aux Media API, parcourez la catégorie Media API des forums développeurs pour trouver une réponse.
⌘I