oEmbed API

oEmbed API는 oEmbed 호환 형식으로 간단한 임베드용 HTML을 반환합니다.

oEmbed API를 사용하면 Tweets 및 timelines와 같은 임베드 콘텐츠를 프로그래밍 방식으로 가져올 수 있습니다. 

oEmbed API의 응답은 페이지에 X 위젯 JavaScript를 포함하면 자동으로 인식되는 HTML 스니펫을 반환합니다.

이 API는 대량 작업을 일괄 처리할 때 사용하는 것을 권장하며, 일반적인 콘텐츠 임베딩에는 강력한 publish.x.com 도구를 사용하시기를 권장합니다.

임베디드 타임라인

반환된 HTML 스니펫은 페이지에 X의 위젯 JavaScript가 포함되어 있으면 임베디드 타임라인으로 자동 인식됩니다.

oEmbed 엔드포인트는 HTML 응답에 기본으로 번들되어 제공되는 X의 JavaScript가 해석할 수 있도록 HTML 마크업 내 해당 속성들을 설정함으로써 임베디드 타임라인의 최종 표시 형태를 사용자 지정할 수 있게 해 줍니다. 반환되는 마크업 형식은 X가 새로운 기능을 추가하거나 타임라인 표현을 조정함에 따라 시간이 지나면서 변경될 수 있습니다.

타임라인 URL로 지정된 X 타임라인을 oEmbed 호환 JSON 형식으로 제공합니다. 사용자 타임라인과 리스트 타임라인이 지원됩니다. 타임라인 마크업은 cache_age 속성에 지정된 권장 캐시 수명까지 사용자의 서버에 캐시하여 사용하는 것을 목적으로 합니다.

Resource URL

https://publish.x.com/oembed

Resource Information

Response formats	JSON
Requires authentication?	No
Rate limited	No

Parameters

Name	Description	Example
url	임베드할 X 타임라인의 URL	* https://x.com/TwitterDev *https://x.com/TwitterDev/lists/national-parks
limit	표시할 항목 수 N(1 이상 20 이하의 값)을 지정합니다	6
maxwidth	위젯의 최대 너비를 설정합니다. 180 이상 1200 이하의 값이어야 합니다	300
maxheight	위젯의 최대 높이를 설정합니다. 200보다 커야 합니다	400
omit_script	응답에 script 요소를 포함하지 않습니다	1
lang	지원되는 X 언어 코드	es
theme	dark로 설정하면, 타임라인이 어두운 배경에 밝은 텍스트로 표시됩니다	dark
chrome	공백으로 구분된 토큰을 사용해 타임라인 표시 구성 요소를 제거합니다 * noheader - 헤더를 숨깁니다 * nofooter - (표시 중인 경우) 푸터를 숨깁니다 * noborders - 위젯 테두리, Tweet 간 테두리, Tweet 내부 테두리를 모두 제거합니다 * noscrollbar - (표시 중인 경우) 타임라인 스크롤바를 잘라내고 숨깁니다 * transparent - 배경색을 제거합니다	noheader%20nofooter
aria_polite	타임라인에 추가되는 Tweet에 대해 단언적인 ARIA 라이브 영역 politeness 값을 설정합니다	assertive
dnt	true로 설정하면, 타임라인 및 사용자의 사이트에 임베드된 해당 페이지는 맞춤형 추천 및 맞춤형 광고를 포함한 목적에 사용되지 않습니다	true

Example Requests

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"

예제 응답

{
  "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"
}

임베디드 Tweet

반환된 HTML 스니펫은 X의 위젯 JavaScript가 페이지에 포함되어 있으면 자동으로 임베디드 Tweet으로 인식됩니다.

oEmbed 엔드포인트를 사용하면 HTML 마크업에서 해당 속성을 설정하여 임베디드 Tweet의 최종 표시 형태를 사용자 지정할 수 있으며, 이러한 속성은 기본적으로 HTML 응답과 함께 번들로 제공되는 X의 JavaScript에 의해 해석됩니다. 반환되는 마크업의 형식은 X가 새로운 기능을 추가하거나 Tweet 표현 방식을 조정함에 따라 시간이 지남에 따라 변경될 수 있습니다.

Tweet 대체 마크업은 cache_age 속성으로 지정된 권장 캐시 수명 동안 서버에 캐시해야 합니다.

리소스 URL

https://publish.x.com/oembed

리소스 정보

응답 형식	JSON
인증 필요 여부	아니요
요청 레이트 리밋 적용 여부	아니요

매개변수

이름	기본값	설명
url 필수 문자열		임베드할 Tweet의 URL
maxwidth Int [220..550]	325	렌더링된 Tweet의 정수 픽셀 단위 최대 너비입니다. 허용 범위보다 작거나 큰 값을 제공하면 각각 지원되는 최소 또는 최대 너비로 조정되어 반환되며, 조정된 너비 값은 반환되는 width 속성에 반영됩니다. 참고로 X는 oEmbed maxheight 매개변수를 지원하지 않습니다. Tweet은 근본적으로 텍스트이므로, 이미지나 비디오처럼 스케일링할 수 없는 예측 불가능한 높이를 갖습니다. 이와 관련하여 oEmbed 응답은 height 값도 제공하지 않습니다. Tweet에 대해 일정한 높이가 필요한 구현에서는 아래의 hide_thread 및 hide_media 매개변수를 참고해야 합니다.
hide_media 불리언, 문자열 또는 정수	false	true, "t", 또는 1로 설정하면 Tweet에 포함된 링크가 사진, 동영상 또는 링크 미리보기로 확장되지 않습니다.
hide_thread Boolean, String 또는 Int	false	true, "t", 또는 1로 설정하면, 요청된 Tweet이 다른 Tweet에 대한 답글인 경우 대화 스레드에서 이전 Tweet의 접힌 버전은 표시되지 않습니다.
omit_script Boolean, String 또는 Int	false	true, "t" 또는 1로 설정하면 widgets.js를 로드하는 <script> 태그는 반환되지 않습니다. 모든 X 위젯(예: Embedded Tweets)에서 사용할 수 있도록 웹 페이지에는 widgets.js에 대한 참조를 직접 포함해야 합니다.
align Enum {left,right,center,none}	none	임베드된 Tweet이 상위 요소를 기준으로 페이지에서 왼쪽, 오른쪽 또는 가운데로 정렬될지 여부를 지정합니다.
lang Enum(Language)	en	요청은 지정한 임베드된 Tweet에서 지원되는 X 언어로 된 HTML과 렌더링된 Tweet을 반환합니다.
theme 열거형 {light, dark}	light	dark로 설정하면 Tweet이 어두운 배경 위에 밝은 색의 텍스트로 표시됩니다.
dnt 부울(Boolean)	false	true로 설정하면 Tweet과 사이트에 임베드된 해당 페이지는 맞춤형 추천 및 맞춤형 광고 등과 같은 목적으로 사용되지 않습니다.

요청 예시

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"

응답 예시

{
  "url": "https:\/\/twitter.com\/Interior\/status\/463440424141459456",
  "author_name": "미국 내무부",
  "author_url": "https:\/\/twitter.com\/Interior",
  "html": "<blockquote class=\"twitter-tweet\"><p lang=\"en\" dir=\"ltr\"><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; 미국 내무부 (@Interior) <a href=\"https:\/\/twitter.com\/Interior\/status\/463440424141459456?ref_src=twsrc%5Etfw\">2014년 5월 5일<\/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": "X",
  "provider_url": "https:\/\/twitter.com",
  "version": "1.0"
}