메인 콘텐츠로 건너뛰기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 Libraries도 참고하세요.
- 긴 정수를 정확히 표현할 수 없는 JavaScript 및 기타 언어에서는 API 응답에 제공되는
media_id_string을 사용하세요.
Media Category 매개변수는 업로드할 미디어 파일의 사용 사례를 정의하며, 미디어 업로드에 적용되는 파일 크기 제한 또는 기타 제약에 영향을 줄 수 있습니다. 미디어를 사용할 때 문제가 발생하지 않도록 올바른 미디어 카테고리를 사용하는 것이 중요합니다. 이는 업로드 플로우에서 INIT 요청에 포함되어 전달되는 선택적 값입니다. 미디어 카테고리가 지정되지 않은 경우 업로드된 미디어는 콘텐츠 유형에 따라 게시물용 미디어(tweet_image, tweet_video, 또는 tweet_gif)로 간주됩니다.
가장 일반적인 미디어 카테고리는 다음과 같습니다:
tweet_imagetweet_videotweet_gifdm_imagedm_videodm_giftweet_image
Ads API 파트너인 경우 프로모션 비디오에 권장되는 미디어 카테고리에 대한 자세한 내용은 이 문서를 참조하세요.
이미지 파일은 다음 모든 기준을 충족해야 합니다:
- 지원되는 이미지 미디어 유형:
JPG, PNG, GIF, WEBP
- 이미지 크기:
<= 5 MB
- 애니메이션 GIF 크기:
<= 15 MB
위의 파일 크기 제한은 미디어 업로드 엔드포인트에서 적용됩니다. 또한 media_id와 함께 게시물 생성(또는 유사한) 엔드포인트를 호출할 때 적용되는 제품 엔터티별 파일 크기 제한이 별도로 있습니다. 파일 크기 제한 및 기타 제약은 media_category 매개변수에 따라 달라질 수 있습니다.
파일 크기 제한을 충족하더라도 게시물 생성 중 GIF 업로드가 실패할 수 있습니다. 성공률을 높이려면 다음 제한 사항을 준수하세요.
- 해상도:
<= 1280x1080 (width x height)
- 프레임 수:
<= 350
- 픽셀 수:
<= 300 million (width * height * num_frames)
- 파일 크기:
<= 15Mb
더 큰 GIF를 처리하려면 media_category 매개변수와 함께 chunked upload 엔드포인트를 사용하세요. 이렇게 하면 서버가 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초 이하여야 합니다
- 가로세로비:
1:3 이상 3:1 이하여야 합니다
- 픽셀 가로세로비:
1:1이어야 합니다
- 픽셀 포맷: YUV 4:2:0만 지원됩니다
- 오디오는 Low Complexity 프로파일의
AAC이어야 합니다. (High-Efficiency AAC는 지원되지 않습니다)
- 오디오는
모노 또는 스테레오여야 하며, 5.1 이상은 불가합니다
open GOP를 사용하면 안 됩니다progressive scan을 사용해야 합니다
아래 표의 각 행은 업로드 권장 사항이며, 필수 요건은 아닙니다. 모든 업로드는 여러 플랫폼에서 최적화되도록 처리됩니다.
| 방향 | 너비 | 높이 | 비디오 비트레이트 | 오디오 비트레이트 |
|---|
| 가로 | 1280 | 720 | 2048K | 128K |
| 가로 | 640 | 360 | 768K | 64K |
| 가로 | 320 | 180 | 256K | 64K |
| 세로 | 720 | 1280 | 2048K | 128K |
| 세로 | 360 | 640 | 768K | 64K |
| 세로 | 180 | 320 | 256K | 64K |
| 정사각형 | 720 | 720 | 2048K | 128K |
| 정사각형 | 480 | 480 | 768K | 64K |
| 정사각형 | 240 | 240 | 256K | 32K |
