X API media upload: the v2 flow that actually works

#Quick answer

X API media upload needs four calls for anything larger than an image: POST /2/media/upload/initialize to open a session and get a media_id, POST /2/media/upload/:id/append once per chunk, POST /2/media/upload/:id/finalize to close it, then GET /2/media/upload?command=STATUS until processing reports succeeded. Images and subtitle files can still go in a single shot to POST /2/media/upload. The scope is media.write, the media_id lives for 24 hours, and the bytes themselves are not billed.

Last updated: October 2026

The hard part is not the four calls. It is that the protocol changed in 2025, so most of the sample code you will find does something X no longer accepts, and that upload limits and posting limits are two separate gates with the same video failing at the second one.

#The four calls

Open the session with a JSON body. Not form fields, not query parameters.

curl -X POST "https://api.x.com/2/media/upload/initialize" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_type":"video/mp4","total_bytes":1048576,"media_category":"tweet_video"}'

You get back an id, a media_key, and expires_after_secs: 86400. That last field is the one worth writing down: 24 hours from initialize to attachment, which is generous for a publish flow and tight for a scheduling queue that pre-uploads a week of video.

Chunks go up one at a time, as multipart, indexed from zero:

curl -X POST "https://api.x.com/2/media/upload/1880028106020515840/append" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -F "segment_index=0" \
  -F "media=@/path/to/chunk0.mp4"

X recommends keeping each segment at or below 5 MB against a server maximum of 8 MB. Finalize takes no body at all. If the finalize response carries a processing_info object, you are not done: poll the status endpoint and respect the check_after_secs it hands you, walking the state machine from pending through in_progress to succeeded or failed. No processing_info means the media is ready immediately, which is the normal case for stills.

Then the media_id goes into the Post:

curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Check out this video","media":{"media_ids":["1880028106020515840"]}}'

One Post takes up to 4 photos, 1 animated GIF, or 1 video. Not a mix.

#The command parameter is dead, and that is why your code broke

X shipped v2 media upload on 17 January 2025 as a single endpoint that took command=INIT, command=APPEND and command=FINALIZE as query parameters, the same shape the old v1.1 endpoint used. That lasted about three months. On 30 April 2025 X replaced the command parameter with the three dedicated paths and gave developers until 30 May 2025 to migrate, then sunset the v1.1 upload endpoints on 9 June 2025.

In practice, POST /2/media/upload still exists, but only for one-shot image and subtitle uploads. Send it command=INIT with total_bytes and media_category today and you get a 400 that reads like nonsense, one error object per parameter, each saying the query parameter "is not one of []". That exact response is all over X's developer forum from the end of May 2025, and X staff answered it the same way every time: migrate to the dedicated endpoints.

Two more artifacts from that migration still cost people time. The append documentation listed segment_index with a required range starting at 1, while the server requires it to start at 0; a developer caught that on 2 May 2025 and the docs were corrected. And a 403 at the initialize step, from a token that posts text perfectly well, is almost always a missing media.write scope rather than a broken token, which is how one developer resolved it on 28 July 2025 after a day of debugging. If you are still deciding which token type to hand this flow, X API OAuth has the scope table and the endpoint-by-method split.

#Limits follow the user, not your plan

This is the single most misread part of media upload. Your developer tier does not decide how long a video you can push. The uploading account's X Premium or verified status does, together with the media_category you declared at initialize.

Minimum duration is 0.5 seconds everywhere. Images accept JPG, PNG, GIF and WEBP. Those Post-video ceilings are the same ones the X app enforces, which is why they match what X video length describes for ordinary users.

Declaring the category correctly matters more than it looks. If you omit it, X infers a Post category from the content type, which is usually right. If you declare a DM category and then attach the result to a Post, the upload succeeds and the Post create fails, and nothing in the error tells you the category was the problem. Use tweet_video for regular Posts and amplify_video for Ads creatives; for Post video the two carry identical caps.

GIFs have their own failure mode, where a file inside the 15 MB limit still dies at Post creation. X publishes the real constraints: no more than 1280x1080, no more than 350 frames, and width times height times frame count no greater than 300 million pixels. Large GIFs need the chunked flow with media_category=tweet_gif so the server can process them asynchronously.

For video encoding, the recommendations that matter are H264 High Profile, AAC LC audio, mono or stereo only, progressive scan, no open GOP, YUV 4:2:0 pixel format, a 1:1 pixel aspect ratio, 60 FPS or less, and an aspect ratio between 1:3 and 3:1.

#The 403 that arrives after a clean upload

Upload limits and Post-create limits are enforced separately. X says so twice in its own docs, because it surprises everyone. A media_id that finalized with state succeeded can still be rejected when you attach it:

{
  "title": "Forbidden",
  "detail": "This user is not allowed to post a video longer than 20 minutes.",
  "type": "about:blank",
  "status": 403
}

That N is the posting user's cap, 20 minutes by default and 125 for Premium. The initialize endpoint happily accepts a total_bytes up to 16 GB regardless of who is authenticated, so a tool that uploads on behalf of many accounts will absolutely hit this: the same 40-minute video succeeds for your Premium beta tester and fails for everyone else, after you already burned the bandwidth. Check the author's entitlement before you start the upload, not after.

#What it costs, and what counts against rate limits

Under pay-per-use, media upload is one of the few things that is effectively free. Initialize, append, finalize and status appear on neither the read nor the write pricing table as of 13 October 2026. What you pay for is the entity:

A Post containing a link costs more than thirteen times a Post without one, which is its own design constraint if you publish video with a call to action. The rest of the per-request and per-resource table is in X API pricing.

Rate limits are where chunked upload actually bites, because they count calls and not files. Initialize, append and finalize each allow 1,875 requests per 15 minutes and 180,000 per 24 hours. A 1 GB video split into 4 MB chunks is 256 append calls, so that 15-minute window holds roughly seven such uploads from one app. Push the chunk size to the 8 MB server maximum and you halve the call count, at the cost of a more expensive retry when a chunk fails. The one-shot POST /2/media/upload runs on a tighter 500 per 15 minutes, the status GET allows 1,000, metadata 500, and subtitles only 100.

#Alt text, subtitles, and per-media analytics

Three endpoints hang off a finalized media_id, and all three are easy to miss.

POST /2/media/metadata is where accessibility and distribution controls live. metadata.alt_text.text takes up to 1,000 characters, which is far more than the app's own field offers, and the same call carries sensitive_media_warning, allow_download_status, content_expiration with a timestamp_sec, plus geo and domain restrictions. Alt text is the only part of this that cannot be changed later, exactly as it works for alt text on X in the app.

POST /2/media/subtitles attaches a caption track, and it has a genuine trap. A subtitle file is itself uploaded as media with media_category=subtitles, capped at 1 MB, and the resulting id is what you attach. The language_code field is described as BCP47 but validated against a two-uppercase-letter pattern, so EN passes and en or en-US do not.

GET /2/media/analytics reports per-asset playback: video_views, watch_time_ms, the playback_start through playback_complete quartiles, and cta_url_clicks. It takes up to 100 media_keys at once, requires start_time and end_time, and accepts hourly, daily or total granularity. Note it keys on media_key, the 13_1880028106020515840 form, not the bare media_id, and it only needs tweet.read.

#One more thing before you ship it

Media upload needs a write scope, and since 14 September 2026 any pay-per-use app requesting a write scope shows the user a "Sensitive permissions requested" notice, a statement that your app is not affiliated with X, and a mandatory "I trust this app" checkbox before the Authorize button works. X's own forum post says there is no way to remove it. Build your authorization funnel expecting that friction rather than treating it as a misconfiguration.

Setup is otherwise ordinary: an app, a user-context token with media.write, and credits in the console. If you have not done that part yet, how to get an X API key covers it.

What the API will not do is make automated engagement cheap or sanctioned. Posting, replying and following through code sit under X's automation rules, which require an accountable operator and the automated account label on accounts posting without a human, and the per-Post price means a high-volume reply habit meters fast. Plenty of growth work therefore never touches a token at all: replying in your own voice, from your own browser session, on your own machine, carries no API bill and a smaller detection surface than a cloud tool calling in from a shared IP pool, though a browser-driven workflow is a gray area under those same rules rather than something anyone should call compliant. That is the trade X-Autopilot makes.

For media, though, the API is the only route. Get the four calls right, declare the category honestly, check the author's entitlement before you upload, and the rest is bandwidth.