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

# 모범 사례

[`POST /2/media/upload`](/ko/x-api/media/media-upload) 엔드포인트를 사용할 때 알아두어야 할 몇 가지 중요한 개념이 있습니다. OAuth를 사용한 미디어 업로드는 다소 까다로울 수 있으므로, 이 엔드포인트를 사용할 때 유의해야 할 사항과 함께 동작 예제를 아래에 정리했습니다.

<div id="keep-in-mind">
  ## 유의사항
</div>

* 하나의 게시물에는 최대 사진 4장, 애니메이션 GIF 1개 또는 동영상 1개를 첨부할 수 있습니다.
* 전달되는 이미지는 이미지의 원시 바이너리 데이터이거나 base64로 인코딩된 바이너리여야 하며, `Content-Type`이 적절하게 설정되어 있는 한 별도의 인코딩이나 이스케이프 처리는 필요하지 않습니다(확실하지 않은 경우: `application/octet-stream` 사용).
* base64로 인코딩된 이미지를 게시할 때는, 메시지의 이미지 부분에 `Content-Transfer-Encoding: base64` 헤더를 반드시 설정해야 합니다.
* 멀티파트 메시지의 boundary는 반드시 한 줄에 단독으로 위치해야 하며, CRLF로 종료되어야 합니다.
* 이 엔드포인트를 사용해 POST 요청을 보내는 작동 예제를 보려면, [xurl](https://github.com/xdevplatform/xurl)로 테스트해 보기를 권장합니다. 또한 제공되는 [X 라이브러리](/ko/resources/tools-and-libraries)도 살펴보세요.
* JavaScript 및 긴 정수를 정확하게 표현할 수 없는 기타 언어의 경우, API 응답에 제공되는 `media_id_string`을 사용하세요.

<div id="media-categories">
  ## 미디어 카테고리
</div>

Media Category 매개변수는 업로드할 미디어 파일의 사용 사례를 정의하며, 업로드 시 적용되는 파일 크기 제한이나 기타 제약 사항에 영향을 줄 수 있습니다. 미디어를 사용하려 할 때 문제가 발생하지 않도록, 미디어를 업로드할 때 올바른 미디어 카테고리를 사용하는 것이 중요합니다. 이 값은 업로드 흐름에서 INIT 요청에 함께 전달하는 선택적 값입니다. 미디어 카테고리를 지정하지 않으면, 업로드된 미디어는 콘텐츠 유형에 따라 게시물용 미디어(`tweet_image`, `tweet_video`, `tweet_gif`)로 간주됩니다.

가장 일반적인 미디어 카테고리는 다음과 같습니다:

* `tweet_image`
* `tweet_video`
* `tweet_gif`
* `dm_image`
* `dm_video`
* `dm_gif`
* `subtitles`

Ads API 파트너인 경우, 프로모션용 동영상에 권장되는 미디어 카테고리에 대한 자세한 내용은 [이 문서](/ko/x-ads-api/creatives#promoted-video)를 참고하세요.

<div id="image-specifications-and-recommendations">
  ## 이미지 사양 및 권장 사항
</div>

이미지 파일은 다음 모든 기준을 충족해야 합니다:

* **지원되는 이미지 미디어 type**: `JPG`, `PNG`, `GIF`, `WEBP`
* **이미지 크기**: `<= 5 MB`
* **애니메이션 GIF 크기**: `<= 15 MB`

위의 파일 크기 제한은 미디어 업로드 엔드포인트에서 적용됩니다. 추가로, `media_id`와 함께 게시물 생성(또는 이와 유사한) 엔드포인트를 호출할 때 적용되는, 개별 제품 엔티티에 대한 별도의 파일 크기 제한이 있습니다. 파일 크기 제한 및 기타 제약 조건은 `media_category` 매개변수에 따라 달라질 수 있습니다.

<div id="animated-gif-recommendations">
  ## 애니메이션 GIF 권장 사항
</div>

파일 크기 제한을 충족하더라도 게시물 생성 중에 GIF 업로드가 실패할 수 있습니다. 성공률을 높이려면 다음 제약 조건을 준수하세요.

* **해상도**: `<= 1280x1080` (`width` x `height`)
* **프레임 수**: `<= 350`
* **픽셀 수**: `<= 3억` (`width` \* `height` \* `num_frames`)
* **파일 크기**: `<= 15Mb`

더 큰 GIF를 처리하려면 `media_category` 매개변수와 함께 [청크 업로드](/ko/x-api/media/quickstart/media-upload-chunked) 엔드포인트를 사용하세요. 이를 통해 서버가 GIF 파일을 비동기적으로 처리할 수 있으며, 이는 대용량 파일을 처리하기 위한 필수 조건입니다. 애니메이션 GIF가 포함된 게시물에 대해 비동기 업로드 동작을 활성화하려면 `media_category=tweet_gif`를 지정하세요.

<div id="video-specifications-and-recommendations">
  ## 비디오 사양 및 권장사항
</div>

미디어 업로드에는 Async Path를 사용해 주세요.

<div id="recommended">
  ### 권장 설정
</div>

* **비디오 코덱**: `H264 High Profile`
* **프레임 레이트**: `30 FPS`, `60 FPS`
* **비디오 해상도**: `1280x720` (가로), `720x1280` (세로), `720x720` (정사각형). 구독 중인 사용자는 1080p 비디오를 업로드하면 1080p로 재생됩니다. 구독하지 않은 사용자는 720p 비디오를 업로드하면 720p로 재생됩니다.
* **최소 비디오 비트레이트**: `5,000 kbps`
* **최소 오디오 비트레이트**: `128 kbps`
* **오디오 코덱**: `AAC LC`
* **가로세로 비율**: `16:9` (가로 또는 세로), `1:1` (정사각형)

<div id="advanced">
  ### 고급
</div>

* **프레임 속도**: `60 FPS` 이하여야 합니다
* **해상도**: `32x32`에서 `1280x1024` 사이여야 합니다
* **파일 크기**: `512 MB`를 초과해서는 안 됩니다
* **재생 시간**: `0.5초`에서 `140초` 사이여야 합니다
* **종횡비(Aspect ratio)**: `1:3`에서 `3:1` 사이여야 합니다
* **[픽셀 종횡비(Pixel aspect ratio)](https://en.wikipedia.org/wiki/Pixel_aspect_ratio)**: `1:1`이어야 합니다
* **픽셀 포맷**: [YUV](https://en.wikipedia.org/wiki/YUV) 4:2:0만 지원됩니다
* 오디오는 [`AAC` Low Complexity 프로필](https://en.wikipedia.org/wiki/Advanced_Audio_Coding#Modular_encoding)을 사용해야 합니다. (High-Efficiency `AAC`는 지원되지 않습니다)
* 오디오는 `mono` 또는 `stereo`여야 하며, 5.1 이상은 지원되지 않습니다
* [`open GOP`](https://en.wikipedia.org/wiki/Group_of_pictures)를 사용하면 안 됩니다
* [`progressive scan`](https://en.wikipedia.org/wiki/Progressive_scan)을 사용해야 합니다

<div id="additional-information">
  ### 추가 정보
</div>

아래 표의 각 행은 업로드를 위한 권장값이지만, 반드시 따라야 하는 필수 조건은 아닙니다. 모든 업로드는 여러 플랫폼에서의 최적화를 위해 처리됩니다.

| Orientation | Width | Height | Video Bitrate | Audio Bitrate |
| :---------- | :---- | :----- | :------------ | :------------ |
| Landscape   | 1280  | 720    | 2048K         | 128K          |
| Landscape   | 640   | 360    | 768K          | 64K           |
| Landscape   | 320   | 180    | 256K          | 64K           |
| Portrait    | 720   | 1280   | 2048K         | 128K          |
| Portrait    | 360   | 640    | 768K          | 64K           |
| Portrait    | 180   | 320    | 256K          | 64K           |
| Square      | 720   | 720    | 2048K         | 128K          |
| Square      | 480   | 480    | 768K          | 64K           |
| Square      | 240   | 240    | 256K          | 32K           |

미디어 업로드 예시는 [청크 단위 미디어 업로드 문서](/ko/x-api/media/quickstart/media-upload-chunked)를 참고하세요.

<div id="troubleshooting">
  ### 문제 해결
</div>

Media API 관련 문제가 있는 경우, 개발자 포럼의 [Media API 카테고리](https://devcommunity.x.com/c/x-api/media-apis)에서 해결 방법을 찾아보세요.