> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Créations publicitaires
export const Button = ({href, children}) => {
return
;
};
## Vue d’ensemble
Les créations sont toutes les entités qui peuvent être promues dans une campagne. Les Publications peuvent inclure du texte, des images, des GIF, des vidéos ou des cartes. Les cartes peuvent inclure des images ou des vidéos.
Les créations d’images, de GIF ou de vidéos sont importées à l’aide soit de [POST media/upload](/fr/x-api/media/upload-media#post-media-upload) — un endpoint de téléchargement simple qui ne prend en charge que les images — soit des endpoints POST media/upload (chunked). Elles peuvent ensuite être ajoutées aux
cartes :
* POST accounts/:account\_id/cards
Tweets :
* POST accounts/:account\_id/tweets - Pour ajouter des cartes à des Tweets, utilisez le paramètre card\_uri.
Tweets programmés :
* POST accounts/:account\_id/scheduled\_tweets
Pour plus de détails sur les cartes, consultez la page Cards. La page Promoted Video fournit des détails sur l’association de vidéos avec des cartes ou des Tweets.
### Cards
L’API Ads prend en charge plusieurs types de cartes pouvant être utilisées dans des Tweets, puis promues dans des campagnes. **Remarque :** une fois la carte intégrée dans un Tweet, ses détails deviennent visibles publiquement. Cela peut inclure des informations sur l’utilisateur qui possède la carte.
#### Image
Les spécifications d’image suivantes s’appliquent aux ressources utilisées dans les [Cards](/fr/x-ads-api/creatives#cards-2). Les images doivent faire 3 Mo maximum et avoir une largeur d’au moins 800 px. De plus, nous prenons en charge les rapports largeur:hauteur suivants :
* Site Web : 1:1 et 1,91:1
* Image App Download : 1:1 et 1,91:1
* Sondage : 1,91:1
* Image Conversation : 1,91:1
* Image Direct Message : 1,91:1
Nous prenons en charge les formats d’image suivants : .bmp, .jpeg et .png.
#### Vidéo
Les spécifications vidéo suivantes s’appliquent aux ressources utilisées dans les [Cards](/fr/x-ads-api/creatives#cards-2). Nous prenons en charge les ratios largeur:hauteur suivants.
* Vidéo de site Web : 16:9 et 1:1
* Vidéo de téléchargement d’App : 16:9 et 1:1
* Sondage : 16:9
* Vidéo de conversation : 16:9
* Vidéo de message privé : 16:9
### Vidéo sponsorisée
Ce document fournit un bref aperçu du processus de téléversement et de promotion de vidéos via l’Ads API.
L’Ads API prend en charge la vidéo sponsorisée dans les [Tweets](/fr/x-ads-api/creatives#tweets-2) et dans les cartes suivantes :
* [Video Website](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [Video App Download](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [Video Conversation](/fr/x-ads-api/creatives#video-conversation-cards)
Commencez par téléverser la vidéo en utilisant l’endpoint [POST media/upload (chunked)](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload-init.html). À l’aide du `media_id`, associez la vidéo à un compte publicitaire en utilisant l’endpoint POST accounts/:account\_id/videos. L’`id` de la vidéo, parfois appelé `media_key`, sera utilisé dans les requêtes suivantes. Il s’agit d’une chaîne qui commence par un entier, suivie d’un caractère de soulignement, et se termine par une valeur de type long. Par exemple : `13_875943225764098048`.
#### Vidéo sponsorisée dans les Tweets
Pour créer un Tweet, utilisez l’endpoint [POST accounts/:account\_id/tweet](/fr/x-ads-api/creatives#get-accounts-account-id-tweets) avec l’`id` de la vidéo. À ce stade, vous pouvez également fournir un titre pour la vidéo, une description et un appel à l’action (CTA). Ces valeurs sont affichées aux utilisateurs.
#### Vidéo sponsorisée dans les cartes
Les cartes Video App Download et Video Conversation permettent d’ajouter une image d’affiche. Téléversez une image à utiliser dans ces cartes à l’aide de l’endpoint [POST media/upload](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload.html).
Créez la carte à l’aide de l’un des endpoints suivants :
* [POST accounts/:account\_id/cards/video\_website](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [POST accounts/:account\_id/cards/video\_app\_download](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [POST accounts/:account\_id/cards/video\_conversation](https://devcommunity.x.com/t/ads-api-version-11/168814)
en utilisant l’`id` de la vidéo et, facultativement, le `media_id` de l’image (pour l’image d’affiche).
Enfin, créez le Tweet à l’aide de l’endpoint POST accounts/:account\_id/tweet. Les cartes sont associées aux Tweets en utilisant le paramètre `card_uri`.
#### Informations générales
Pour des instructions détaillées sur le téléversement de vidéos via l’API, veuillez consulter le [Guide de téléversement de vidéos](https://developer.x.com/en/docs/media/upload-media/uploading-media.html).
Les vidéos peuvent également être promues en tant qu’éléments pré‑roll. Consultez le [Guide sur l’objectif de vues vidéo pré‑roll](/fr/x-ads-api/campaign-management#video-views-preroll-objective) pour une explication détaillée.
* (À compter du 2015-10-22) Lors du téléversement de vidéos destinées à être utilisées dans du contenu promu, le paramètre `media_category` doit être défini avec la valeur `amplify_video` pour toutes les requêtes de commande `INIT` vers le endpoint [POST media/upload (chunked)](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload-init.html). L’utilisation de ce nouveau paramètre garantit que la vidéo est prétraitée de manière asynchrone et préparée pour être utilisée dans du contenu promu. La commande `STATUS` peut être utilisée pour vérifier la fin du traitement asynchrone après le téléversement de la vidéo.
* La durée maximale actuellement autorisée pour une vidéo promue est de 10 minutes, avec une taille de fichier de 500 Mo ou moins.
* La vidéo téléversée doit être au format mp4 ou mov.
* La vidéo téléversée est généralement traitée rapidement, mais les temps de traitement peuvent varier en fonction de la durée et de la taille du fichier.
* Les images d’aperçu téléversées doivent être au format png ou jpg. Il n’y a pas d’exigence de rapport hauteur/largeur ou de taille, mais l’image d’aperçu sera ajustée pour s’adapter au lecteur vidéo.
## Guides
### Tweets programmés
#### Introduction
Les Tweets programmés permettent à un annonceur ou à un utilisateur de créer un Tweet qui pourra être mis en ligne à une date ultérieure. En plus de pouvoir créer et gérer ces Tweets, l’API permet d’associer ces Tweets à un line item, afin qu’ils soient promus une fois le Tweet mis en ligne. Cela permet aux annonceurs de préparer des Tweets natifs et de planifier à l’avance les créations de leurs campagnes pour toute initiative clé. Par exemple, préparer une création de Tweet pour qu’elle soit mise en ligne immédiatement lors de l’annonce d’un nouveau produit.
L’ensemble des fonctionnalités fournies par les endpoints de l’API Scheduled Tweets est listé ci‑dessous :
* Créer, modifier et afficher de nouveaux Tweets programmés
* Associer un Tweet programmé à un line item
* Interroger et gérer les Tweets programmés existants
* Une fois qu’un Tweet programmé est mis en ligne, récupérer l’`id` du Tweet en ligne
#### Points de terminaison de l’API
L’ensemble des points de terminaison liés à la fonctionnalité ci-dessus est présenté ci-dessous :
#### Gestion des Tweets programmés
* [GET accounts/:account\_id/scheduled\_tweets](/fr/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) (obtenir la liste de tous les Tweets programmés)
* [GET accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/fr/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) (obtenir un Tweet programmé spécifique en utilisant son `id`)
* [POST accounts/:account\_id/scheduled\_tweets](/fr/x-ads-api/creatives#post-accounts-account-id-scheduled-tweets) (créer un nouveau Tweet programmé)
* [PUT accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/fr/x-ads-api/creatives#example-request-39) (modifier un Tweet programmé existant)
* [DELETE accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/fr/x-ads-api/creatives#example-request-40) (supprimer un Tweet programmé en utilisant son `id`)
* [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/fr/x-ads-api/creatives#scheduled-tweets-2) (prévisualiser un Tweet programmé existant)
#### Tweets sponsorisés programmés
* [GET accounts/:account\_id/scheduled\_promoted\_tweets](/fr/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets) (obtenir la liste de tous les Tweets sponsorisés programmés)
* [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/fr/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (rechercher un Tweet sponsorisé programmé à partir de son `id`)
* [POST accounts/:account\_id/scheduled\_promoted\_tweets](/fr/x-ads-api/campaign-management#post-accounts-account-id-scheduled-promoted-tweets) (créer un nouveau Tweet sponsorisé programmé)
* [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/fr/x-ads-api/campaign-management#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (supprimer un Tweet sponsorisé programmé existant à partir de son `id`)
#### Affichage d’un Tweet programmé
* [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/fr/x-ads-api/creatives#scheduled-tweets-2) (afficher un Tweet programmé existant)
Du fait que les Tweets programmés soient des entités distinctes des Tweets publiés, deux ensembles de validations différents sont appliqués à toute création ou modification de ces Tweets. Le premier ensemble de règles de validation est appliqué lors de l’étape de création du Tweet programmé, plus précisément :
#### Création de Tweet programmé :
* Vérifiez que l’utilisateur authentifié est autorisé à créer des Tweets organiques pour un @handle donné. Les privilèges de création de Tweet Promoted-Only exigent que l’utilisateur authentifié soit un utilisateur du compte disposant des [Tweet composer permissions](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/authenticated-user-access#get-accounts-account-id-authenticated-user-access).
* Vérifiez qu’il n’y a pas plus de 30 Tweets dont la création est programmée dans une fenêtre de 15 minutes autour de l’horodatage `scheduled_at`. Un message d’erreur SCHEDULED\_TWEET\_LIMIT\_EXCEEDED indique que trop de Tweets programmés ont été définis dans la même plage future de 15 minutes. Les annonceurs devront supprimer un Tweet programmé existant ou déplacer l’horodatage `scheduled_at` plus tôt ou plus tard.
#### Le Tweet programmé est publié :
* Ces règles de validation sont exécutées à l’heure programmée (scheduled\_at) et sont identiques à celles appliquées lors de la création classique d’un Tweet via l’API. Par exemple, un Tweet programmé ne sera pas publié et scheduled\_status sera défini sur FAILED si le Tweet programmé contient à la fois une image et un GIF.
#### Workflow
**Créer un nouveau Tweet programmé**
Un nouveau Tweet programmé peut être créé à l'aide du point de terminaison [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets). Ce point de terminaison a les paramètres obligatoires suivants : l'heure `scheduled_at` ainsi que le `text` du Tweet si aucune entité média n'est incluse dans le Tweet. De plus, ce point de terminaison fournit quelques options supplémentaires qui vous permettent de créer un Tweet programmé pour le compte d'un autre @handle via le paramètre `as_user_id`, ainsi que d'ajouter une carte (`card_uri`) et des médias (`media_ids`). À noter qu'un Tweet ne peut contenir que des entités d'un seul type, c'est‑à‑dire soit Vidéo, GIF ou Image. Le paramètre `nullcast` contrôle si le Tweet est un Tweet « Promoted-Only » ou non. Tous les nouveaux Tweets programmés créés sont « Promoted-Only » (`nullcast=true`) par défaut. Si `nullcast=false`, alors un Tweet programmé organique est créé.
Une fois qu'un Tweet programmé est créé avec succès, la réponse contient un champ `id`, qui fait référence à l'identifiant unique du Tweet programmé lui‑même. En plus de ce champ, un autre champ appelé `tweet_id` est également renvoyé. Ce champ est initialement à `null`, mais une fois que le Tweet est publié, ce champ est renseigné avec l'id du Tweet « live ».
```
twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Happy Holidays!'
```
Cela va créer le Tweet programmé suivant :
```json theme={null}
{
"request": {
"params": {
"text": "Happy Holidays!",
"scheduled_at": "2017-12-24T23:59:00Z"
}
},
"data": {
"completed_at": null,
"id_str": "917507899668099072",
"text": "Happy Holidays!",
"user_id": "3271358660",
"scheduled_status": "SCHEDULED",
"id": 917507899668099100,
"nullcast": true,
"created_at": "2017-10-09T21:51:44Z",
"scheduled_at": "2017-12-24T23:59:00Z",
"card_uri": null,
"updated_at": "2017-10-09T21:51:44Z",
"tweet_id": null,
"media_keys": []
}
}
```
Une fois que ce Tweet programmé est diffusé, le champ `tweet_id` sera renseigné avec l’ID du Tweet « en direct ».
**Afficher un Tweet programmé**
L’endpoint [GET accounts/:account\_id/tweet\_previews](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) peut ensuite être utilisé avec l’`id` du Tweet programmé obtenu à l’étape précédente pour générer un aperçu du Tweet. La réponse de l’API contiendra une URL d’iframe prête à être utilisée pour afficher un aperçu du Tweet programmé. Les ressources CSS et les images concernées seront servies directement via X.
```
twurl -H ads-api.x.com -X GET "/6/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072
```
```json theme={null}
{
"request": {
"params": {
"tweet_type": "SCHEDULED",
"tweet_ids": [
"917507899668099072"
],
"account_id": "18ce54bgxky"
}
},
"data": [
{
"tweet_id": "1126633863155871744",
"preview": "<\iframe class='tweet-preview' src='https://ton.smf1.x.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAK1WTW%2FjNhD9Kyyv9dqSZdmOgALJbhJsCyxaIDkUWBUEJY0lNhSpklRSN%2FV%2F71CyZbm297S%2BWJxPzpt5I71T9wbgaELeaW6AOygYxyN9rlryhW9JcEPmUbKIkuiG%2FBjgj8yD8IZOqChoEobz5TKK1ssojOP1KlwtFl7BrDMY4oIW%2FTatlMzB3z7JZ940W%2FJZS1Hwrf0Btc60Kve3oMmGSwsTWgjbSL7tXJjhqgSafA0mYfzHhIJywgmwNHmnFbeV4yU%2Bf0WN3daZlvtDa8Gw2htrdRCZXrlDU92aHIPStA2CKOekMrD5KaWVc02SztIZps%2Bh0rIAg27TXNcpJQYk2ii90VLqt7R3ht%2B4cQoMeVClUIAPd03Th01nvDfx0ClmoJFYk0aouGst82gqROaKskf03KCr7LLvXnXN02K3QTHFaziovYdH0seL5qswitfLZTBq6FGIRfSe9Lm1FTfkY%2BX%2FFcpPAlNRC7eufdFSY1%2BxASh84oo8YitzYXM9IZ%2FuaNcQ1HjMbQc61l0VXDmYlsJVbTYVGq0KwPCi2cf5tQFFnjR2zyDU6YycwX%2Fr3oRzvfKpwTaSZ8NfQUoU%2FUsetanxAV79VElhHbm1oIrSiILcvvgquqSN0Q7y8Uz2TQdjWa5bhZP8IUShEeh8IvIxkVB7SY%2FyKctaIL%2B0kgQrMp8n0SKJ10eWxZ4t%2FBXHUzg4idu6nOnNxsIQ1Yka2D9aDc0sQTNQPJP%2B2sgqvPUrGLERozL68ToNLRELvBj4VuZaOSOy1mmsdAi2dxaWOeyhlRzVl6TYozMnhHIjJLCM5y%2BlwaweHOn96afg%2FuHhnl60ETUvgR1HpJsQntkptrcuO0bOOhuLg1NBPfyH6Swrpw2W9O24rBu8kwH8DuEdns9Kv1hLc5rsxBaTLcN1HIdhHIVRuFov5wtMXH748vO2%2BP0jUzjFXE7%2FbMa3%2BFZl3z1ZxhWyjv2fwlfy9NaY6LhO0lm4WC3WcRSvlqO4UqiXYT7C%2B7vwcT7SWlFAxg3LtMHNfH2ODnZ4kIPVPRo9jnN1r5eDNup%2BIy2y5GxuDrQqYMNb6dje9or44HOyQYTnWs%2FXXoD7%2Ba8WrGO4hwZuK%2B2Qt%2F32tAPhB%2B4xt238qjVQtpIbuuvIP6wbjfAIhStncO3eZ0f9keMHmYHuo%2BCwFoJ%2BDfktdEF0JPfebbxgct30b%2BdhY%2B51u%2FGm2U2IR7rW%2FbJU%2FdcBfpEchHjwoO52%2FwENmVvErwgAAA%3D%3D'>"
}
]
}
```
Un exemple du Tweet programmé récemment créé est affiché ci-dessus
**Associer un Tweet programmé à un élément de campagne**
Même si les Tweets programmés peuvent être utilisés pour créer des Tweets organiques, nous permettons également aux partenaires de créer un Tweet « Promoted-Only » (`nullcast=true`), dont l’un ou l’autre peut être associé à un élément de campagne. Pour ce faire, nous proposons également un endpoint [POST accounts/:account\_id/scheduled\_promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#post-accounts-account-id-scheduled-promoted-tweets). Cet endpoint permet uniquement d’associer un seul Tweet programmé promu à un élément de campagne dans un seul appel d’API. Pour associer plusieurs Tweets programmés au même élément de campagne, plusieurs appels d’API sont nécessaires.
Veuillez noter qu’il n’est pas possible de modifier un Tweet programmé promu existant.
```
twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072'
```
```json theme={null}
{
"data": {
"line_item_id": "a44qc",
"id": "26576",
"created_at": "2017-10-09T22:24:16Z",
"updated_at": "2017-10-09T22:24:16Z",
"scheduled_tweet_id": "917507899668099072",
"tweet_id": null,
"deleted": false
},
"request": {
"params": {
"line_item_id": "a44qc",
"scheduled_tweet_id": 917507899668099100,
"account_id": "aaaaa"
}
}
}
```
Cet endpoint crée uniquement une association entre un Tweet programmé donné et un line item. Une fois que la période de diffusion de la campagne/du line item a commencé, le line item commencera automatiquement à diffuser le Tweet « live » correspondant. Bien que nous vérifiions à cette étape que le Tweet programmé est dans l'état `SCHEDULED`, et que le Tweet programmé donné est valide pour l'objectif donné, aucune autre validation n'est effectuée. Toutes les règles de validation restantes qui s'appliquent au line item et au Tweet programmé sont exécutées lorsque le Tweet passe en « live ».
Afin de s'assurer qu'il n'y a aucun problème de diffusion de la campagne, il est recommandé que le Tweet programmé soit `scheduled_at` à une date/heure antérieure au début de la période de diffusion de la campagne/du line item.
Par exemple, supposons que le Tweet programmé soit défini pour passer en « live » après la date de début de la campagne (et qu'il n'y ait qu'un seul Tweet associé à un seul line item), alors la campagne sera `ACTIVE`. Cependant, étant donné que le Tweet programmé n'est pas encore « live », aucune création ne sera disponible pour la diffusion.
**Gestion des Tweets programmés**
Les autres endpoints permettent aux utilisateurs de l'API de gérer tous leurs Tweets programmés et Tweets promus programmés. Ces API peuvent être utilisées pour renvoyer une liste de tous les Tweets programmés, éventuellement filtrés par un état donné, ainsi que pour rechercher un Tweet programmé donné par son `id`.
#### Que se passe-t-il lorsqu’un Tweet programmé est mis en ligne ?
Lorsqu’un Tweet programmé est sur le point d’être mis en ligne, autrement dit au moment indiqué par `scheduled_at`, les mises à jour suivantes sont effectuées :
* Le Tweet « live » est créé, mais cela peut présenter une latence pouvant aller jusqu’à une seconde
* Le `tweet_id` est ajouté aux entités suivantes :
* Tweet programmé
* Tweet programmé promu
* Une nouvelle entité de Tweet promu est créée
#### Bonnes pratiques
Les bonnes pratiques suivantes sont recommandées lors de la création ou de la promotion de Tweets programmés :
* Assurez-vous que le Tweet est valide au moment de la création du Tweet programmé (par exemple, un Tweet ne peut contenir qu’une image, une vidéo ou un GIF, et non une combinaison des trois)
* Assurez-vous que les dates de diffusion de la campagne (c’est‑à‑dire `start_time` et `end_time`) sont alignées sur l’heure `scheduled_at` du Tweet programmé
* Les Tweets programmés ne doivent pas être planifiés à plus d’un an dans le futur (365 jours)
* L’aperçu de Tweet n’est actuellement pas pris en charge pour les Tweets programmés (il s’agit de la possibilité d’afficher un aperçu des Tweets programmés avant leur création)
### Médiathèque
#### Introduction
Les endpoints de Media Library permettent de gérer les images, les GIFs et les vidéos pour les comptes X Ads. Les ressources média de la bibliothèque peuvent être utilisées dans des Tweets et pour créer des cartes. Elles peuvent également être réutilisées dans plusieurs [éléments créatifs](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/overview), ce qui évite d'avoir à téléverser plusieurs fois le même fichier.
#### Points de terminaison de l’API
* [POST media/upload](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload#post-media-upload) (téléverser des médias) ou [POST media/upload (chunked)](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload-init#post-media-upload-init) (téléverser des médias par segments)
* [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#post-accounts-account-id-media-library) (ajouter des médias à la médiathèque)
#### Ajout à la bibliothèque
L'ajout de médias à la bibliothèque se fait en deux étapes. Tout d'abord, téléversez l'élément en utilisant soit l'endpoint [POST media/upload](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload#post-media-upload), soit la série d'endpoints [POST media/upload (chunked)](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload-init#post-media-upload-init). (Consultez le guide [Téléversement de médias par segments](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/uploading-media/chunked-media-upload) pour plus de détails sur notre processus de téléversement en plusieurs parties.)
```
twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"
```
```json theme={null}
{
"media_id":966947208837742592,
"media_id_string":"966947208837742592",
"size":74194,
"expires_after_secs":86400,
"image":{
"image_type":"image/jpeg",
"w":800,
"h":418
}
}
```
Ensuite, en utilisant l’id du média, ajoutez-le à la bibliothèque du compte publicitaire via le point de terminaison [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#post-accounts-account-id-media-library).
```
twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte"
```
```json theme={null}
{
"request":{
"params":{
"name":"Latte",
"file_name":"latte.jpeg",
"media_category":"TWEET_IMAGE",
"account_id":"18ce54d4x5t",
"media_key":966947208837742592
}
},
"data":{
"tweeted":false,
"name":"Latte",
"file_name":"latte.jpeg",
"media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"media_category":"TWEET_IMAGE",
"media_key":"3_966947208837742592",
"created_at":"2018-02-23T08:05:54Z",
"media_status":"TRANSCODE_COMPLETED",
"media_key":"966947208837742592",
"media_type":"IMAGE",
"updated_at":"2018-02-23T08:06:17Z",
"deleted":false
}
}
```
**Remarque :** Le fait de tweeter des images, des GIF ou des vidéos immédiatement après leur téléversement ajoute également ces médias à la bibliothèque de médias.
#### Paramètres de requête
Toutes les requêtes POST vers la Media Library nécessitent un identifiant de média. Cette valeur est renvoyée lors de l’étape de téléversement. Lors de l’utilisation de `media_id`, comme dans l’exemple ci-dessus, une `media_category` doit également être spécifiée. Il existe quatre valeurs de catégorie possibles : `AMPLIFY_VIDEO`, `TWEET_GIF`, `TWEET_IMAGE` et `TWEET_VIDEO`.
En option, les valeurs `name` et `file_name` peuvent être définies pour les objets de la Media Library. Ces attributs aident les utilisateurs à distinguer les variantes de médias dans la bibliothèque.
Pour les vidéos, il est également possible de définir un titre et une description. Ces valeurs sont destinées à être transmises en tant que paramètres de requête `video_title` et `video_description` avec le point de terminaison [POST accounts/:account\_id/tweet](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet). Dans le Tweet, ce texte apparaît sous la vidéo.
#### Attributs
La Media Library introduit formellement le concept de media\_key. Il s’agit de l’identifiant unique des objets dans la bibliothèque. Les media keys sont des valeurs de type chaîne de caractères au format suivant : 13\_875943225764098048. Elles sont entièrement prises en charge dans tous nos endpoints de cartes.
De plus, la réponse de la Media Library inclut le media\_id, représenté sous forme de chaîne de caractères. Celui-ci est inclus pour les ressources qui n’acceptent pas encore de media key : [Tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet)*, [aperçu de Tweet](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweet-preview)* et [Tweets programmés](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets). Nous travaillons à la prise en charge des media keys partout.
L’attribut aspect\_ratio est renvoyé pour les GIF et les vidéos. Il peut être utilisé pour filtrer les médias à utiliser dans des cartes qui n’acceptent que certains rapports d’aspect spécifiques.
\*Ces endpoints prennent en charge le paramètre video\_id, qui est une media key.
#### Utilisation
Dans cette section, l'image suivante sera utilisée dans un Tweet et pour créer une carte de site web.
```
twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592"
```
```json theme={null}
{
"request":{
"params":{
"account_id":"18ce54d4x5t",
"media_key":"3_966947208837742592"
}
},
"data":{
"tweeted":false,
"name":"Latte",
"file_name":"latte.jpeg",
"media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"media_category":"TWEET_IMAGE",
"media_key":"3_966947208837742592",
"created_at":"2018-02-23T08:05:54Z",
"media_status":"TRANSCODE_COMPLETED",
"media_key":"966947208837742592",
"media_type":"IMAGE",
"updated_at":"2018-02-23T08:06:17Z",
"deleted":false
}
}
```
**Tweet**
Nous pouvons créer le Tweet en faisant référence aux images à l’aide de media\_keys.
```
twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true"
```
```json theme={null}
{
"data":{
"created_at":"Fri Feb 23 08:20:05 +0000 2018",
"id":966950781302665218,
"id_str":"966950781302665218",
"text":"coffee https://t.co/T772Hx5GNT",
"truncated":false,
"entities":{
"hashtags":[
],
"symbols":[
],
"user_mentions":[
],
"urls":[
],
"media":[
{
"id":966947208837742592,
"id_str":"966947208837742592",
"indices":[
7,
30
],
"media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"url":"https://t.co/T772Hx5GNT",
"display_url":"pic.x.com/T772Hx5GNT",
"expanded_url":"https://x.com/apimctestface/status/966950781302665218/photo/1",
"type":"photo",
"sizes":{
"thumb":{
"w":150,
"h":150,
"resize":"crop"
},
"large":{
"w":800,
"h":418,
"resize":"fit"
},
"medium":{
"w":800,
"h":418,
"resize":"fit"
},
"small":{
"w":680,
"h":355,
"resize":"fit"
}
}
}
]
},
"source":"Ads API Internal Test App",
"in_reply_to_status_id":null,
"in_reply_to_status_id_str":null,
"in_reply_to_user_id":null,
"in_reply_to_user_id_str":null,
"in_reply_to_screen_name":null,
"user":{
"id":756201191646691328,
"id_str":"756201191646691328"
},
"geo":null,
"coordinates":null,
"place":null,
"contributors":[
2417045708
],
"retweet_count":0,
"favorite_count":0,
"favorited":false,
"retweeted":false,
"possibly_sensitive":false,
"scopes":{
"followers":false
},
"lang":"en"
},
"request":{
"params":{
"as_user_id":756201191646691328,
"text":"coffee",
"account_id":"18ce54d4x5t",
"media_keys":[
966947208837742592
],
"trim_user":true
}
}
}
```
**Website Card**
Tous nos endpoints de cards prennent en charge les clés media\_key. Nous allons créer la [website card](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/website#post-accounts-account-id-cards-website) en utilisant la clé media\_key de l’image.
```
twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards"
```
```json theme={null}
{
"name": "components create cards",
"components": [
{
"type": "MEDIA",
"media_key": "3_1323490622599176192"
},
{
"type": "BUTTON",
"label": {
"type": "ENUM",
"value": "INSTALL"
},
"destination": {
"type": "APP",
"country_code": "US",
"googleplay_app_id": "com.twitter.android"
}
}
]
}
```
Nous associons ensuite cette card à un Tweet à l’aide de son card\_uri.
### Identification des Cards
#### Introduction
Les Cards sont des formats d’annonce personnalisables qui utilisent des médias et qui peuvent être associées à un site Web, une App ou à des appels à l’action pour générer certains types d’engagements utilisateur, comme l’ouverture d’un Message Direct. Elles peuvent être ajoutées à des Tweets, des Tweets programmés ou des Tweets en brouillon.
Les Cards peuvent être référencées dans les objets Tweet de deux manières : par le `card_uri` de la Card ou par son `preview_url`. Des valeurs d’exemple pour chacune sont présentées ci-dessous.
| card\_uri | preview\_url |
| :------------------------- | :----------------------------------------------------------------------------------------- |
| card://1043282691834048513 | [https://cards.x.com/cards/18ce54d4x5t/68w3s](https://cards.x.com/cards/18ce54d4x5t/68w3s) |
**Remarque** : à partir de la version 3 de l’Ads API, seul le `card_uri` est généré et renvoyé dans la réponse `cards` pour les Cards nouvellement créées.
**Remarque** : à partir de la version 5 de l’Ads API, le `preview_url` n’est plus renvoyé dans la réponse `cards`.
Le type de référence dans la réponse de l’objet Tweet dépendra de la manière dont le Tweet a été créé. En d’autres termes, si le Tweet a été créé à l’aide du paramètre de requête `card_uri`, la valeur de l’URI de la Card apparaîtra dans la réponse. En revanche, si le `preview_url` a été inclus dans le texte du Tweet, l’URL d’aperçu apparaîtra dans la réponse.
#### Identification des Tweets à l'aide de card\_uri
Pour les Tweets créés à partir de la valeur d'URI de la carte, recherchez la référence à cette carte dans l'attribut de réponse card\_uri. L'exemple de réponse ci-dessous utilise le point de terminaison [GET accounts/:account\_id/tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweets).
```
$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
"request": {
"params": {
"tweet_ids": [
"1043551275923591168"
],
"tweet_type": "PUBLISHED",
"trim_user": true,
"account_id": "18ce54d4x5t"
}
},
"next_cursor": null,
"data": [
{
"coordinates": null,
"retweeted": false,
"source": "Ads API Internal Test App",
"entities": {
"hashtags": [],
"symbols": [],
"user_mentions": [],
"urls": []
},
"display_text_range": [
0,
15
],
"favorite_count": 0,
"in_reply_to_status_id_str": null,
"geo": null,
"id_str": "1043551275923591168",
"scopes": {
"followers": false
},
"in_reply_to_user_id": null,
"truncated": false,
"retweet_count": 0,
"scheduled_status": null,
"id": 1043551275923591168,
"in_reply_to_status_id": null,
"nullcast": true,
"created_at": "Sat Sep 22 17:23:07 +0000 2018",
"place": null,
"scheduled_at": null,
"tweet_type": "PUBLISHED",
"favorited": false,
"card_uri": "card://1043282691834048513",
"full_text": "Tracking a card",
"lang": "en",
"contributors": [
2417045708
],
"in_reply_to_screen_name": null,
"in_reply_to_user_id_str": null,
"user": {
"id": 756201191646691328,
"id_str": "756201191646691328"
},
"tweet_id": "1043551275923591168"
}
]
}
```
Si vous utilisez l’API standard, utilisez include\_card\_uri=true dans la requête.
Quel que soit l’endpoint utilisé, l’attribut de réponse card\_uri ne sera présent que si le Tweet a été créé à l’aide d’un URI de carte.
Pour les objets Tweet planifiés et brouillons, la réponse inclura toujours l’attribut de réponse card\_uri.
#### Identification des Tweets avec preview\_url
Pour les Tweets créés en incluant l’URL d’aperçu dans le texte du Tweet, l’URL se trouve dans entities\["urls"]\[i]\["expanded\_url"] (le champ text contient une URL t.co raccourcie), où i est un indice de tableau (un Tweet peut contenir plusieurs URL).
Pour les objets Tweet planifiés ou brouillons, l’URL d’aperçu apparaît toujours dans le champ text.
#### Récupération des cards
Pour récupérer des informations supplémentaires sur une card spécifique, nous fournissons deux endpoints : [GET accounts/:account\_id/cards/all](https://developer.x.com/en/docs/ads/creatives/api-reference/cards-fetch.html#get-accounts-account-id-cards-all) et [GET accounts/:account\_id/cards/all/:card\_id](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/cards-fetch#get-accounts-account-id-cards-all-card-id). Le premier endpoint permet de récupérer une card à partir de son card\_uri et le second à partir de l’ID de la card. L’ID de la card se trouve à la fin du preview\_url. Dans l’exemple ci-dessus, cet ID est 68w3s.
### Identification des médias
#### Introduction
Les médias — images, GIF et vidéos — peuvent être ajoutés aux Tweets et aux cartes. De plus, les vidéos peuvent être utilisées comme ressources pré-roll et les images peuvent être promues sur la [X Audience Platform](https://developer.x.com/en/docs/ads/measurement/overview/twitter-audience-platform). Cette section décrit comment trouver les références de médias au sein de ces entités.
Il existe deux types d'identifiants de média : des ID et des clés. Des exemples de valeurs pour chacun sont présentés ci-dessous.
| **Media ID** | **Media key** |
| :------------------ | :---------------------- |
| 1029825579531807971 | 13\_1029825579531807971 |
La media key correspond à l'ID précédé d'un préfixe numérique et d'un caractère de soulignement.
#### Images
Le tableau suivant indique les types d’identifiants actuellement disponibles dans la réponse de chaque ressource liée aux images, ainsi que le ou les noms d’attributs correspondants.
| **Resource** | **Identifier** | **Attribute(s)** |
| :-------------- | :------------- | :-------------------------------------------------------------- |
| Image cards | None | |
| Tweet | Both | `entities["media"]["id_str"]` `entities["media"]["media_key"]` |
| Scheduled Tweet | Both | `media_ids` and `media_keys` |
| Draft Tweet | Both | `media_ids` and `media_keys` |
| Account Media | None | |
| Media Library | Both | `media_id` and `media_key` |
Les images d’Image cards et d’Account Media ne contiennent aucune référence à un identifiant de média. Les Tweets incluent uniquement des ID de média. Les Scheduled et Draft Tweets incluent à la fois l’ID de média et la clé de média. La Media Library renvoie également les deux.
Pour les Tweets, les champs id et id\_str de l’objet au sein du tableau entities\["media"] correspondent à l’ID du média. Dans les cas où un Tweet inclut plusieurs images, les références à chaque entité média ne se trouvent que dans extended\_entities\["media"].
En plus des références aux identifiants, il est souvent important d’avoir accès à l’URL de l’image.
| **Resource** | **Attribute(s)** | **Format** |
| :-------------- | :---------------------------------------------------------------------------------- | :--------- |
| Image cards | `image` | .jpg |
| Tweet\* | `entities["media"][0]["media_url"]` or `extended_entities["media"][i]["media_url"]` | .jpg |
| Scheduled Tweet | None | |
| Draft Tweet | None | |
| Account Media | `media_url` | .jpg |
| Media Library | `media_url` | .jpg |
* Cet emplacement d’URL dépend du fait que le Tweet contienne une seule image ou plusieurs images.
Toutes les Image cards incluent un attribut de réponse image qui contient l’URL de l’image X. (Pour les image app download cards, le nom est wide\_app\_image.)
Pour les Tweets, l’emplacement de l’URL du média dépend à la fois du type de média et de l’endpoint utilisé. Pour les Tweets contenant une seule image, l’URL se trouve dans entities\["media"]\[0]\["media\_url"]. Cela vaut pour l’Ads API comme pour la Standard API. Lorsque les Tweets contiennent plusieurs images, cependant, les URL ne se trouvent que dans extended\_entities\["media"]\[i]\["media\_url"]. Cela n’est disponible que dans la Standard API.
#### Vidéos
Le tableau suivant indique les types d'identifiants actuellement disponibles dans la réponse de chaque ressource liée à la vidéo, ainsi que le ou les noms d'attributs correspondants.
| **Ressource** | **Identifiant** | **Attribut(s)** |
| :---------------------- | :------------------------ | :-------------------------------------------------------------- |
| Cartes vidéo | Peut être l'un ou l'autre | `video_content_id` |
| Cartes de sondage vidéo | Aucun | |
| Tweet | Les deux | `entities["media"]["id_str"]` `entities["media"]["media_key"]` |
| Tweet planifié | Les deux | `media_ids` et `media_keys` |
| Brouillon de Tweet | Les deux | `media_ids` et `media_keys` |
| Médias du compte | Clé de média | `video_id` |
| Médiathèque | Les deux | `media_id` et `media_key` |
Bien que les cartes vidéo (à l'exception des cartes de sondage avec vidéo) incluent un attribut de réponse `video_content_id`, il existe une incohérence dans le type de valeur renvoyée. Dans certains cas, il s'agit d'un ID de média ; dans d'autres, d'une clé de média.
Les informations sur la façon d'accéder à l'URL de la vidéo sont présentées ci-dessous.
| **Ressource** | **Attribut(s)** | **Format** |
| :----------------- | :------------------------------------------------------------------ | :----------- |
| Cartes vidéo | `video_url` et `video_hls_url` | .vmap .m3u8 |
| Tweet avec vidéo | `extended_entities["media"][i]["video_info"]["variants"][j]["url"]` | .mp4 |
| Tweet planifié | Aucun | |
| Brouillon de Tweet | Aucun | |
| Médias du compte | Aucun | |
| Médiathèque | `media_url` | .mp4 |
Les cartes vidéo incluent les attributs de réponse `video_url` et `video_hls_url` avec, respectivement, des URL en .vmap et .m3u8.
#### Media Library
Il est parfois nécessaire de récupérer des informations supplémentaires sur une ressource média. Un cas d’usage, pour les video cards, consiste à récupérer l’URL mp4 au lieu de l’URL vmap. Ces informations sont disponibles dans la Media Library. Pour plus de détails sur les informations disponibles, consultez notre [guide Media Library](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/guides/media-library). La plupart des ressources appartenant au FULL promotable user du compte publicitaire se trouvent dans la bibliothèque. Il existe toutefois quelques exceptions.
**Récupération des médias**
Comme indiqué ci-dessus, les image cards ne contiennent pas de références ni à des media IDs ni à des media keys. Par conséquent, il n’est pas possible de récupérer leurs ressources via la Media Library. Cela vaut également pour les images [Account Media](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/account-media#account-media).
Les video cards exigent que la ressource vidéo fasse partie de la Media Library (ou de la ressource Videos auparavant) avant leur création. Par conséquent, ces ressources pourront toujours être récupérées dans la Media Library. Cela est également vrai pour les ressources Account Media PREROLL.
Enfin, les médias contenus dans les Tweets sont toujours présents dans la Media Library.
Le tableau suivant récapitule quelles ressources peuvent être récupérées dans la Media Library, en tenant compte du fait que la réponse de la ressource inclut ou non un identifiant à utiliser pour la recherche.
| **Resource** | **Dans la Media Library** |
| :------------------------------- | :------------------------ |
| Image cards | Non |
| Video cards | Oui\* |
| Tweets (tout média)\*\* | Oui |
| Tweets programmés | Oui |
| Tweets brouillons | Oui |
| Images Account Media | Non |
| Vidéos Account Media (`PREROLL`) | Oui |
* Pour les cards où le `video_content_id` est une media key. Lorsque la valeur est un media ID, la ressource existe toujours dans la Media Library, mais sa récupération implique l’ajout d’un préfixe numérique et d’un trait de soulignement.
\*\* Les Tweets ne renvoient que des media IDs. Bien que la ressource soit garantie d’exister dans la Media Library, sa récupération implique l’ajout d’un préfixe numérique et d’un trait de soulignement.
**Interactions avec Account Media**
Il existe deux cas où des ressources média ajoutées à la bibliothèque sont automatiquement ajoutées à la ressource Account Media.
* Lorsqu’une ressource AMPLIFY\_VIDEO est ajoutée à la Media Library, elle est automatiquement ajoutée en tant que ressource Account Media avec un creative type PREROLL.
* Lorsque des images ayant des dimensions spécifiques (voir « Creative Types » sur notre [page des énumérations](https://developer.x.com/content/developer-twitter/en/docs/ads/general/overview/enums)) sont ajoutées à la Media Library, elles sont automatiquement ajoutées en tant que ressources Account Media. Le creative type (par exemple, INTERSTITIAL) dépend des dimensions de l’image.
### Tweets
#### Introduction
L’API X Ads prend en charge trois types de Tweets : publiés, programmés et brouillons.
#### Tweets nullcastés
Les Tweets peuvent être soit nullcastés (également appelés « Promoted-only »), soit organiques. Une fois publiés, les Tweets nullcastés n’apparaissent pas dans la timeline publique de l’utilisateur, même s’ils restent publics. Les Tweets organiques, en revanche, sont diffusés aux abonnés de l’utilisateur et apparaissent dans la timeline publique de celui-ci.
**Création de Tweets**
Chacun des trois endpoints de création de Tweet accepte un paramètre booléen `nullcast` qui permet à l’utilisateur de l’API de créer des Tweets nullcastés ou organiques. Les Tweets nullcastés peuvent être créés par l’utilisateur ou par toute personne disposant de l’autorisation de créer des Tweets pour le compte de cet utilisateur. Les Tweets organiques ne peuvent être créés que par le [full promotable user](https://developer.x.com/content/developer-twitter/en/docs/tutorials/ads-api-hierarchy-terminology#promotable-users).
**Mise à jour des Tweets**
Il est possible de mettre à jour la propriété `nullcast` pour les Tweets programmés et les brouillons de Tweets. Pour les Tweets programmés, des modifications peuvent être apportées jusqu’à l’heure `scheduled_at` du Tweet. Les brouillons de Tweets peuvent être modifiés indéfiniment. Une fois publiés, toutefois, il n’est pas possible de faire passer un Tweet de nullcasté à organique ou inversement.
#### Promotion de Tweets
Seuls les Tweets publiés et programmés peuvent être promus. Ils peuvent être soit en nullcast, soit organiques, sans restriction. Un annonceur peut promouvoir ses propres Tweets ou ceux d'un autre utilisateur, à condition d'avoir obtenu l'autorisation de le faire. (Voir : [Promoting another user's Tweets](https://developer.x.com/content/developer-twitter/en/docs/tutorials/promoting-another-users-content) pour plus d'informations.)
Plusieurs Tweets peuvent être promus dans une seule campagne. De même, un seul Tweet peut être promu dans une ou plusieurs campagnes.
Pour promouvoir des Tweets publiés, utilisez l’endpoint [POST accounts/:account\_id/promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/promoted-tweets#post-accounts-account-id-promoted-tweets). Cela associe les Tweets publiés à un line item. Pour promouvoir des Tweets programmés, utilisez l’endpoint [POST accounts/:account\_id/scheduled\_promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#post-accounts-account-id-scheduled-promoted-tweets).
#### ID de Tweet
Les ID des Tweets publiés, programmés ou en brouillon sont [numériques](https://developer.x.com/content/developer-twitter/en/docs/basics/twitter-ids) : il s’agit d’entiers non signés 64 bits. Par exemple, l’ID du Tweet publié suivant est 1166476031668015104.
Lorsque des Tweets publiés ou programmés sont promus, une entité de Tweet promu correspondante est créée. Ces entités ont leurs propres ID, qui sont alphanumériques et sont représentés sous forme de valeurs encodées en base 36. Par exemple, la promotion du Tweet publié ci‑dessus — c’est‑à‑dire en l’associant au line item 6c62d — renvoie la réponse d’API suivante.
```
$ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104"
{
"request": {
"params": {
"tweet_ids": [
1166476031668015104
],
"line_item_id": "6c62d",
"account_id": "18ce54d4x5t"
}
},
"data": [
{
"line_item_id": "6c62d",
"id": "3qwlq6",
"entity_status": "ACTIVE",
"created_at": "2019-09-12T21:39:10Z",
"updated_at": "2019-09-12T21:39:10Z",
"approval_status": "ACCEPTED",
"tweet_id": "1166476031668015104",
"deleted": false
}
],
"total_count": 1
}
```
En plus de l’ID du Tweet et de l’ID de l’élément de campagne, qui ont été fournis dans la requête de création, la réponse comprend un champ id dont la valeur est 3qw1q6 ; il s’agit de l’ID du Tweet promu.
### Carrousels
#### Introduction
L'API X Ads permet de créer et d'obtenir des carrousels vidéo et des carrousels d'images. Le carrousel est un type de carte qui peut contenir entre 2 et 6 éléments média. La carte carrousel peut diriger un utilisateur vers un site web ou l'inciter à installer une application mobile. Pour plus d'informations sur les carrousels, leurs avantages, les bonnes pratiques et la FAQ, consultez notre page [Carousel Ads on X](https://business.x.com/en/advertising/carousels.html).
Un carrousel, comme tout autre type de carte, peut être utilisé dans des Tweets, et ces Tweets peuvent ensuite être promus. Le flux de travail est le même que celui auquel vous êtes déjà habitué :
1. Téléverser les médias
2. Créer la carte
3. Créer le Tweet
4. Promouvoir le Tweet
La seule différence concerne la façon dont la carte est créée. Alors que les autres requêtes de création de carte acceptent des paramètres de requête, les requêtes de création de carte carrousel acceptent uniquement des corps de requête POST au format JSON.
#### Points de terminaison
L’Ads API permet de créer et de récupérer des carrousels.
Pour créer un carrousel — quel qu’en soit le type — utilisez le point de terminaison [POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards). Pour récupérer des carrousels, utilisez le point de terminaison [GET accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#get-accounts-account-id-cards).
#### Corps de la requête POST JSON
Les carrousels sont créés à l'aide de deux composants. Le premier spécifie les ressources média qui seront utilisées. Le second spécifie des informations à propos du site Web ou de l'application.
Plus précisément, une carte de carrousel est créée en utilisant les composants suivants, dans l'ordre :
* Un composant `SWIPEABLE_MEDIA`, qui accepte un tableau de clés de médias
* *Un* des éléments suivants :
* Un composant `DETAILS` pour spécifier les informations du site Web
* Un composant `BUTTON` pour spécifier les informations de l'application
Le composant `SWIPEABLE_MEDIA` doit inclure un tableau `media_keys` dans lequel vous pouvez spécifier entre 2 et 6 images ou vidéos. L'ordre dans lequel les clés de médias sont transmises détermine l'ordre dans lequel elles seront rendues.
```
{
"type": "SWIPEABLE_MEDIA",
"media_keys": [
"13_1089771253848666112",
"13_1191948012077092867"
]
}
```
Pour rappel, vous pouvez obtenir des clés média en envoyant une requête vers l’endpoint [GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#get-accounts-account-id-media-library).
La composition du deuxième objet composant dépend du fait que vous souhaitiez diriger un utilisateur vers un site web ou l’encourager à installer une app. Le tableau ci-dessous récapitule les deux options. (**Remarque** : toutes les clés répertoriées sont obligatoires.)
| | **Site web** | **App** |
| :----------------------------- | :----------------------------------------------------------------- | :------------------------------------------------ |
| Spécifier le type de composant | `"type": "DETAILS"` | `"type": "BUTTON"` |
| Titre/Libellé | `"title": "X"` | `"label": { "type": "ENUM", "value": "INSTALL" }` |
| Destination | `"destination": { "type": "WEBSITE", "url": "https://www.x.com" }` | `"destination": { "type": "APP", ... }` |
En combinant ces éléments, voici ci-dessous un exemple de corps de requête POST JSON pour un carrousel de site web.
```
{
"name": "website carousel",
"components": [
{
"type": "SWIPEABLE_MEDIA",
"media_keys": [
"13_1089771253848666112",
"13_1191948012077092867"
]
},
{
"type": "DETAILS",
"title": "X",
"destination": {
"type": "WEBSITE",
"url": "https://www.x.com"
}
}
]
}
```
Les objets de destination d’application au sein des composants `BUTTON` nécessitent un code de pays et au moins un identifiant d’app. Ils acceptent éventuellement des liens profonds (deep links). Pour une description de ces champs, consultez la [documentation de référence](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#app-destination).
En combinant ces éléments, voici un exemple de corps de requête JSON POST pour un carrousel d’applications.
```
{
"name": "app carousel",
"components": [
{
"type": "SWIPEABLE_MEDIA",
"media_keys": [
"13_1089771253848666112",
"13_1191948012077092867"
]
},
{
"type": "BUTTON",
"label": {
"type": "ENUM",
"value": "INSTALL"
},
"destination": {
"type": "APP",
"country_code": "US",
"googleplay_app_id": "com.twitter.android",
"iphone_app_id": "333903271"
}
}
]
}
```
#### Exemple
Cette section montre comment créer une carte carrousel vidéo pour site web et comment l’utiliser dans un Tweet. Comme indiqué ci-dessus, le flux de travail est le même que celui auquel vous êtes déjà habitué : téléverser les médias, créer la carte, créer le Tweet. La seule différence réside dans la manière dont la carte est créée.
**Médias**
Pour commencer, téléversez de nouveaux éléments média ou utilisez des éléments existants. Pour plus de détails sur la façon de téléverser de nouveaux éléments média et de les ajouter à la Media Library, consultez notre [guide Media Library](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/media-library).
Une fois vos éléments média présents dans la Media Library, récupérez-les à l’aide de l’endpoint [GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#get-accounts-account-id-media-library). Utilisez le paramètre de requête `media_type` pour restreindre les résultats à un type de média particulier.
```
$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
```
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"media_type": "VIDEO"
}
},
"next_cursor": null,
"data": [
{
"tweeted": true,
"duration": 5283,
"name": "Sunrise",
"file_name": "sunrise.mp4",
"description": null,
"media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9",
"poster_media_key": "3_1089771253848666112",
"media_key": "13_1089771253848666112",
"created_at": "2019-01-28T06:24:48Z",
"media_status": "TRANSCODE_COMPLETED",
"poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg",
"title": null,
"media_type": "VIDEO",
"aspect_ratio": "16:9",
"updated_at": "2019-08-23T19:05:33Z",
"deleted": false
},
{
"tweeted": true,
"duration": 15248,
"name": "snow",
"file_name": "snow.mp4",
"description": "Two, three, and to the four",
"media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13",
"poster_media_key": "3_1191948012077092867",
"media_key": "13_1191948012077092867",
"created_at": "2019-11-06T05:18:46Z",
"media_status": "TRANSCODE_COMPLETED",
"poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg",
"title": "One",
"media_type": "VIDEO",
"aspect_ratio": "16:9",
"updated_at": "2020-03-27T22:23:18Z",
"deleted": false
}
]
}
```
**Création de carrousel**
Utilisez le point de terminaison [POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards) pour créer votre carrousel. Utilisez les clés média de la requête précédente. Gardez à l’esprit que l’ordre dans lequel les clés média sont transmises détermine l’ordre dans lequel elles sont affichées.
```
$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "X","destination":{"type":"WEBSITE", "url":"https://www.x.com"}}]}'
```
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t"
}
},
"data": {
"name": "website carousel",
"components": [
{
"type": "SWIPEABLE_MEDIA",
"media_keys": [
"13_1089771253848666112",
"13_1191948012077092867"
]
},
{
"type": "DETAILS",
"title": "X",
"destination": {
"type": "WEBSITE",
"url": "https://www.x.com/",
"tco_url": "https://t.co/dyTMHWKWZb"
}
}
],
"id": "ars7m",
"created_at": "2020-11-11T07:51:47Z",
"card_uri": "card://1326432421105995776",
"updated_at": "2020-11-11T07:51:47Z",
"deleted": false,
"card_type": "UNIFIED"
}
}
```
Notez que, comme pour les autres cartes, la réponse de la carte carrousel contient un `card_uri`, qui sera utilisé lors de la création d’un Tweet.
**Tweet**
Utilisez le point de terminaison [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweets#post-accounts-account-id-tweet) pour créer votre Tweet. Utilisez le `card_uri` de la requête précédente. (Réponse tronquée afin d’améliorer la lisibilité.)
```
$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792"
```
```
{
"data": {
"created_at": "Wed Nov 11 07:58:27 +0000 2020",
"id": 1326434098324385792,
"id_str": "1326434098324385792",
"text": "Swipe",
"truncated": false,
"entities": {
"hashtags": [],
"symbols": [],
"user_mentions": [],
"urls": []
},
"source": "Ads API Internal Test App",
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 756201191646691300,
"id_str": "756201191646691328",
...
},
"geo": null,
"coordinates": null,
"place": null,
"contributors": [
2417045708
],
"retweet_count": 0,
"favorite_count": 0,
"favorited": false,
"retweeted": false,
"possibly_sensitive": false,
"scopes": {
"followers": false
},
"lang": "en"
},
"request": {
"params": {
"text": "Swipe",
"as_user_id": 756201191646691300,
"card_uri": "card://1326432421105995776",
"account_id": "18ce54d4x5t"
}
}
}
```
**Aperçu du Tweet**
Utilisez l’endpoint [GET accounts/:account\_id/tweet\_previews](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) pour afficher un aperçu de votre Tweet.
### balisage-des-métadonnées-de-création
#### Introduction
Ce guide s’adresse aux partenaires créatifs, aux agences et aux développeurs créatifs pour ajouter des balises aux éléments utilisés dans les campagnes X, afin de mieux comprendre la valeur et les performances de chaque élément.
**Remarque :** les éléments média doivent uniquement être balisés par le partenaire ou le développeur qui crée l’élément. Si l’utilisateur de l’élément média n’en est pas le créateur, n’implémentez pas de balisage de métadonnées.
Le balisage des métadonnées créatives permet d’attribuer les images et les vidéos créées par les Creative Partners, quel que soit l’endroit où l’élément est téléversé sur X ou l’entité qui téléverse l’élément. Pour établir le lien entre l’élément créatif et le Creative Partner, la norme [XMP](https://exiftool.org/TagNames/XMP.html) est utilisée.
#### Marquage des ressources créatives
Le tableau suivant présente les types d’identifiants actuellement disponibles dans la réponse de chaque ressource liée aux images, ainsi que le ou les noms d’attributs correspondants. Un outil de marquage est nécessaire pour marquer les ressources créatives. [ExifTool](https://exiftool.org/), une bibliothèque Perl multiplateforme accompagnée d’une [application en ligne de commande](https://exiftool.org/exiftool_pod.html) pour lire, écrire et modifier les métadonnées, est recommandé. Consultez la liste de tous les [types de fichiers](https://exiftool.org/#supported) pris en charge.
Suivez les [instructions d’installation d’ExifTool](https://exiftool.org/install.html). Des paquets logiciels sont également proposés par [Homebrew](https://formulae.brew.sh/) afin de simplifier davantage l’installation en fournissant la [commande d’installation exiftool](https://formulae.brew.sh/formula/exiftool) pour macOS et Linux. Vérifiez que votre outil est correctement installé en saisissant exiftool -ver dans la ligne de commande pour obtenir le numéro de version de l’outil. Pour en savoir plus sur les paramètres de commande ExifTool, consultez la [documentation ExifTool](https://exiftool.org/).
Les partenaires créatifs peuvent appliquer des balises de métadonnées à des ressources créatives nouvelles ou existantes en indiquant leur X app\_id dans la balise XMP contributor et la balise date. Les ressources créatives respecteront les restrictions de taille existantes lors du [téléversement de médias](https://developer.x.com/en/docs/twitter-api/v1/media/upload-media/overview).
**Remarque :** l’utilisation par X de la balise XMP contributor veille à ce que les métadonnées capturent des valeurs exclusivement pour les campagnes sur X.
`exiftool -contributor="" -creative_file.jpg`
`exiftool -date="" -creative_file.jpg`
L’app\_id peut être trouvé dans la [Console de développement](https://developer.x.com/en/portal/dashboard) sous Projects & Apps. Exemple : 16489123
L’exemple suivant ajoute app\_id en tant que balise contributor et date en tant que balise date pour une image :
```
app_id:858382169
```
```
date:2022-03-13
```
```
creative_file: eiffel_tower.jpg
```
```
exiftool -contributor=858382169 eiffel_tower.jpg
```
```
1 fichier image mis à jour
```
```
exiftool -date=2022-03-13 eiffel_tower.jpg
```
```
1 fichier image mis à jour
```
Vérifiez que votre image a été correctement balisée :
`exiftool -xmp:all -G1 `
Exemple :
`exiftool -xmp:all -G1 eiffel_tower.jpg`
```
[XMP] XMP Toolkit : Image::ExifTool 12.30
```
```
[XMP] Contributor : 858382169
```
```
[XMP] Date : 2022:03:13
```
#### Des questions ?
Si vous souhaitez confirmer que votre marquage et votre attribution sont réussis, veuillez envoyer des exemples de ressources taguées à [adsapi-program@x.com](mailto:adsapi-program@x.com) pour qu’un représentant de X puisse les examiner.
## Référence de l’API
### Médias de compte
#### GET accounts/:account\_id/account\_media
Récupérer les détails de certains ou de l’ensemble des médias du compte associés au compte actuel.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/account_media`
#### Paramètres
| Nom | Description |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| account\_media\_ids *optional* | Restreint la réponse aux seuls médias du compte souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type : string Exemple : `3wpx` |
| count *optional* | Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type : int Valeur par défaut : `200` Min, Max : `1`, `1000` |
| creative\_types *optional* | Restreint la réponse aux seuls médias du compte qui correspondent aux types d’éléments créatifs spécifiés. Plus d’un type d’élément créatif peut être spécifié en séparant les valeurs de l’énumération par des virgules. Type : enum Valeurs possibles : `BANNER`, `BANNER_TABLET`, `INTERSTITIAL`, `INTERSTITIAL_LANDSCAPE`, `INTERSTITIAL_LANDSCAPE_TABLET`, `INTERSTITIAL_TABLET`, `MEDIUM_RECTANGLE`, `PREROLL`, `VAST_PREROLL` |
| cursor *optional* | Spécifie un curseur pour obtenir la page suivante de résultats. Voir [Pagination](https://developer.x.com/x-ads-api/introduction) pour plus d’informations. Type : string Exemple : `8x7v00oow` |
| sort\_by *optional* | Trie selon un attribut pris en charge, dans l’ordre croissant ou décroissant. Voir [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) pour plus d’informations. Type : string Exemple : `created_at-asc` |
| with\_deleted *optional* | Inclut les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| with\_total\_count *optional* | Inclut l’attribut de réponse `total_count`. **Remarque** : Ce paramètre et `cursor` sont exclusifs. **Remarque** : Les requêtes qui incluent `total_count` auront des limites de taux plus basses, actuellement fixées à 200 toutes les 15 minutes. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| Name | Description |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | Identifiant du compte annonceur. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| account\_media\_id *required* | Référence au média de compte que vous utilisez dans la requête. Type : string Exemple : `2pnfd` |
| with\_deleted *optional* | Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
```
{
"request": {
"params": {
"account_media_id": "2pnfd",
"account_id": "18ce54d4x5t"
}
},
"data": {
"video_id": null,
"media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
"creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
"id": "2pnfd",
"created_at": "2017-07-28T01:44:41Z",
"updated_at": "2017-07-28T01:44:41Z",
"deleted": false
}
}
```
Supprimer l’objet média de compte spécifié pour le compte actuel.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id`
#### Parameters
| Name | Description |
| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t` |
| account\_media\_id *obligatoire* | Une référence au média de compte utilisé dans la requête. Type: string Example: `2pnfd` |
**Remarque** : pour associer une carte à un Tweet, utilisez le paramètre `card_uri` avec l’un des endpoints [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets) ou [POST accounts/:account\_id/draft\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/draft-tweets#post-accounts-account-id-draft-tweets).
Récupère les détails de certaines ou de toutes les cartes associées au compte actuel.
**Remarque** : cet endpoint renvoie uniquement les cartes qui ont été créées à l’aide de l’endpoint POST accounts/:account\_id/cards. Les cartes créées à l’aide d’autres endpoints ne sont pas renvoyées.
| Name | Description |
| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | L'identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_types *optional* | Limite la réponse uniquement aux types de cartes souhaités en indiquant une liste de valeurs d'énumération séparées par des virgules. Type : enum Valeurs possibles : `IMAGE_APP`, `IMAGE_CAROUSEL_APP`, `IMAGE_CAROUSEL_WEBSITE`, `IMAGE_MULTI_DEST_CAROUSEL_WEBSITE`, `IMAGE_WEBSITE`, `MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE`, `VIDEO_APP`, `VIDEO_CAROUSEL_APP`, `VIDEO_CAROUSEL_WEBSITE`, `VIDEO_MULTI_DEST_CAROUSEL_WEBSITE`, `VIDEO_WEBSITE` |
| card\_id *optional* | Limite la réponse uniquement aux cartes souhaitées en indiquant une liste d'identifiants séparés par des virgules. Jusqu'à 200 ID de carte peuvent être fournis. Type : string Exemple : `1044294149527166979,1044301099031658496` |
| card\_uris *optional* | Limite la réponse uniquement aux cartes souhaitées en indiquant une liste d'identifiants séparés par des virgules. Jusqu'à 200 valeurs d'URI de carte peuvent être fournies. Type : string Exemple : `card://1044294149527166979,card://1044301099031658496` |
| count *optional* | Spécifie le nombre d'enregistrements à tenter de récupérer par requête distincte. Type : int Valeur par défaut : `100` Min, Max : `1`, `200` |
| cursor *optional* | Spécifie un curseur pour obtenir la page de résultats suivante. Voir [Pagination](https://developer.x.com/x-ads-api/introduction) pour plus d'informations. Type : string Exemple : `8x7v00oow` |
| include\_legacy\_cards *optional* | Inclut les anciennes cartes de site web et d'app dans la réponse. Les anciennes cartes sont celles dont l'URL de ressource a le format suivant : accounts/:account\_id/cards/:card\_type. Voir [ce billet du forum des développeurs](https://devcommunity.x.com/t/new-cards-endpoints-and-carousel-ads/145782/6) pour plus de contexte. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| q *optional* | Requête optionnelle pour limiter les cartes par `name`. Omettez ce paramètre pour tout récupérer. Longueur maximale : 80 caractères. **Remarque** : cette opération effectue une recherche de préfixe insensible à la casse. Type : string Exemple : `dtc` |
| sort\_by *optional* | Trie par un attribut pris en charge, par ordre croissant ou décroissant. Voir [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) pour plus d'informations. Type : string Exemple : `created_at-asc` |
| with\_deleted *optional* | Inclut les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| Nom | Description |
| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | Identifiant du compte à effet de levier. Il apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_id *obligatoire* | L’id des Cards. Type : string Exemple : `1044294149527166979` |
| with\_deleted *facultatif* | Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
Créer une nouvelle carte associée au compte spécifié.
Les requêtes de création de carte n’acceptent que des corps de requête POST au format JSON. Le `Content-Type` doit être défini à `application/json`.
Consultez notre [guide sur les carrousels](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/carousels) pour un exemple d’utilisation détaillé.
Le corps JSON de la requête POST doit contenir un `name` de carte et un tableau de `components`. Les composants sont représentés sous forme d’objets et décrivent les attributs de la carte visibles par l’annonceur.
L’exemple suivant illustre la structure générale du corps de la requête (mais contient des données non valides).
```
{
"name": "some name",
"components": [
{
"type": "TYPE_ENUM",
"key": "value"
}
]
}
```
Informations supplémentaires sur les composants ci-dessous.
| Name | Description |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| name *required* | Le nom de la carte. Longueur maximale : 80 caractères. Type : string Exemple : `component based card` |
| components *sometimes required* | Décrit les composants à utiliser pour créer la carte. Informations supplémentaires ci-dessous. Ne peut pas être utilisé conjointement avec `slides`. **Remarque** : l’ordre des composants est important. Type : tableau d’objets |
| slides *sometimes required* | Utilisez ce tableau de tableaux pour créer des Multi-Destination Carousels. Décrit chaque carte comme un groupe de composants. Chaque slide doit être une représentation complète d’une carte. Ne peut pas être utilisé conjointement avec `components`. **Remarque** : l’ordre de chaque slide est important. Type : tableau de tableaux |
#### Composants
Chaque composant doit inclure un champ `type` qui détermine le schéma de l'objet. L'Ads API prend en charge les types de composants suivants, regroupés en composants basés sur les médias et en composants basés sur la description.
* Média :
* `MEDIA` : une seule vidéo ou image
* `SWIPEABLE_MEDIA` : entre 2 et 6 vidéos ou images
* Description :
* `DETAILS`
* `BUTTON`
Chaque composant possède un ensemble de champs obligatoires (en plus de la clé `type`). Ceux-ci sont répertoriés dans le tableau suivant.
| Component `type` | Field | Value type |
| :---------------- | :---------------------- | :--------------- |
| `MEDIA` | `media_key` | string |
| `SWIPEABLE_MEDIA` | `media_keys` | array of strings |
| `DETAILS` | `title` `destination` | string object |
| `BUTTON` | `label` `destination` | object object |
Voici un exemple de composant `BUTTON` dans le contexte du tableau `components` (en omettant intentionnellement la clé `name`). Les points de suspension indiquent les endroits où il serait nécessaire de spécifier davantage d'informations.
```
{
"components": [
{
"type": "BUTTON",
"label": {
...
},
"destination": {
...
}
}
]
}
```
L’ordre dans lequel les objets de composant sont spécifiés détermine l’ordre d’affichage de haut en bas. Les Cards doivent être créées à l’aide d’un composant basé sur un média et soit d’un composant `DETAILS`, soit d’un composant `BUTTON`. Les composants basés sur une description sont rendus sous le média et ont des destinations associées, soit des URL, soit des applications mobiles.
**Label**
Les libellés définissent le texte affiché sur les boutons et, par conséquent, ne s’appliquent qu’au composant `BUTTON`. Les objets label ont deux clés obligatoires : `type` et `value`. Le `type` doit être défini à `ENUM` et la `value` peut être l’une des valeurs suivantes : `BOOK`, `CONNECT`, `INSTALL`, `OPEN`, `ORDER`, `PLAY` ou `SHOP`.
En reprenant l’exemple précédent, l’exemple suivant illustre l’objet `label` au sein du composant `BUTTON`.
```
{
"components": [
{
"type": "BUTTON",
"label": {
"type": "ENUM",
"value": "INSTALL"
},
"destination": {
...
}
}
]
}
```
**Destination**
Les destinations correspondent à l’endroit où les annonceurs souhaitent amener les utilisateurs. Elles sont toujours requises dans les composants `DETAILS` ou `BUTTON`. Il existe deux types de destinations : `WEBSITE` ou `APP`.
**Remarque** : les destinations de type site web ne peuvent être utilisées qu’avec les composants `DETAILS` et les destinations de type app ne peuvent être utilisées qu’avec les composants `BUTTON`.
**Destination de type site web**
| Name | Description |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| type *required* | Le type de destination, qui détermine son schéma. Type : enum Valeurs possibles : `WEBSITE` |
| url *required* | L’URL du site web vers lequel rediriger un utilisateur. Type : string Exemple : `https://devcommunity.x.com/c/advertiser-api` |
**Destination de type App**
| Name | Description |
| :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| type *required* | Le type de destination, qui détermine son schéma. Type : enum Valeurs possibles : `APP` |
| country\_code *required* | Le code à deux lettres [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) du pays dans lequel l’app est vendue. Type : string Exemple : `US` |
| googleplay\_app\_id *sometimes required* | Le nom de package de l’application Google Play. **Remarque** : au moins l’un des éléments suivants est requis : `ios_app_store_identifier` ou `googleplay_app_id`. Type : string Exemple : `com.twitter.android` |
| ios\_app\_store\_identifier *sometimes required* | L’identifiant de l’App Store iOS. **Remarque** : au moins l’un des éléments suivants est requis : `ios_app_store_identifier` ou `googleplay_app_id`. Type : string Exemple : `333903271` |
| googleplay\_deep\_link *optional* | Un deep link vers l’app Android que vous mettez en avant. **Remarque** : ne peut être utilisé que si un `googleplay_app_id` a été fourni. Type : string |
| ios\_deep\_link *optional* | Un deep link vers l’app iOS que vous mettez en avant. **Remarque** : ne peut être utilisé que si un `ios_app_store_identifier` a été fourni. Type : string |
Le corps JSON de la requête POST doit inclure les paramètres qui seront mis à jour. La requête va **remplacer** chaque champ par les paramètres spécifiés dans le corps de la requête. Les composants sont représentés sous forme d’objets et décrivent les attributs de la carte visibles par les annonceurs.
L’exemple suivant montre la structure générale du corps de la requête (mais contient des informations fictives).
```
{
"name": "some name",
"components": [
{
"type": "TYPE_ENUM",
"key": "value"
}
]
}
```
Informations supplémentaires sur les composants et les diapositives dans **POST accounts/:account\_id/cards**.
| Name | Description |
| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t` |
| name *optional* | Le nom de la carte. Longueur maximale : 80 caractères. Type: string Example: `component based card` |
| components *optional* | Décrit les composants à utiliser pour mettre à jour la carte. Informations supplémentaires ci-dessous. Ne peut pas être spécifié en même temps que `slides`. **Remarque** : l’ordre des composants est important. Type: array of objects |
| slides *optional* | Utilisez ce tableau de tableaux pour mettre à jour les carrousels Multi-Destination. Décrit chaque carte comme un regroupement de composants. Chaque diapositive doit être une représentation complète d’une carte. Ne peut pas être spécifié en même temps que `components`. **Remarque** : l’ordre de chaque diapositive est important. Type: array of array |
#### Exemple de requête
Cet exemple met à jour le nom et supprime l'une des `media_keys` du champ `components` dans l'exemple ci-dessus.
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264`
```
{
"name": "changed name",
"components": [
{
"type": "SWIPEABLE_MEDIA",
"media_keys": [
"3_1075096386931052545"
]
},
{
"type": "BUTTON",
"label": {
"type": "ENUM",
"value": "OPEN"
},
"destination": {
"type": "APP",
"country_code": "US",
"googleplay_app_id": "com.twitter.android",
"googleplay_deep_link": "twitter://user?screen_name=apimctestface"
}
}
]
}
```
| Name | Description |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L’identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_id *obligatoire* | L’id de la carte à supprimer. Type : string Exemple : `1044294149527166979` |
| Nom | Description |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_uris *required* | Restreignez la réponse aux seules cartes souhaitées en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 valeurs d’URI de carte peuvent être fournies. Type : string Exemple : `card://1044294149527166979,card://1044301099031658496` |
| with\_deleted *optional* | Incluez les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| Nom | Description |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *requis* | Identifiant du compte publicitaire. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_id *requis* | Référence à la carte sur laquelle porte la requête. Type : string Exemple : `508pf` |
| with\_deleted *optionnel* | Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| Name | Description |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| count *optionnel* | Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type : int Valeur par défaut : `100` Min, Max : `1`, `200` |
| cursor *optionnel* | Spécifie un curseur pour obtenir la page de résultats suivante. Voir [Pagination](https://developer.x.com/x-ads-api/introduction) pour plus d’informations. Type : string Exemple : `c-jh1g0ryb` |
| user\_id *optionnel* | Spécifie l’utilisateur pour lequel récupérer les Tweets en brouillon. Par défaut, il s’agit de l’utilisateur promouvable `FULL` du compte lorsque ce paramètre n’est pas défini. Type : string Exemple : `756201191646691328` |
`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`
#### Parameters
| Name | Description |
| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Ads, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| draft\_tweet\_id *required* | Une référence au Tweet brouillon que vous utilisez dans la requête. Type : string Exemple : `994788364334325760` |
Créez un brouillon de Tweet pour l'utilisateur promouvable principal du compte (valeur par défaut) ou pour l'utilisateur spécifié dans le paramètre `as_user_id`.
| Name | Description |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| as\_user\_id *required* | L’identifiant utilisateur (user ID) de l’annonceur pour le compte duquel vous publiez le Tweet. L’annonceur doit accorder à votre handle (ou à vos handles) l’accès à son compte publicitaire via [ads.x.com](https://ads.x.com/). Cette autorisation vous permet d’appeler l’API en utilisant les jetons OAuth de votre propre handle plutôt que ceux de l’annonceur. Type : string Exemple : `756201191646691328` |
| text *sometimes required* | Le texte de votre mise à jour de statut. Obligatoire si aucune valeur `media_keys` n’est spécifiée. Type : string Exemple : `Just setting up my X.` |
| card\_uri *optional* | Associez une carte au Tweet en utilisant la valeur `card_uri` renvoyée dans n’importe quelle réponse de carte, si disponible. Type : string Exemple : `card://960880280705392541` |
| media\_keys *optional* | Associez des médias au Tweet en spécifiant une liste d’identifiants séparés par des virgules. Incluez jusqu’à 4 images, 1 GIF animé ou 1 vidéo. **Remarque** : la ressource média doit se trouver dans la [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library) du compte. Type : string Exemple : `13_1153584529292270722` |
| nullcast *optional* | Indique s’il faut créer un Tweet nullcast (ou « Promoted-only »). Type : boolean Valeur par défaut : `true` Valeurs possibles : `true`, `false` |
| name *optional* | Le nom du brouillon de Tweet. Longueur maximale : 80 caractères. Type : string Exemple : `Tweet with name` |
#### Exemple de requête
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.`
#### Exemple de réponse
```
{
"request": {
"params": {
"text": "Just setting up my X.",
"as_user_id": "756201191646691328"
}
},
"data": {
"name": null,
"text": "Just setting up my X.",
"user_id": "756201191646691328",
"id": "994747471329873920",
"nullcast": true,
"created_at": "2018-05-11T01:14:13Z",
"card_uri": null,
"updated_at": "2018-05-11T01:14:13Z",
"media_keys": []
}
}
```
Met à jour le brouillon de Tweet spécifié du compte actuel.
| Nom | Description |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *requis* | L'identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| draft\_tweet\_id *requis* | Une référence au brouillon de Tweet utilisé dans la requête. Type : string Exemple : `994747471329873920` |
| card\_uri *optionnel* | Associez une carte au Tweet en utilisant la valeur `card_uri` provenant de n'importe quelle réponse de carte, si disponible. **Remarque** : réinitialisez (supprimez) le paramètre en le spécifiant sans valeur. Type : string Exemple : `card://970582057284129151` |
| media\_keys *optionnel* | Associez des médias au Tweet en spécifiant une liste d'identifiants séparés par des virgules. Incluez jusqu'à 4 images, 1 GIF animé ou 1 vidéo. **Remarque** : le média doit se trouver dans la [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library) du compte. **Remarque** : réinitialisez (supprimez) le paramètre en le spécifiant sans valeur. Type : string Exemple : `13_1153584529292270722` |
| nullcast *optionnel* | Indique s'il faut créer un Tweet en nullcast (ou « Promoted-only »). Type : boolean Valeurs possibles : `true`, `false` |
| text *optionnel* | Le texte de votre mise à jour de statut. Type : string Exemple : `just setting up my twttr` |
| name *optionnel* | Le nom du brouillon de Tweet. Longueur maximale : 80 caractères. Type : string Exemple : `Tweet with name` |
#### Exemple de requête
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr`
#### Exemple de réponse
```
{
"request": {
"params": {
"draft_tweet_id": 994747471329873920,
"text": "just setting up my twttr"
}
},
"data": {
"name": null,
"text": "just setting up my twttr",
"user_id": "756201191646691328",
"id": "994747471329873920",
"nullcast": true,
"created_at": "2018-05-11T01:14:13Z",
"card_uri": null,
"updated_at": "2018-05-11T01:16:59Z",
"media_keys": []
}
}
```
Supprimer définitivement le brouillon de Tweet spécifié appartenant au compte actuel.
**Remarque** : Nous **recommandons fortement** de supprimer les brouillons une fois qu’un Tweet ou un Tweet planifié a été créé à partir de ses métadonnées.
**Remarque** : Il s’agit d’une suppression définitive. En conséquence, il n’est pas possible de récupérer les brouillons de Tweet supprimés.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`
#### Paramètres
| Nom | Description |
| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L’identifiant du compte annonceur utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’Advertiser API, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| draft\_tweet\_id *obligatoire* | Une référence au Draft Tweet utilisé dans la requête. Type : string Exemple : `994787835663155200` |
#### POST accounts/:account\_id/draft\_tweets/preview/:draft\_tweet\_id
Prévisualiser un Tweet brouillon sur un appareil mobile.
Une requête réussie envoie une notification à chaque appareil sur lequel l’utilisateur authentifié est connecté. En appuyant sur la notification, une timeline s’ouvre et permet à l’utilisateur de voir et d’interagir avec le Tweet brouillon, afin de tester la lecture automatique, le volume, le mode plein écran, l’ancrage de la vidéo dans une Video Website Card, ainsi que d’autres comportements.
**Remarque** : Les aperçus sur l’appareil ne sont visibles que par l’utilisateur qui reçoit la notification.
**Remarque** : Les notifications sont uniquement envoyées aux applications officielles X.
| Nom | Description |
| :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L'identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes Advertiser API, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| draft\_tweet\_id *obligatoire* | Une référence au Tweet en brouillon que vous manipulez dans la requête. Type : string Exemple : `996132315829948416` |
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"draft_tweet_id": "996132315829948416"
}
},
"message": "See @apimctestface's notifications in the X app to preview your Tweet."
}
```
### Cartes de conversation avec image
**Remarque** : pour associer une carte à un Tweet, utilisez le paramètre `card_uri` avec l’un des points de terminaison suivants : [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update) ou [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets).
#### GET accounts/:account\_id/cards/image\_conversation
Récupérer les détails de certaines ou de toutes les cartes de conversation avec image associées au compte actuel.
| Name | Description |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L'identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type: string Exemple : `18ce54d4x5t` |
| card\_ids *optional* | Limite la réponse aux Image Conversation Cards souhaitées en spécifiant une liste d'identifiants séparés par des virgules. Jusqu'à 200 ID peuvent être fournis. Type: string Exemple : `59woh` |
| count *optional* | Spécifie le nombre d'enregistrements à récupérer par requête distincte. Type: int Valeur par défaut : `200` Min, Max : `1`, `1000` |
| cursor *optional* | Spécifie un curseur pour obtenir la page suivante de résultats. Consultez la section [Pagination](https://developer.x.com/x-ads-api/introduction) pour plus d'informations. Type: string Exemple : `8x7v00oow` |
| q *optional* | Requête facultative pour filtrer les cartes par `name`. Omettez ce paramètre pour les récupérer toutes. Longueur maximale : 80 caractères. **Remarque** : cette opération effectue une correspondance de préfixe insensible à la casse. Type: string Exemple : `night` |
| sort\_by *optional* | Trie par attribut pris en charge, dans l'ordre croissant ou décroissant. Consultez la section [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) pour plus d'informations. Type: string Exemple : `created_at-asc` |
| with\_deleted *optional* | Inclut les résultats supprimés dans votre requête. Type: boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| with\_total\_count *optional* | Inclut l'attribut de réponse `total_count`. **Remarque** : ce paramètre et `cursor` sont exclusifs. **Remarque** : les requêtes qui incluent `total_count` auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type: boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| Name | Description |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | L'identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_id *required* | Une référence à la carte de conversation avec image utilisée dans la requête. Type : string Exemple : `59woh` |
| with\_deleted *optional* | Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
#### POST accounts/:account\_id/cards/image\_conversation
Créer une nouvelle carte de conversation d’image associée au compte indiqué.
Consultez [Uploading Media](https://developer.x.com/rest/public/uploading-media) pour plus d’informations sur la mise en ligne d’images sur nos points de terminaison.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`
#### Paramètres
| Name | Description |
| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| first\_cta *required* | Le hashtag d’appel à l’action (CTA) pour la première option. Longueur maximale : 20 caractères (sans compter le #). Type : string Exemple : `#ShareNow` |
| first\_cta\_tweet *required* | Le texte du Tweet à utiliser lorsqu’on clique sur le premier CTA. Type : string Exemple : `I Heart @AdsAPI` |
| media\_key *required* | La clé de média pour une image à utiliser dans cette carte. **Remarque** : l’image doit se trouver dans la [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library) du compte. **Remarque** : une largeur d’image minimale de 800 px et un ratio largeur :hauteur de 1,91:1 est requise. Type : string Exemple : `3_1151345051104991073` |
| name *required* | Le nom de la carte. Type : string Exemple : `image conversation card` |
| thank\_you\_text *required* | Le texte à afficher après le clic sur le CTA. Longueur maximale : 23 caractères. Type : string Exemple : `Thank you` |
| second\_cta *sometimes required* | Le hashtag d’appel à l’action (CTA) pour la deuxième option. Longueur maximale : 20 caractères (sans compter le #). Type : string **Remarque** : requis si `title` n’est `pas` défini. Exemple : `#ShareAgain` |
| second\_cta\_tweet *sometimes required* | Le texte du Tweet à utiliser lorsqu’on clique sur le deuxième CTA. **Remarque** : requis si `second_cta` est défini. Type : string Exemple : `I Heart @AdsAPI Again` |
| title *sometimes required* | Le titre de la carte, qui apparaît sous l’image et au-dessus des CTA. Longueur maximale : 23 caractères. Type : string **Remarque** : requis si `second_cta` n’est `pas` défini. Exemple : `Start a conversation` |
| third\_cta *optional* | Le hashtag d’appel à l’action (CTA) pour la troisième option. Longueur maximale : 20 caractères (sans compter le #). Type : string Exemple : `#ShareMore` |
| third\_cta\_tweet *sometimes required* | Le texte du Tweet à utiliser lorsqu’on clique sur le troisième CTA. Type : string **Remarque** : requis si `third_cta` est défini. Exemple : `I Heart @TwitterDev` |
| fourth\_cta *optional* | Le hashtag d’appel à l’action (CTA) pour la quatrième option. Longueur maximale : 20 caractères (sans compter le #). Type : string Exemple : `#ShareExtra` |
| fourth\_cta\_tweet *sometimes required* | Le texte du Tweet à utiliser lorsqu’on clique sur le quatrième CTA. Type : string **Remarque** : requis si `fourth_cta` est défini. Exemple : `I Heart @TwitterDev Again` |
| unlocked\_image\_media\_key *optional* | Un `media_key` d’une image qui sera utilisée dans le scénario de déverrouillage instantané. Il s’agit d’un champ en écriture seule. Dans la réponse, l’API fournira une URL X pour cette image. **Remarque** : l’image doit se trouver dans la médiathèque du compte. **Remarque** : une largeur d’image minimale de 800 px et un ratio largeur :hauteur de 5:2 est requise. Type : string Exemple : `3_883112887618682880` |
| thank\_you\_url *optional* | L’URL à afficher avec le texte de remerciement. Type : string Exemple : `https://example.com/thankyou` |
| Name | Description |
| :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | Identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte indiqué doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_id *required* | Référence à la carte de conversation avec image que vous utilisez dans la requête. Type : string Exemple : `4i0qg` |
| first\_cta *optional* | Hashtag d'appel à l'action (CTA) pour la première option. Longueur maximale : 20 caractères (sans compter le #). Type : string Exemple : `#ShareNow` |
| first\_cta\_tweet *optional* | Texte du Tweet à utiliser lorsque le premier CTA est cliqué. Type : string Exemple : `I Heart @AdsAPI` |
| second\_cta *optional* | Hashtag d'appel à l'action (CTA) pour la deuxième option. Longueur maximale : 20 caractères (sans compter le #). Type : string **Remarque** : Obligatoire si `title` n'est `pas` défini. Exemple : `#ShareAgain` |
| second\_cta\_tweet *optional* | Texte du Tweet à utiliser lorsque le deuxième CTA est cliqué. **Remarque** : Obligatoire si `second_cta` est défini. Type : string Exemple : `I Heart @AdsAPI Again` |
| third\_cta *optional* | Hashtag d'appel à l'action (CTA) pour la troisième option. Longueur maximale : 20 caractères (sans compter le #). Type : string Exemple : `#ShareMore` |
| third\_cta\_tweet *optional* | Texte du Tweet à utiliser lorsque le troisième CTA est cliqué. Type : string **Remarque** : Obligatoire si `third_cta` est défini. Exemple : `I Heart @TwitterDev` |
| fourth\_cta *optional* | Hashtag d'appel à l'action (CTA) pour la quatrième option. Longueur maximale : 20 caractères (sans compter le #). Type : string Exemple : `#ShareExtra` |
| fourth\_cta\_tweet *optional* | Texte du Tweet à utiliser lorsque le quatrième CTA est cliqué. Type : string **Remarque** : Obligatoire si `fourth_cta` est défini. Exemple : `I Heart @TwitterDev Again` |
| media\_key *optional* | Clé média d'une image à utiliser dans cette carte. **Remarque** : L'image doit se trouver dans la [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library) du compte. **Remarque** : Une largeur d'image minimale de 800 px et un ratio largeur :hauteur de 1,91:1 est requise. Type : string Exemple : `3_1151345051104991073` |
| name *optional* | Nom de la carte. Type : string Exemple : `moon card` |
| thank\_you\_text *optional* | Texte à afficher après le clic sur le CTA. Longueur maximale : 23 caractères. Type : string Exemple : `Thank you` |
| thank\_you\_url *optional* | URL à afficher avec le texte de remerciement. Type : string Exemple : `https://example.com/thankyou` |
| title *optional* | Titre de la carte, qui apparaît sous l'image et au‑dessus des CTA. Longueur maximale : 23 caractères. Type : string **Remarque** : Obligatoire si `second_cta` n'est `pas` défini. Exemple : `Start a conversation` |
| unlocked\_image\_media\_key *optional* | La `media_key` d'une image qui sera utilisée dans le scénario de déverrouillage instantané. Il s'agit d'un champ en écriture seule. Dans la réponse, l'API fournira une URL X pour cette image. **Remarque** : L'image doit se trouver dans la médiathèque du compte. **Remarque** : Une largeur d'image minimale de 800 px et un ratio largeur :hauteur de 5:2 est requise. Type : string Exemple : `3_883112887618682880` |
| Nom | Description |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *requis* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_id *requis* | Une référence à l’Image Conversation Card que vous manipulez dans la requête. Type : string Exemple : `4i0qe` |
| Nom | Description |
| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *requis* | Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes Advertiser API à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| count *optionnel* | Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type : int Valeur par défaut : `20` Min, Max : `1`, `50` |
| cursor *optionnel* | Spécifie un curseur pour obtenir la page suivante de résultats. Voir [Pagination](https://developer.x.com/x-ads-api/introduction) pour plus d’informations. Type : string Exemple : `c-1` |
| media\_type *optionnel* | Limite la réponse au seul type de média souhaité. Type : enum Valeurs possibles : `GIF`, `IMAGE`, `VIDEO` |
| q *optionnel* | Requête facultative permettant de filtrer les ressources par les champs `name`, `title`, `file_name` et `description`. **Remarque** : cette opération effectue une correspondance de *termes* insensible à la casse. Type : string Longueur min, max : `1`, `255` |
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"count": 1
}
},
"data": [
{
"tweeted": true,
"name": null,
"file_name": "coffee https://t.co/4tcPU9XUon",
"media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
"media_category": "TWEET_IMAGE",
"media_key": "3_908573900237180928",
"created_at": "2017-09-15T06:11:12Z",
"media_status": "TRANSCODE_COMPLETED",
"media_type": "IMAGE",
"updated_at": "2017-11-16T06:00:01Z",
"deleted": false
}
],
"next_cursor": "c-1"
}
```
Récupère un objet spécifique de la médiathèque associé au compte actuel.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`
#### Paramètres
| Name | Description |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L’identifiant du compte publicitaire. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| media\_key *obligatoire* | Une référence à l’objet de la médiathèque avec lequel vous interagissez dans la requête. Type : string Exemple : `13_909110614026444802` |
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"media_key": "13_909110614026444802"
}
},
"data": {
"tweeted": true,
"duration": 39973,
"name": null,
"file_name": "buildings https://t.co/xFdzrHM5QG",
"description": null,
"media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
"media_category": "AMPLIFY_VIDEO",
"poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
"poster_media_key": "3_909110614026444802",
"media_key": "13_909110614026444802",
"created_at": "2017-09-16T17:43:55Z",
"media_status": "TRANSCODE_COMPLETED",
"title": "buildings",
"media_type": "VIDEO",
"aspect_ratio": "16:9",
"updated_at": "2017-09-27T13:04:00Z",
"deleted": false
}
}
```
Associer un objet média au compte actuel. Pour plus de détails, consultez notre [guide Media Library](https://developer.x.com/en/docs/ads/creatives/guides/media-library).
**Remarque** : lorsque vous ajoutez à la Media Library une vidéo dont la catégorie de média est `AMPLIFY_VIDEO`, elle devient automatiquement disponible en tant que ressource [account\_media](https://developer.x.com/en/docs/ads/creatives/api-reference/account-media#get-accounts-account-id-account-media) `PREROLL`.
| Name | Description |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Example : `18ce54d4x5t` |
| media\_key *required* | Le `media_key` du contenu téléversé. Un `media_key` est renvoyé dans la réponse de POST media/upload lorsqu’une `media_category` est spécifiée. Type : string Example : `3_931236738554519552` |
| description *optional* | La description qui apparaît sous la vidéo lorsqu’elle est publiée dans un Tweet. Longueur maximale : 200 caractères. Elle n’est pas affichée dans le Tweet par défaut. Pour afficher la `description` de la vidéo, utilisez le paramètre `video_description` avec le point de terminaison [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet). **Remarque** : ne peut être utilisée qu’avec des vidéos. Type : string Example : `Ceci est la description sous la vidéo.` |
| file\_name *optional* | Le nom de fichier de l’objet de la médiathèque. Longueur maximale : 255. Le nom de fichier peut être consulté dans les détails de chaque élément média dans l’interface Media Library sur ads.x.com. Ce champ sera vide lorsque `file_name` n’est pas défini. Type : string Example : `coffee.jpeg` |
| name *optional* | Le nom de l’objet de la médiathèque. Longueur maximale : 100. Il s’agit du libellé affiché sous chaque élément média dans l’interface Media Library sur ads.x.com. Le libellé sera « Untitled » lorsque `name` n’est pas défini. Type : string Example : `Latte` |
| poster\_media\_key *optional* | Spécifiez une image d’aperçu pour la vidéo en utilisant le `media_key` d’une image téléversée. Si ce paramètre n’est pas spécifié, la première image de la vidéo sera utilisée. **Remarque** : ne peut être utilisée qu’avec des vidéos. Type : string Example : `3_890599134483242005` |
| title *optional* | Le titre (accroche) qui apparaît sous la vidéo lorsqu’elle est publiée dans un Tweet. Longueur maximale : 70 caractères. Ce titre n’est pas affiché dans le Tweet par défaut. Pour afficher le `title` de la vidéo, utilisez le paramètre `video_title` avec le point de terminaison [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet). **Remarque** : ne peut être utilisé qu’avec des vidéos. Type : string Example : `Video title` |
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"media_key": "3_931236738554519552"
}
},
"data": {
"tweeted": false,
"name": null,
"file_name": null,
"media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
"media_category": "TWEET_IMAGE",
"media_key": "3_931236738554519552",
"created_at": "2017-11-16T19:05:14Z",
"media_status": "TRANSCODE_COMPLETED",
"media_type": "IMAGE",
"updated_at": "2017-11-16T19:05:23Z",
"deleted": false
}
}
```
Met à jour l’objet de médiathèque spécifié appartenant au compte actuel.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`
#### Paramètres
| Nom | Description |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | L'identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| media\_key *required* | Une référence à l'objet de la médiathèque que vous utilisez dans la requête. Type : string Exemple : `16_844800354743074820` |
| description *optional* | La description qui apparaît sous la vidéo lorsqu'elle est publiée dans un Tweet. Longueur maximale : 200 caractères. Elle n’est pas affichée dans le Tweet par défaut. Pour afficher la `description` de la vidéo, utilisez le paramètre `video_description` avec le point de terminaison [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet). **Remarque** : ne peut être utilisé qu'avec des vidéos. Type : string Exemple : `Ceci est la description sous la vidéo.` |
| file\_name *optional* | Le nom de fichier de l'objet de la médiathèque. Longueur maximale : 255. Le nom de fichier est visible dans les détails de chaque élément média dans l'interface Media Library sur ads.x.com. Ce champ sera vide lorsque `file_name` n'est pas défini. Type : string Exemple : `coffee.jpeg` |
| name *optional* | Le nom de l'objet de la médiathèque. Longueur maximale : 100. Il s'agit du libellé sous chaque élément média dans l'interface Media Library sur ads.x.com. Le libellé sera « Untitled » lorsque `name` n'est pas défini. Type : string Exemple : `Latte` |
| poster\_media\_key *optional* | Spécifiez une image d’aperçu (poster) pour la vidéo en utilisant le `media_key` d'une image déjà mise en ligne. **Remarque** : ne peut être utilisé qu'avec des vidéos. Type : string Exemple : `3_885003359340375465` |
| title *optional* | Le titre (accroche) qui apparaît sous la vidéo lorsqu'elle est publiée dans un Tweet. Longueur maximale : 70 caractères. Il n’est pas affiché dans le Tweet par défaut. Pour afficher le `title` de la vidéo, utilisez le paramètre `video_title` avec le point de terminaison [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet). **Remarque** : ne peut être utilisé qu'avec des vidéos. Type : string Exemple : `Titre de la vidéo` |
| Nom | Description |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L’identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| media\_key *obligatoire* | Une référence à l’objet de la médiathèque que vous utilisez dans la requête. Type : string Exemple : `7_860318603387600896` |
Récupérer les détails de certaines ou de toutes les cartes de sondage associées au compte en cours.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/cards/poll`
#### Paramètres
| Name | Description |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t` |
| card\_ids *optional* | Limite la réponse aux seules cartes de sondage souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Example: `57i77` |
| count *optional* | Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | Spécifie un curseur pour obtenir la page de résultats suivante. Voir [Pagination](https://developer.x.com/x-ads-api/introduction) pour plus d’informations. Type: string Example: `8x7v00oow` |
| q *optional* | Requête facultative pour filtrer les cartes en fonction de `name`. Omettez ce paramètre pour les récupérer toutes. Longueur maximale : 80 caractères. **Note** : cette opération effectue une correspondance de préfixe insensible à la casse. Type: string Example: `night` |
| sort\_by *optional* | Trie selon un attribut pris en charge, dans l’ordre croissant ou décroissant. Voir [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) pour plus d’informations. Type: string Example: `created_at-asc` |
| with\_deleted *optional* | Inclut les résultats supprimés dans votre requête. Type: boolean Default: `false` Possible values: `true`, `false` |
| with\_total\_count *optional* | Inclut l’attribut de réponse `total_count`. **Note** : ce paramètre et `cursor` sont mutuellement exclusifs. **Note** : les requêtes qui incluent `total_count` auront des limites de taux plus faibles, actuellement définies à 200 toutes les 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` |
| Nom | Description |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *requis* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_id *requis* | Une référence à la carte de sondage sur laquelle porte la requête. Type : string Exemple : `57i8t` |
| with\_deleted *optionnel* | Inclure les résultats supprimés dans votre requête. Type : boolean Par défaut : `false` Valeurs possibles : `true`, `false` |
Crée une nouvelle carte de sondage associée au compte spécifié. Ce point de terminaison permet de créer des cartes de sondage avec une image, une vidéo ou sans média. Les sondages avec média sont appelés Media Forward Polls.
**Remarque** : Le produit Media Forward Polls est en version bêta et nécessite la fonctionnalité de compte `PROMOTED_MEDIA_POLLS`.
**Remarque** : Il n’est pas possible de mettre à jour des cartes de sondage via PUT.
| Nom | Description |
| :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| duration\_in\_minutes *required* | La durée (en minutes) pendant laquelle le sondage restera ouvert. Après la `duration_in_minutes` spécifiée, le sondage sera fermé et les votes ne seront plus acceptés. Cela correspond à `end_time` dans la réponse. **Remarque** : cela commence dès que la carte est créée et non lorsqu’elle est ajoutée à un Tweet. Type : int Min, Max : `5`, `10080` |
| first\_choice *required* | Le premier choix du sondage. Longueur maximale : 25 caractères. Type : string Exemple : `One` |
| name *required* | Le nom de la carte. Type : string Exemple : `poll card` |
| second\_choice *required* | Le deuxième choix du sondage. Longueur maximale : 25 caractères. Type : string Exemple : `Two` |
| fourth\_choice *optional* | Le quatrième choix du sondage. Longueur maximale : 25 caractères. **Remarque** : les premier, deuxième et troisième choix doivent être définis lorsque vous utilisez ce paramètre. Type : string Exemple : `Four` |
| media\_key *optional* | Le `media_key` d’une image ou d’une vidéo de la médiathèque qui sera utilisée dans cette carte. Ce champ est en écriture seule. Dans la réponse, l’API fournira une URL X pour ce média. **Remarque** : l’image ou la vidéo doit se trouver dans la médiathèque du compte. **Remarque** : une largeur d’image minimale de 800 px et un rapport largeur/hauteur de 1,91:1 sont requis. |
| third\_choice *optional* | Le troisième choix du sondage. Longueur maximale : 25 caractères. **Remarque** : les premier et deuxième choix doivent être définis lorsque vous utilisez ce paramètre. Type : string Exemple : `Three` |
```
{
"request": {
"params": {
"first_choice": "East",
"name": "best coast poll",
"second_choice": "West",
"media_key": "13_950589518557540353",
"duration_in_minutes": 10080
}
},
"data": {
"video_poster_height": "9",
"name": "best coast poll",
"start_time": "2018-01-09T04:51:34Z",
"first_choice": "East",
"video_height": "9",
"video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
"content_duration_seconds": "8",
"second_choice": "West",
"end_time": "2018-01-16T04:51:34Z",
"id": "57i77",
"video_width": "16",
"video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
"created_at": "2018-01-09T04:51:34Z",
"duration_in_minutes": "10080",
"card_uri": "card://950590850777497601",
"updated_at": "2018-01-09T04:51:34Z",
"video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
"video_poster_width": "16",
"deleted": false,
"card_type": "VIDEO_POLLS"
}
}
```
Supprimer définitivement la carte de sondage spécifiée appartenant au compte actuel.
Remarque : il s’agit d’une suppression définitive. Par conséquent, il sera impossible de récupérer les cartes supprimées.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id`
#### Paramètres
| Nom | Description |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L'identifiant du compte à effet de levier. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Ads pour les annonceurs, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| card\_id *obligatoire* | Une référence à la carte de sondage que vous utilisez dans la requête. Type : string Exemple : `57i9t` |
| Name | Description |
| :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L'identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type: string Example: `18ce54d4x5t` |
| line\_item\_ids *optional* | Limite la réponse aux seuls CTA preroll associés aux line items spécifiés en indiquant une liste d'identifiants séparés par des virgules. Jusqu'à 200 ID peuvent être fournis. Type: string Example: `8v53k` |
| count *optional* | Spécifie le nombre d'enregistrements à récupérer par requête distincte. Type: int Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | Spécifie un curseur pour obtenir la page suivante de résultats. Consultez la section [Pagination](https://developer.x.com/x-ads-api/introduction) pour plus d'informations. Type: string Example: `8x7v00oow` |
| preroll\_call\_to\_action\_ids *optional* | Limite la réponse aux seuls CTA preroll souhaités en indiquant une liste d'identifiants séparés par des virgules. Jusqu'à 200 ID peuvent être fournis. Type: string Example: `8f0` |
| sort\_by *optional* | Trie selon un attribut pris en charge, dans l'ordre croissant ou décroissant. Consultez la section [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) pour plus d'informations. Type: string Example: `created_at-asc` |
| with\_deleted *optional* | Inclut les résultats supprimés dans votre requête. Type: boolean Default: `false` Possible values: `true`, `false` |
| with\_total\_count *optional* | Inclut l'attribut de réponse `total_count`. **Remarque** : ce paramètre et `cursor` sont exclusifs. **Remarque** : les requêtes qui incluent `total_count` auront des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` |
| Name | Description |
| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | Identifiant du compte annonceur utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| preroll\_call\_to\_action\_id *obligatoire* | Référence au preroll call to action que vous utilisez dans la requête. Type : string Exemple : `8f0` |
| with\_deleted *optionnel* | Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
| Nom | Description |
| :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | L'identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes vers l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| call\_to\_action *obligatoire* | Le texte d'appel à l'action (CTA) du bouton affiché dans la publicité. Type : enum Valeurs possibles : `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW` |
| call\_to\_action\_url *obligatoire* | L'URL vers laquelle l'utilisateur est redirigé lorsqu'il clique sur le bouton CTA. Type : string Exemple : `https://www.x.com` |
| line\_item\_id *obligatoire* | Une référence au line item avec lequel vous opérez dans la requête. Type : string Exemple : `8v53k` |
| Nom | Description |
| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *obligatoire* | L'identifiant du compte utilisé. Apparaît dans le chemin d'accès de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| preroll\_call\_to\_action\_id *obligatoire* | Une référence au CTA preroll utilisé dans la requête. Type : string Exemple : `8f0` |
| call\_to\_action *optionnel* | Le texte du CTA pour le bouton affiché dans l’annonce. Type : enum Valeurs possibles : `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW` |
| call\_to\_action\_url *optionnel* | L’URL vers laquelle rediriger l'utilisateur lorsque l’utilisateur clique sur le bouton CTA. Type : string Exemple : `https://www.x.com` |
| Name | Description |
| :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t` |
| preroll\_call\_to\_action\_id *required* | Une référence au CTA preroll avec lequel vous opérez dans la requête. Type: string Example: `8f0` |
| Name | Description |
| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| count *optional* | Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type : int Valeur par défaut : `100` Min, Max : `1`, `200` |
| cursor *optional* | Spécifie un curseur pour obtenir la page de résultats suivante. Voir [Pagination](https://developer.x.com/x-ads-api/introduction) pour plus d’informations. Type : string Exemple : `c-j3cn6n40` |
| user\_id *optional* | Spécifie l’utilisateur pour lequel récupérer les Tweets programmés. Par défaut, il s’agit de l’utilisateur promouvable `FULL` du compte lorsqu’il n’est pas défini. Type : long Exemple : `756201191646691328` |
| Nom | Description |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *requis* | L'identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API Advertiser, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| scheduled\_tweet\_id *requis* | Une référence au Tweet programmé sur lequel porte la requête. Type : string Exemple : `917438609065623552` |
Créez un Tweet programmé pour l’utilisateur promouvable principal du compte (par défaut) ou pour l’utilisateur spécifié dans le paramètre `as_user_id`.
#### URL de ressource
`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets`
#### Paramètres
| Name | Description |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| scheduled\_at *required* | Heure, exprimée au format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), à laquelle le Tweet doit être publié (ou mis en ligne). **Remarque** : les Tweets ne peuvent être planifiés que jusqu’à un an à l’avance. **Remarque** : les Tweets doivent uniquement être planifiés à la minute près ; les secondes seront ignorées. Type : string Exemple : `2017-12-31T23:59:00Z` |
| as\_user\_id *required* | L’ID de l’annonceur pour le compte duquel vous publiez le Tweet. L’annonceur doit accorder à votre handle (ou à vos handles) l’accès à son compte publicitaire via [ads.x.com](https://ads.x.com/). Cette autorisation vous permet d’appeler l’API en utilisant les jetons OAuth de votre propre handle plutôt que ceux de l’annonceur. Type : long Exemple : `756201191646691328` |
| text *sometimes required* | Le texte de votre mise à jour de statut. Obligatoire si aucun `media_keys` n’est spécifié. Type : string Exemple : `just setting up my twttr` |
| card\_uri *optional* | Associez une carte au Tweet en utilisant la valeur `card_uri` de n’importe quelle réponse de cartes, si disponible. Type : string Exemple : `card://855591459410511943` |
| media\_keys *optional* | Associez des médias au Tweet en spécifiant une liste d’identifiants séparés par des virgules. Incluez jusqu’à 4 images, 1 GIF animé ou 1 vidéo. **Remarque** : la ressource média doit se trouver dans la [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library) du compte. Type : string Exemple : `13_1153584529292270722` |
| nullcast *optional* | Indique s’il faut créer un Tweet nullcasté (ou « Promoted-only »). Type : boolean Valeur par défaut : `true` Valeurs possibles : `true`, `false` |
| name *optional* | Le nom du Tweet planifié. Longueur maximale : 80 caractères. Type : string Exemple : `Tweet with name` |
| Nom | Description |
| :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L'identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l'API pour les annonceurs, à l'exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l'utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| scheduled\_tweet\_id *required* | Une référence au Tweet programmé concerné par la requête. Type : string Exemple : `870321875435442177` |
| card\_uri *optional* | Associez une carte au Tweet en utilisant la valeur `card_uri` provenant de n'importe quelle réponse de cartes, si disponible. **Remarque** : annulez (supprimez) l'association en spécifiant le paramètre sans valeur. Type : string Exemple : `card://875146925316386347` |
| media\_keys *optional* | Associez des médias au Tweet en spécifiant une liste d'identifiants séparés par des virgules. Incluez jusqu'à 4 images, 1 GIF animé ou 1 vidéo. **Remarque** : l'élément média doit se trouver dans la [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library) du compte. **Remarque** : annulez (supprimez) l'association en spécifiant le paramètre sans valeur. Type : string Exemple : `13_1153584529292270722` |
| nullcast *optional* | Indique s'il faut créer un Tweet en nullcast (ou « Promoted-only »). Type : boolean Valeurs possibles : `true`, `false` |
| scheduled\_at *optional* | L'heure, exprimée au format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), à laquelle le Tweet doit être publié (ou mis en ligne). Type : string Exemple : `2017-12-31T23:59:59Z` |
| text *optional* | Le texte de votre mise à jour de statut. Type : string Exemple : `just setting up my twttr` |
| name *optional* | Le nom du Tweet programmé. Longueur maximale : 80 caractères. Type : string Exemple : `Tweet nommé` |
| Name | Description |
| :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *obligatoire* | Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| scheduled\_tweet\_id *obligatoire* | Référence au Tweet programmé concerné par la requête. Type : string Exemple : `870321875435442177` |
Prévisualise les Tweets publiés, programmés ou en brouillon.
* Permet de prévisualiser *plusieurs* Tweets — jusqu’à 200 — dans une seule requête API
* Rendu précis et à jour de la mise en page et du style des Tweets
* Prend en charge les formats et types de cartes les plus récents
* Retourne un iframe
| Nom | Description |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes vers l’API Advertiser, à l’exception de [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t` |
| tweet\_ids *required* | Une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. **Remarque** : les identifiants doivent correspondre au `tweet_type` spécifié. Par exemple, si l’identifiant d’un Tweet programmé est transmis et que `tweet_type=PUBLISHED` est spécifié, aucun aperçu ne sera renvoyé pour cet identifiant. Type : long Exemple : `1122911801354510336,1102836745790316550` |
| tweet\_type *required* | Le type de Tweet pour les `tweet_ids` spécifiés. Type : enum Valeurs possibles : `DRAFT`, `PUBLISHED`, `SCHEDULED` |