POST media/upload
Overview
Use this endpoint to upload images to Twitter. It returns a media_id which can be used in most Twitter endpoints that accept images. For example, a media_id value can be used to create a Tweet with an attached photo using the statuses/update endpoint.
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.
Supported media types and filesize
- Supported media types: jpg, png, gif, webp
- Image file size must be <= 5 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 endpoint requires images to be <= 3 MB.
See the uploading media guide for additional constraints for animated GIF files.
Use the media metadata endpoint to provide image alt text information.
Request
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
Response
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 is only valid for expires_after_secs seconds. Any attempt to use media_id after this time period in other endpoints will result in an HTTP 4xx Bad Request.
The additional_owners field enables media to be uploaded media as user A and then used to create Tweets as user B.
Resource URL
https://upload.twitter.com/1.1/media/upload.jsonResource Information
Parameters
The raw binary file content being uploaded. Cannot be used with media_data.
The base64-encoded file content being uploaded. Cannot be used with media.
A comma-separated list of user IDs to set as additional owners allowed to use the returned media_id in Tweets or Cards. Up to 100 additional owners may be specified.
OAuth Signature Generator
Sign in to see a list of your registered applications.
Example Request
POST
https://upload.twitter.com/1.1/media/upload.json
Example Result
{
"media_id": 553639437322563584,
"media_id_string": "553639437322563584",
"size": 998865,
"image": {
"w": 2234,
"h": 1873,
"image_type": "image/jpeg"
}
}