Upload media

Keep in mind

• Because the method uses multipart POST, OAuth is handled differently. POST or query string parameters are not used when calculating an OAuth signature basestring or signature. Only the oauth_* parameters are used.
• You may attach up to 4 photos, 1 animated GIF or 1 video in a Tweet.
• The image passed should be the raw binary of the image or binary base64 encoded, no need to otherwise encode or escape the contents as long as the Content-Type is set appropriately (when in doubt: application/octet-stream).
• When posting base64 encoded images, be sure to set the “Content-Transfer-Encoding: base64” on the image part of the message.
• Multi-part message boundaries must be on their own line and terminated by a CRLF.
• For working examples of how to POST using this endpoint, we recommend testing with twurl. Also take a look at the Twitter Libraries available.
• Use the media_id_string provided in the API response from Javascript and other languages that cannot accurately represent a long integer.

Image specifications and recommendations

Image files must meet all of the following criteria:

• Supported image media types: JPG, PNG, GIF, WEBP
• Image size <= 5 MB, animated GIF size <= 15 MB

The file size limit above is enforced by the media upload endpoint. In addition, there is a separate product entity specific file size limit which is applied when calling the Tweet creation (or similar) endpoints with media_id. The file size limit and other constraints may vary depending on the media_category parameter.

Animated GIF recommendations

A GIF may fail during Tweet creation even if it is within the file size limit. Adhere to the following constraints to improve success rates.

• Resolution should be <= 1280x1080 (width x height)
• Number of frames <= 350
• Number of pixels (width * height * num_frames) <= 300 million
• File size <= 15Mb

In order to get better support for larger GIFs, use the chunked upload endpoint with the media_category parameter. This allows the server to process the GIF file asynchronously, which is a requirement for processing larger files. Pass media_category=tweet_gif to enable async upload behavior for Tweets with an animated GIF.

Video specifications and recommendations

Video files must meet all of the following criteria:

• Duration should be between 0.5 seconds and 30 seconds (sync) / 140 seconds (async)
• File size should not exceed 15 mb (sync) / 512 mb (async)
• Dimensions should be between 32x32 and 1280x1024
• Aspect ratio should be between 1:3 and 3:1
• Frame rate should be 40fps or less
• Must not have open GOP
• Must use progressive scan
• Must have 1:1 pixel aspect ratio
• Only YUV 4:2:0 pixel format is supported.
• Audio should be mono or stereo, not 5.1 or greater
• Audio must be AAC with Low Complexity profile. High-Efficiency AAC is not supported.

Note that the duration, file size, fps and other constraints may vary based on the media_category parameter.

The media platform is optimized to handle the specifications of video captured on mobile devices. For developers creating their own video (i.e. not uploading video captured directly from a mobile device), please refer to the table below. Each row represents an upload recommendation, but is not a requirement. All uploads are processed for optimization across multiple platforms.