POST /2/media/upload エンドポイントを使用する際に理解しておくべき重要な概念がいくつかあります。OAuth を使ってメディアをアップロードするのは少し複雑なため、注意点とともに、このエンドポイントの使い方の実用的なサンプルをここにまとめています。
留意点
- Post には最大 4 枚の写真、1 枚のアニメーション GIF、または 1 本の動画を添付できます。
- 渡す画像は raw バイナリまたは base64 エンコードされたバイナリである必要があります。Content-Type が適切に設定されていれば、それ以外のエンコードやエスケープは不要です（不明な場合は
application/octet-streamを指定してください）。 - base64 エンコードされた画像を POST する場合は、メッセージの画像パートに “Content-Transfer-Encoding: base64” を設定してください。
- Multi-part メッセージの境界は独立した行に置き、CRLF で終了する必要があります。
- このエンドポイントで POST を行う動作例については、xurl でのテストを推奨します。また、利用可能な X Libraries も参照してください。
- JavaScript など、long integer を正確に表現できない言語では、API レスポンスに含まれる
media_id_stringを使用してください。
メディアカテゴリ
Media Category パラメータは、アップロードするメディアファイルのユースケースを定義するもので、メディアアップロードで適用されるファイルサイズ制限やその他の制約に影響します。メディアを使用する際の問題を避けるため、アップロード時に正しい media category を使うことが重要です。これはアップロードフローの一部として INIT リクエストで渡すオプションの値です。media category が指定されない場合、アップロードされたメディアは Post 用（tweet_image、tweet_video、または tweet_gif）と見なされ、コンテンツタイプに応じて判定されます。
最もよく使われる media category は以下のとおりです。
tweet_imagetweet_videotweet_gifdm_imagedm_videodm_gifsubtitles
画像の仕様と推奨事項
画像ファイルは以下の条件をすべて満たす必要があります。- 対応する画像メディアタイプ:
JPG、PNG、GIF、WEBP - 画像サイズ:
<= 5 MB - アニメーション GIF サイズ:
<= 15 MB
media_id を使用して Post 作成（または類似の）エンドポイントを呼び出す際に適用される、プロダクトエンティティ固有のファイルサイズ制限が別途存在します。ファイルサイズ制限やその他の制約は、media_category パラメータによって異なる場合があります。
アニメーション GIF の推奨事項
ファイルサイズの上限内でも、Post 作成時に GIF が失敗する可能性があります。成功率を高めるため、以下の制約に従ってください。- 解像度:
<= 1280x1080（widthxheight） - フレーム数:
<= 350 - ピクセル数:
<= 300 million（width*height*num_frames） - ファイルサイズ:
<= 15Mb
media_category パラメータを指定した chunked upload エンドポイントを使用してください。これにより、大きなファイル処理に必要な非同期処理をサーバー側で行えます。アニメーション GIF を含む Post の非同期アップロード動作を有効にするには media_category=tweet_gif を渡してください。
動画の仕様と推奨事項
メディアアップロードには Async Path を使用してください。推奨
- Video Codec:
H264 High Profile - フレームレート:
30 FPS、60 FPS - 動画解像度:
1280x720（横向き）、720x1280（縦向き）、720x720（正方形）。Subscribed ユーザーは 1080p の動画をアップロードして 1080p 再生を利用できます。Unsubscribed ユーザーは 720p 動画をアップロードして 720p 再生を利用できます。 - 最小ビデオビットレート:
5,000 kbps - 最小オーディオビットレート:
128 kbps - Audio Codec:
AAC LC - アスペクト比:
16:9（横向きまたは縦向き）、1:1（正方形）
詳細
- フレームレート:
60 FPS以下 - サイズ:
32x32から1280x1024の範囲 - ファイルサイズ:
512 mb以下 - 長さ:
0.5 secondsから140 secondsの範囲 - アスペクト比:
1:3から3:1の範囲 - Pixel aspect ratio:
1:1である必要があります - Pixel format: YUV 4:2:0 のみ対応
- Audio は
AACwith Low Complexity profile である必要があります。（High-EfficiencyAACは非対応） - Audio は
monoまたはstereoである必要があり、5.1 以上は不可 open GOPを使用してはいけませんprogressive scanを使用する必要があります
追加情報
以下の表の各行はアップロードの推奨事項であり、要件ではありません。すべてのアップロードは複数プラットフォームでの最適化のために処理されます。
メディアアップロードの例については、chunked media upload documentation を参照してください。