> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ベストプラクティス

> POST /2/media/upload エンドポイントを使用する際の重要な概念とベストプラクティス。quickstart をカバーする X API v2 standard tier のリファレンスです。

[`POST /2/media/upload`](/x-api/media/upload-media) エンドポイントを使用する際に理解しておくべき重要な概念がいくつかあります。OAuth を使ってメディアをアップロードするのは少し複雑なため、注意点とともに、このエンドポイントの使い方の実用的なサンプルをここにまとめています。

## 留意点

* Post には最大 4 枚の写真、1 枚のアニメーション GIF、または 1 本の動画を添付できます。
* 渡す画像は raw バイナリまたは base64 エンコードされたバイナリである必要があります。Content-Type が適切に設定されていれば、それ以外のエンコードやエスケープは不要です（不明な場合は `application/octet-stream` を指定してください）。
* base64 エンコードされた画像を POST する場合は、メッセージの画像パートに "Content-Transfer-Encoding: base64" を設定してください。
* Multi-part メッセージの境界は独立した行に置き、CRLF で終了する必要があります。
* このエンドポイントで POST を行う動作例については、[xurl](https://github.com/xdevplatform/xurl) でのテストを推奨します。また、利用可能な [X Libraries](/resources/tools-and-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_image`
* `tweet_video`
* `tweet_gif`
* `dm_image`
* `dm_video`
* `dm_gif`
* `subtitles`

Ads API パートナーの方は、promoted video の推奨 media category について [こちらのドキュメント](/x-ads-api/creatives#promoted-video) を参照してください。

## 画像の仕様と推奨事項

画像ファイルは以下の条件をすべて満たす必要があります。

* **対応する画像メディアタイプ**: `JPG`、`PNG`、`GIF`、`WEBP`
* **画像サイズ**: `<= 5 MB`
* **アニメーション GIF サイズ**: `<= 15 MB`

上記のファイルサイズ制限は media upload エンドポイントによって強制されます。これに加えて、`media_id` を使用して Post 作成（または類似の）エンドポイントを呼び出す際に適用される、プロダクトエンティティ固有のファイルサイズ制限が別途存在します。ファイルサイズ制限やその他の制約は、`media_category` パラメータによって異なる場合があります。

## アニメーション GIF の推奨事項

ファイルサイズの上限内でも、Post 作成時に GIF が失敗する可能性があります。成功率を高めるため、以下の制約に従ってください。

* **解像度**: `<= 1280x1080`（`width` x `height`）
* **フレーム数**: `<= 350`
* **ピクセル数**: `<= 300 million`（`width` \* `height` \* `num_frames`）
* **ファイルサイズ**: `<= 15Mb`

より大きい GIF を処理するには、`media_category` パラメータを指定した [chunked upload](/x-api/media/quickstart/media-upload-chunked) エンドポイントを使用してください。これにより、大きなファイル処理に必要な非同期処理をサーバー側で行えます。アニメーション 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](https://en.wikipedia.org/wiki/Pixel_aspect_ratio)**: `1:1` である必要があります
* **Pixel format**: [YUV](https://en.wikipedia.org/wiki/YUV) 4:2:0 のみ対応
* Audio は [`AAC` with Low Complexity profile](https://en.wikipedia.org/wiki/Advanced_Audio_Coding#Modular_encoding) である必要があります。（High-Efficiency `AAC` は非対応）
* Audio は `mono` または `stereo` である必要があり、5.1 以上は不可
* [`open GOP`](https://en.wikipedia.org/wiki/Group_of_pictures) を使用してはいけません
* [`progressive scan`](https://en.wikipedia.org/wiki/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           |

メディアアップロードの例については、[chunked media upload documentation](/x-api/media/quickstart/media-upload-chunked) を参照してください。

### トラブルシューティング

Media API に関する問題については、開発者フォーラムの [Media API カテゴリ](https://devcommunity.x.com/c/x-api/media-apis) で回答を検索してください。