POST media/upload

Overview¶

Use this endpoint to upload images to Twitter.

This endpoint returns a media_id by default and can optionally return a media_key when a media_category is specified. These values are used by Twitter endpoints that accept images.

For example, a media_id value can be used to create a Tweet with an attached photo using the POST statuses/update endpoint.

All Ads API endpoints require a media_key. For example, a media_key value can be used to create a Draft Tweet with a photo using the POST accounts/:account_id/draft_tweets endpoint.

Usage¶

This is a simple image upload endpoint with a limited set of features. The preferred alternative is the chunked upload endpoint which supports both images and videos, provides better reliability, allows resumption of file uploads, and other important features. In the future, new features will only be supported for the chunked upload endpoint.

• See the Uploading media guide for constraints and requirements on media files.
• See the Uploading Media tutorial for step-by-step instructions on uploading an image.
• Use the media metadata endpoint to provide image alt text information.
• Ensure the POST is a multipart/form-data request. Either upload the raw binary (media parameter) of the file, or its base64-encoded contents (media_data parameter). Use raw binary when possible, because base64 encoding results in larger file sizes
• The response provides a media identifier in the media_id (64-bit integer) and media_id_string (string) fields. Use the media_id_string provided in the API response from JavaScript and other languages that cannot accurately represent a long integer.
• The returned media_id and media_key are only valid for expires_after_secs seconds. Any attempt to use either after this time period in other endpoints will result in an HTTP 4xx Bad Request.
• The additional_owners field enables media to be uploaded as user A and then used to create Tweets as user B.
• Please note that to upload videos or GIFs (tweet_video, amplify_video, and tweet_gif), you need to use the chunked upload end-point.

Request¶

Requests should be either multipart/form-data or application/x-www-form-urlencoded POST formats.

Note: The domain for this endpoint is upload.twitter.com

Resource URL¶

https://upload.twitter.com/1.1/media/upload.json

Resource Information¶

Parameters¶

Example Request¶

POST https://upload.twitter.com/1.1/media/upload.json?media_category=tweet_image

Example Response¶

{
  "media_id": 710511363345354753,
  "media_id_string": "710511363345354753",
  "media_key": "3_710511363345354753",
  "size": 11065,
  "expires_after_secs": 86400,
  "image": {
    "image_type": "image/jpeg",
    "w": 800,
    "h": 320
  }
}