모범 사례

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

​

유의사항

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

​

미디어 카테고리

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

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

• tweet_image
• tweet_video
• tweet_gif
• dm_image
• dm_video
• dm_gif
• subtitles

Ads API 파트너인 경우, 프로모션용 동영상에 권장되는 미디어 카테고리에 대한 자세한 내용은 이 문서를 참고하세요.

​

이미지 사양 및 권장 사항

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

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

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

​

애니메이션 GIF 권장 사항

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

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

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

​

비디오 사양 및 권장사항

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

​

권장 설정

• 비디오 코덱: 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 (정사각형)

​

고급

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

​

추가 정보

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

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

미디어 업로드 예시는 청크 단위 미디어 업로드 문서를 참고하세요.

​

문제 해결

Media API 관련 문제가 있는 경우, 개발자 포럼의 Media API 카테고리에서 해결 방법을 찾아보세요.