> ## 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.

# oEmbed API

> oEmbed API는 [oEmbed](http://oembed.com/) 호환 형식으로 간단한 임베드용 HTML을 반환합니다.

oEmbed API를 사용하면 [Tweets](https://developer.x.com/en/docs/twitter-for-websites/embedded-tweets/overview) 및 [timelines](https://developer.x.com/en/docs/twitter-for-websites/timelines/overview)와 같은 임베드 콘텐츠를 프로그래밍 방식으로 가져올 수 있습니다. 

oEmbed API의 응답은 [페이지에 X 위젯 JavaScript를 포함](https://developer.x.com/web/javascript/loading)하면 자동으로 인식되는 HTML 스니펫을 반환합니다.

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

<Tabs>
  <Tab title="임베디드 타임라인">
    반환된 HTML 스니펫은 페이지에 [X의 위젯 JavaScript가 포함되어 있으면](https://developer.x.com/web/javascript/loading) [임베디드 타임라인](https://developer.x.com/en/docs/twitter-for-websites/timelines/overview)으로 자동 인식됩니다.

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

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

    ## Resource URL

    *[https://publish.x.com/oembed](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)<br /> \*[https://x.com/TwitterDev/lists/national-parks](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 [언어 코드](/ko/en/docs/twitter-for-websites/twitter-for-websites-supported-languages/overview "Twitter language code")                                                                                                                                                      | es                                                                                                                                                               |
    | theme        | `dark`로 설정하면, 타임라인이 어두운 배경에 밝은 텍스트로 표시됩니다                                                                                                                                                                                                                                       | dark                                                                                                                                                             |
    | chrome       | 공백으로 구분된 토큰을 사용해 타임라인 표시 구성 요소를 제거합니다<br /><br />\*   noheader - 헤더를 숨깁니다<br />\*   nofooter - (표시 중인 경우) 푸터를 숨깁니다<br />\*   noborders - 위젯 테두리, Tweet 간 테두리, Tweet 내부 테두리를 모두 제거합니다<br />\*   noscrollbar - (표시 중인 경우) 타임라인 스크롤바를 잘라내고 숨깁니다<br />\*   transparent - 배경색을 제거합니다 | noheader%20nofooter                                                                                                                                              |
    | aria\_polite | 타임라인에 추가되는 Tweet에 대해 단언적인 [ARIA 라이브 영역 politeness](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live) 값을 설정합니다                                                                                                                                                     | assertive                                                                                                                                                        |
    | dnt          | `true`로 설정하면, 타임라인 및 사용자의 사이트에 임베드된 해당 페이지는 [맞춤형 추천](https://support.x.com/articles/20169421) 및 [맞춤형 광고](https://support.x.com/articles/20170405)를 포함한 목적에 사용되지 않습니다                                                                                                            | true                                                                                                                                                             |

    ## Example Requests

    ```bash theme={null}
    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"
    ```

    ## 예제 응답

    ```json theme={null}

    {
      "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"
    }
    ```
  </Tab>

  <Tab title="임베디드 Tweet">
    반환된 HTML 스니펫은 [X의 위젯 JavaScript가 페이지에 포함](https://developer.x.com/web/javascript/loading)되어 있으면 자동으로 [임베디드 Tweet](https://developer.x.com/web/embedded-tweets)으로 인식됩니다.

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

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

    ## 리소스 URL

    *[https://publish.x.com/oembed](https://publish.x.com/oembed)*

    ## 리소스 정보

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

    ## 매개변수

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

    ## 요청 예시

    ```bash theme={null}
    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"
    ```

    ## 응답 예시

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>
</Tabs>