There are a few important concepts to understand when using the POST media/upload endpoint. Uploading media with OAuth can be a bit tricky, so we’ve outlined some things to keep in mind as well as a working sample of how to use this endpoint here.

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 filesize limit above is enforced by the media upload endpoint. In addition, there is a separate product entity specific filesize limit which is applied when calling the Tweet creation (or similar) endpoints with media_id. For example, it is possible to upload a 5 MB image, but the Tweet creation requires images to be <= 3 MB. The filesize 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 filesize 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
  • Filesize <= 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, filesize, 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.

Orientation Width Height Video Bitrate Audio Bitrate
Landscape 1280 720 2048K 128K
Landscape 640 360 768K 64K
Landscape 320 180 256K 64K
Portrait 640 640 1024K 96K
Portrait 480 480 768K 64K
Portrait 240 240 256K 64K

Example of image media/upload

Below is an example of adding a small image with a single step. Use this example as a great way to debug your own code, however it's recommended to use the chunk upload process described in the next guide.

As of Twurl v0.9.0 (see our command-line twurl tool) support for calling Twitter’s REST API with a multipart message for the POST media/upload endpoint now exists. Note that many of the Twitter Libraries include methods that will handle this POST correctly for you.

Using the -t option will show you the full trace of the request and response that was POSTed to the Twitter API.

  twurl -H upload.twitter.com -X POST "/1.1/media/upload.json" --file "/path/to/media.jpg" --file-field "media"
  {
  "media_id": 553656900508606464,
  "media_id_string": "553656900508606464",
  "size": 998865,
  "image": {
    "w": 2234,
    "h": 1873,
    "image_type": "image/jpeg"
  }
}

Troubleshooting

For issues with the Media APIs: