Skip to main content
POST
Initialize media upload
Start a chunked upload session. Send a JSON body with media_type, total_bytes, and media_category. Do not send command=INIT to POST /2/media/upload.

Size and duration limits

total_bytes may be at most 16 GB in the request schema. The session is then capped by the authenticated user’s X Premium / verified status and by media_category: Minimum video duration is 0.5 seconds. Use tweet_video for a regular Post and amplify_video for Ads creatives. Post-video caps are the same for both categories. A successful initialize does not mean the file can be attached to a Post. POST /2/tweets re-checks duration and returns 403 if the video is longer than that user is allowed to post. See size and duration limits and the chunked upload quickstart.

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
additional_owners
string[]

User ids granted access to the uploaded media.

Pattern: ^[0-9]{1,19}$
media_category
enum<string>

The media category of the upload.

Available options:
amplify_video,
tweet_gif,
tweet_image,
tweet_video,
dm_gif,
dm_image,
dm_video,
subtitles
media_type
enum<string>

The type of media.

Available options:
video/mp4,
video/webm,
video/mp2t,
video/quicktime,
text/srt,
text/vtt,
image/jpeg,
image/gif,
image/bmp,
image/png,
image/webp,
image/pjpeg,
image/tiff,
model/gltf-binary,
model/vnd.usdz+zip
shared
boolean

Whether this media is shared or not.

total_bytes
integer

The total size of the media upload in bytes.

Required range: 0 <= x <= 17179869184

Response

The request has succeeded.

data
object
errors
object[]