Skip to main content
A media object represents a single photo, video or animated GIF. Media objects are used by many endpoints within the X API, and may be included in Posts, Direct Messages, user profiles, advertising creatives and elsewhere. Each media object may have multiple display or playback variants, with different resolutions or formats.

​
Size and duration limits

Upload and posting are separately enforced. A file that uploads successfully can still be rejected when you attach it to a Post with POST /2/tweets. Limits depend on:
  • The authenticated user’s X Premium / verified status — not your developer API plan
  • The media_category you pass when initializing the upload

​
Images and GIFs

​
Video

Use chunked upload for all videos. Simple POST /2/media/upload is for images and small files only. Minimum video duration is 0.5 seconds in all cases. These Post-video caps match the X app. Premium status is the uploading user’s X Premium / verified subscription (feature/long_video_upload), not your developer API plan.
POST /2/media/upload/initialize accepts total_bytes up to 16 GB. Passing a larger total_bytes than the account is allowed to upload fails at initialize or finalize.

​
Posting (POST /2/tweets)

Attaching a media_id re-checks duration and size against the posting user’s entitlement:
  • A Post may include up to 4 photos, 1 animated GIF, or 1 video.
  • If the video is longer than that user is allowed to post, the request fails with 403 Forbidden: This user is not allowed to post a video longer than N minutes.
  • Upload succeeding does not guarantee the media can be attached to a Post. Always handle this 403 when creating Posts with video.
For codec, resolution, and frame-rate requirements, see Best practices.

​
Creation

Objects such as Posts, Direct Messages, user profile pictures, hosted Ads cards, etc. can contain one or more media objects. These top-level objects are collectively known as entities. The relevant entity creation API (e.g. POST /2/tweets) can be passed one or more media objects using a unique media_id. An entity which contains media object(s) can be created by following these steps:
  1. Upload the media file(s) using either the recommended chunked upload (images/GIF/video), or the older simple upload (images only).
  2. Receive a media_id from step 1. This step may be repeated multiple times with different media if the entity allows multiple media_id parameters to be passed in.
  3. Create the entity by calling the appropriate endpoint, including the media_id and other required parameters. For example, attach a media_id to a Post using the POST /2/tweets endpoint.

​
Retrieving

Please refer to the Media Object in the data dictionary.