Upload Media with X (Twitter) API v2: The 2026 Guide

Shipping images, GIFs, and video through the X API v2 is straightforward once the new auth, IDs, and chunk rules are clear. This guide explains exactly how to upload media to X, attach it to a post, and avoid the...

tutorial tools
Upload Media with X (Twitter) API v2: The 2026 Guide

Shipping images, GIFs, and video through the X API v2 is straightforward once the new auth, IDs, and chunk rules are clear. This guide explains exactly how to upload media to X, attach it to a post, and avoid the gotchas that waste engineering time. It includes a compact, working cURL example and a quick comparison table for fast reference.

What changed and why it matters

The v1.1 media/upload.json endpoint was deprecated on March 31, 2025, so production apps need to use https://api.x.com/2/media/upload. The flow is still INIT, APPEND, FINALIZE, plus STATUS polling for video and GIF, but the responses are now ID based in a data object. Instead of media_id_string at the top level, v2 returns data.id and related fields like expires_after_secs.

Auth changed too. The v2 media upload requires OAuth 2.0 user context with the media.write scope. App-only bearer tokens will fail. Old tokens issued without scopes return 403 until the user re-authorizes and grants media.write. Teams migrating should bake a re-auth path into the rollout.

Chunk semantics are stricter. APPEND accepts file pieces up to the 5MB per chunk limit with zero-based segment_index. Video and GIF must be finalized and then polled until processing_info.state is succeeded before tweet media attachment. Images often complete synchronously, but code should still guard for asynchronous cases.

Item v2 detail Notes
Endpoint POST https://api.x.com/2/media/upload INIT, APPEND, FINALIZE, STATUS
Auth OAuth 2.0 user, media.write Re-authorize to add scopes
IDs data.id on responses Replaces v1.1 media_id_string
Chunks Max 5 MB per APPEND segment_index starts at 0
Categories tweet_image, tweet_video, tweet_gif amplify_video for ads up to 512 MB
Attach to post POST https://api.x.com/2/tweets media.media_ids array, up to 4 images or 1 video
Processing STATUS polling for video/GIF pending, in_progress, succeeded, failed

The v2 upload flow

Plan the upload around file size and category. For INIT, provide command=INIT, media_type like image/png or video/mp4, total_bytes, and media_category. The response includes data.id and expires_after_secs, which defines the window to finish APPEND and FINALIZE. If uploads are started far ahead of a content calendar, track expiry and re-upload closer to publish time.

APPEND the file in segments no larger than 5 MB. Use consistent chunk size, for example 4 MB. A 100 MB video splits into roughly 25 parts at 4 MB each. Send segment_index starting at 0 and increment by 1 for each chunk. After the last piece, send FINALIZE with the same media_id.

Video and GIF processing is asynchronous. Fetch STATUS with GET /2/media/upload?command=STATUS&media_id=... and follow processing_info.check_after_secs for efficient polling. Only when state is succeeded should the media be attached to a tweet. Create the post with POST https://api.x.com/2/tweets, include media.media_ids: [""], and remember that X supports one video or up to four images per post.

Working code and one-call path

The example below uses cURL and assumes an OAuth 2.0 user token that already has the media.write scope. It uploads two 4 MB chunks, finalizes, polls, then posts the tweet. Adapt file names and paths as needed.

TOKEN="YOUR_USER_TOKEN_WITH_media.write"
# 1) INIT
curl -s -X POST "https://api.x.com/2/media/upload" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"INIT","media_type":"video/mp4","total_bytes":104857600,"media_category":"tweet_video"}'

# Assume the JSON returns {"data":{"id":"MEDIA_ID","expires_after_secs":...}}
MEDIA_ID="MEDIA_ID"

# 2) APPEND chunk 0 and 1 (repeat for all chunks)
curl -s -X POST "https://api.x.com/2/media/upload" -H "Authorization: Bearer $TOKEN" \
  -F "command=APPEND" -F "media_id=$MEDIA_ID" -F "segment_index=0" -F "media=@chunk_0000.bin"
curl -s -X POST "https://api.x.com/2/media/upload" -H "Authorization: Bearer $TOKEN" \
  -F "command=APPEND" -F "media_id=$MEDIA_ID" -F "segment_index=1" -F "media=@chunk_0001.bin"

# 3) FINALIZE
curl -s -X POST "https://api.x.com/2/media/upload" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d "{\"command\":\"FINALIZE\",\"media_id\":\"$MEDIA_ID\"}"

# 4) Poll STATUS for video/GIF until state == succeeded
curl -s "https://api.x.com/2/media/upload?command=STATUS&media_id=$MEDIA_ID" -H "Authorization: Bearer $TOKEN"

# 5) Create the tweet with the media_id
curl -s -X POST "https://api.x.com/2/tweets" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"text\":\"Video posted via API v2\",\"media\":{\"media_ids\":[\"$MEDIA_ID\"]}}"

Teams that prefer to skip chunk orchestration often use one-call services that accept a file and return a URL to pass as media_urls when creating the post. These services run on pay-per-use, where each published post consumes X API credits, and posts that include links may cost more. This approach removes the need for scopes or a developer account, but it trades control and introduces variable costs, so evaluate carefully for volume use.

Pro tips and pitfalls

Smart engineers avoid preventable 403s by ensuring user re-authorization when adding the OAuth 2.0 media.write scope. During migration, detect scope-less tokens and route users through a consent screen that grants media.write before any INIT calls. For resilience, implement exponential backoff on STATUS polling and treat processing_info.check_after_secs as a minimum, not a rigid delay.

  • Honor the 5MB per chunk limit. Changing chunk size mid-upload often produces failed processing.
  • Keep segment_index contiguous from 0. Skipped or repeated indices corrupt uploads.
  • For tweet media attachment, wait until processing succeeds. Attaching early is a common cause of post creation failure.
  • Validate media_type and media_category pairs, for example video/mp4 with tweet_video.
  • Cache data.id and expires_after_secs, then re-INIT if the window closes before FINALIZE.
  • Respect media limits. Typical caps are up to 4 images per post, 1 video, video around 140 seconds, and larger files only under amplify_video.

Related guides and next steps

  • OAuth 2.0 user context: adding scopes, rotating tokens, and least-privilege patterns.
  • Media processing webhooks: reacting to succeeded or failed states without hot polling.
  • Scheduling and batching: pre-upload windows, retries, and content calendars.
  • For teams that want scheduling, safe engagement, and publishing without maintaining code, BeeReach provides a full client portal with Content Scheduler and Smart Automation Rules. It targets audiences with Radar Filtering and executes only human-like actions, which keeps accounts safe. Learn more at https://beereach.io.

Related Posts