POST media/upload (chunked)
Upload videos or chunked images to Twitter for use in a Tweet or Twitter-hosted Card. For uploading images in a single call, see our POST media/upload endpoint.
Ensure your POST is a multipart/form-data request. You may either upload the raw binary of the file or its base64-encoded contents. The resulting media_id or media_id_string will be used to pass to the POST statuses/update or Card-related API endpoints. See our uploading media guide for more on using this endpoint.
Uploaded media files will be available for use for the time indicated in the response, before they are flushed from the servers (if not associated to a Tweet or Card). Note that you need to call the upload endpoint for each media file you want to upload, storing the media_ids to use with other endpoints, such as POST statuses/update. We suggest using the media_id_string value to avoid issues in Javascript and other languages that do not support 64-bit integers.
The media and media_data parameters are mutually exclusive.
Media uploads for images are limited to 5MB in file size, and for videos are limited to 15MB. For chunked uploads, the maximum chunk size is 5MB.
MIME-types supported by this endpoint: PNG, JPEG, BMP, WEBP, GIF, Animated GIF, MP4
Uploads using this endpoint require at least 3 calls, one to initialize the request, which returns the media_id, one or more calls to append/upload binary or base64 encoded data, and one last call to finalize the upload and make the media_id usable with other resources.
The phases of the upload using this endpoint:
| Command | Purpose | Required Parameters | Response |
|---|---|---|---|
INIT | Initialize an upload | command, total_bytes, media_type | JSON |
APPEND | Upload(s) of chunked data | command, media_id, segment_index, either media or media_data | HTTP 2XX |
FINALIZE | Complete the upload | command, media_id | JSON |
STATUS | Check the processing status of the upload (for async video uploads only) | command, media_id | JSON |
A detailed example of each of these phases can be found in our uploading media guide.
Note: The domain for this endpoint is upload.twitter.com
Resource URL
https://upload.twitter.com/1.1/media/upload.jsonResource Information
Parameters
The type of operation to take. Possible values are INIT, APPEND and FINALIZE. Always required.
Example: INIT.
The size of the media being uploaded in bytes.
The MIME type of the media being uploaded.
Example: video/mp4.
A comma-separated string of user IDs to set as additional owners who are allowed to use the returned media_id in Tweets or Cards. A maximum of 100 additional owners may be specified.
The media_id returned from the INIT query. Required after an INIT on subsequent calls until the upload has completed.
The base64-encoded file content being uploaded. Cannot be used with media.
The raw binary file content being uploaded. Cannot be used with media_data.
Required after an INIT, an index number starting at zero indicating the order of the uploaded chunks. The chunk of the upload for a single media, from 0-999, inclusive. The first segment_index is 0, the second segment uploaded is 1, etc.
Identifies category the current media upload should be associated with.
Note: this is currently only applicable for video uploads for Ads API developers who should include a value of amplify_video for this parameter.
OAuth Signature Generator
Sign in to see a list of your registered applications.