API oEmbed

L’API oEmbed renvoie un HTML d’intégration simple dans un format compatible oEmbed.

Vous pouvez utiliser l’API oEmbed pour renvoyer de manière programmatique du contenu intégré, comme des Tweets et des chronologies. 

La réponse de l’API oEmbed contiendra un extrait de code HTML qui sera automatiquement reconnu lorsque le JavaScript des widgets X est inclus dans la page.

Veuillez noter que l’API est recommandée pour effectuer des opérations en masse, et nous vous conseillons d’utiliser notre outil robuste publish.x.com pour intégrer du contenu.

Timelines intégrées

L’extrait HTML renvoyé sera automatiquement reconnu comme une timeline intégrée lorsque le JavaScript de widget de X est inclus dans la page.

Le endpoint oEmbed permet de personnaliser l’apparence finale d’une timeline intégrée en définissant les propriétés correspondantes dans le balisage HTML, qui seront interprétées par le JavaScript de X fourni par défaut avec la réponse HTML. Le format du balisage renvoyé peut évoluer au fil du temps, à mesure que X ajoute de nouvelles fonctionnalités ou ajuste la représentation de la timeline.

Pour une timeline X spécifiée par l’URL de la timeline, dans un format JSON compatible oEmbed. Les timelines utilisateur et de Liste sont prises en charge. Le balisage de la timeline est destiné à être mis en cache sur vos serveurs pendant au plus la durée de mise en cache recommandée, indiquée par la propriété cache_age.

URL de la ressource

https://publish.x.com/oembed

Informations sur la ressource

Formats de réponse	JSON
Nécessite une authentification ?	Non
Soumis à une limitation de débit	Non

Paramètres

Nom	Description	Exemple
url	L’URL de la timeline X à intégrer	* https://x.com/TwitterDev *https://x.com/TwitterDev/lists/national-parks
limit	Affiche jusqu’à N éléments, où N est une valeur comprise entre 1 et 20 inclus	6
maxwidth	Définit la largeur maximale du widget. Doit être comprise entre 180 et 1200 inclus	300
maxheight	Définit la hauteur maximale du widget. Doit être supérieure à 200	400
omit_script	N’inclut pas d’élément script dans la réponse	1
lang	Un code de langue X pris en charge (language code)	es
theme	Lorsqu’il est défini sur dark, la timeline est affichée avec un texte clair sur un arrière-plan sombre	dark
chrome	Supprime des composants d’affichage de la timeline à l’aide de jetons séparés par des espaces * noheader - masque l’en-tête * nofooter - masque le pied de page, s’il est visible * noborders - supprime toutes les bordures : autour du widget, entre les Tweets et à l’intérieur d’un Tweet * noscrollbar - rogne et masque la barre de défilement de la timeline, si elle est visible * transparent - supprime la couleur d’arrière-plan	noheader%20nofooter
aria_polite	Définit, pour les Tweets ajoutés à une timeline, une valeur ARIA live region politeness assertive	assertive
dnt	Lorsqu’il est défini sur true, la timeline et sa page intégrée sur votre site ne sont pas utilisées à des fins incluant les suggestions personnalisées et les publicités personnalisées	true

Exemples de requêtes

curl --request GET --url 'https://publish.x.com/oembed?url=https%3A%2F%2Ftwitter.com%2FInterior%2Fstatus%2F507185938620219395'
twurl -H publish.x.com "/oembed?url=https://x.com/Interior/status/463440424141459456"

Exemple de réponse

{
  "url": "https://x.com/TwitterDev",
  "title": "",
  "html": "<a class=\"twitter-timeline\" href=\"https://x.com/TwitterDev\">Tweets by TwitterDev</a>\n<script async src=\"//platform.x.com/widgets.js\" charset=\"utf-8\"></script>",
  "width": null,
  "height": null,
  "type": "rich",
  "cache_age": "3153600000",
  "provider_name": "Twitter",
  "provider_url": "https://x.com",
  "version": "1.0"
}

Tweets intégrés

L’extrait HTML renvoyé sera automatiquement reconnu comme un Tweet intégré lorsque le JavaScript du widget de X est inclus sur la page.

Le point de terminaison oEmbed permet de personnaliser l’apparence finale d’un Tweet intégré en définissant les propriétés correspondantes dans le balisage HTML à interpréter par le JavaScript de X, fourni par défaut avec la réponse HTML. Le format du balisage renvoyé peut évoluer au fil du temps à mesure que X ajoute de nouvelles fonctionnalités ou ajuste sa représentation des Tweets.

Le balisage de secours du Tweet doit être mis en cache sur vos serveurs pour une durée maximale correspondant à la durée de vie du cache suggérée, spécifiée par la propriété cache_age.

URL de ressource

https://publish.x.com/oembed

Informations sur la ressource

Formats de réponse	JSON
Authentification requise ?	Non
Soumis à une limitation de débit ?	Non

Paramètres

Nom	Valeur par défaut	Description
urlrequis String		URL du Tweet à intégrer
maxwidth Int [220..550]	325	La largeur maximale, en pixels entiers, d’un Tweet rendu. Une valeur fournie en dessous ou au-dessus de la plage autorisée sera renvoyée comme largeur minimale ou maximale prise en charge, respectivement ; la valeur de largeur ajustée sera reflétée dans la propriété width renvoyée. Notez que X ne prend pas en charge le paramètre oEmbed maxheight. Les Tweets sont fondamentalement du texte et ont donc une hauteur imprévisible qui ne peut pas être mise à l’échelle comme une image ou une vidéo. Par conséquent, la réponse oEmbed ne fournira pas de valeur pour height. Les implémentations qui nécessitent des hauteurs constantes pour les Tweets doivent se référer aux paramètres hide_thread et hide_media ci‑dessous.
hide_media Boolean, String ou Int	false	Lorsque la valeur est true, "t" ou 1, les liens dans un Tweet ne sont pas affichés sous forme d’aperçus de photos, de vidéos ou de liens.
hide_thread Boolean, String ou Int	false	Lorsqu’il est défini sur true, "t" ou 1, la version réduite du Tweet précédent dans un fil de conversation n’est pas affichée lorsque le Tweet demandé est une réponse à un autre Tweet.
omit_script booléen, chaîne ou entier	false	Lorsque ce paramètre est défini sur true, "t" ou 1, le <script> responsable du chargement de widgets.js ne sera pas renvoyé. Vos pages Web doivent inclure leur propre référence à widgets.js pour pouvoir l’utiliser avec l’ensemble des widgets X, y compris les Tweets intégrés.
align Enum {left,right,center,none}	none	Indique si le Tweet intégré doit être aligné à gauche, à droite ou centré par rapport à son élément parent.
lang Enum(Language)	en	Renvoie du HTML et un Tweet rendu dans la langue X prise en charge pour les Tweets intégrés spécifiée.
theme Enum {light, dark}	light	Lorsque ce paramètre est défini sur dark, le Tweet est affiché avec un texte clair sur un arrière-plan sombre.
dnt booléen	false	Lorsqu’il est défini sur true, le Tweet et sa page intégrée sur votre site ne sont pas utilisés à des fins telles que les suggestions personnalisées et les publicités personnalisées.

Exemples de requêtes

curl --request GET --url 'https://publish.x.com/oembed?url=https%3A%2F%2Ftwitter.com%2Ftwiterdev'
twurl -H publish.x.com "/oembed?url=https://x.com/TwitterDev"

Exemple de réponse

{
  "url": "https:\/\/twitter.com\/Interior\/status\/463440424141459456",
  "author_name": "US Department of the Interior",
  "author_url": "https:\/\/twitter.com\/Interior",
  "html": "<blockquote class=\"twitter-tweet\"><p lang=\"en\" dir=\"ltr\">Sunsets don&#39;t get much better than this one over <a href=\"https:\/\/twitter.com\/GrandTetonNPS?ref_src=twsrc%5Etfw\">@GrandTetonNPS<\/a>. <a href=\"https:\/\/twitter.com\/hashtag\/nature?src=hash&amp;ref_src=twsrc%5Etfw\">#nature<\/a> <a href=\"https:\/\/twitter.com\/hashtag\/sunset?src=hash&amp;ref_src=twsrc%5Etfw\">#sunset<\/a> <a href=\"http:\/\/t.co\/YuKy2rcjyU\">pic.x.com\/YuKy2rcjyU<\/a><\/p>&mdash; US Department of the Interior (@Interior) <a href=\"https:\/\/twitter.com\/Interior\/status\/463440424141459456?ref_src=twsrc%5Etfw\">May 5, 2014<\/a><\/blockquote>\n<script async src=\"https:\/\/platform.x.com\/widgets.js\" charset=\"utf-8\"><\/script>\n",
  "width": 550,
  "height": null,
  "type": "rich",
  "cache_age": "3153600000",
  "provider_name": "Twitter",
  "provider_url": "https:\/\/twitter.com",
  "version": "1.0"
}