POST /2/media/upload
endpoints are used to upload a video, which requires an adjusted workflow from single image uploads.
For video or chunked uploads, you must:
INIT
commandAPPEND
commandFINALIZE
commandCONSUMER_KEY
, CONSUMER_SECRET
, ACCESS_KEY
, ACCESS_TOKEN
in the App inside of your Project in the dashboard of the Developer Portal.
INIT
command request is used to initiate a file upload session. It returns a media_id
which should be used to execute all subsequent requests. The next step after a successful return from INIT
command is the APPEND
command.
See Best Practices for constraints and requirements on media files.
Example Request
multipart/form-data
or application/x-www-form-urlencoded
POST formats.id
(string) and media_key
(string). The entire file must be uploaded before expires_after_secs
seconds.
APPEND
command is used to upload a chunk (consecutive byte range) of the media file. For example, a 3 MB file could be split into 3 chunks of size 1 MB, and uploaded using 3 APPEND
command requests. After the entire file is uploaded, the next step is to call the FINALIZE
command.
segment_index
is an ordered index of file chunk. It must be between 0-999 inclusive. The first segment has index 0, second segment has index 1, and so on. Continue uploading the file chunks until all the chunks are uploaded.
multipart/form-data
POST format.FINALIZE
command should be called after the entire media file is uploaded using APPEND
commands. If and (only if) the response of the FINALIZE
command contains a processing_info
field, it may also be necessary to use a STATUS
command and wait for it to return success before proceeding to Post creation.
Example Request
multipart/form-data
or application/x-www-form-urlencoded
POST formats.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 mediaId after this time period in other API calls will result in a Bad Request (HTTP 4xx) response.
If the response contains a processing_info
field, then use the STATUS
command to poll for the status of the FINALIZE
operation. The async finalize approach is used for cases where media processing requires more time. In future, all video and animated GIF processing will only be supported using async finalize. This behavior is enabled if an upload session was initialized with a media_category
parameter, and when then media type is either video or animated GIF.
processing_info
field is NOT returned in the response, then media_id
is ready for use in other API endpoints.STATUS
command is used to periodically poll for updates of media processing operation. After the STATUS
command response returns succeeded
, you can move on to the next step which is usually create Post with media_id
.
FINALIZE
command or a previous STATUS command contained a processing_info
field.processing_info
field which provides information about current state of media processing operation. It contains a state
field which has transition flow: pending
-> in_progress
-> [failed
| succeeded
]. You can not use the media_id
to create Post or other entities before the state field is set to succeeded
.
POST /2/tweets
endpoint, including the media_id
on behalf of an authenticated user.
Example Request