How to upload images and video with the X API v2

By itwtr Published November 17, 2026 5 min read

Short answer

To upload media with X API v2, call POST /2/media/upload/initialize with the file size and type to get a media_id, send the file in chunks of 5 MB or less to POST /2/media/upload/{id}/append, then call POST /2/media/upload/{id}/finalize. For video, poll the status until processing succeeds, then pass the ID in media.media_ids when you create the post.

Key takeaways

  • Upload is a separate step: you get a media_id first and attach it to POST /2/tweets afterwards.
  • The v2 flow uses three paths (initialize, append, finalize), not the old command= parameters.
  • Keep chunks at 5 MB or less; X's server maximum per chunk is 8 MB.
  • A post holds up to 4 photos, 1 GIF, or 1 video.
  • OAuth 2.0 tokens need the media.write scope.

Media is where most homemade X clients break first. Text posting is a single JSON request, but an image or a video needs its own upload session before the post exists. Here is the v2 flow, in the order your code runs it, with the limits X documents as of November 2026.

How does media upload fit into posting?

You upload the file first, receive a media_id, and then create the post with that ID in media.media_ids. The two calls are independent. That means you can upload while the user is still typing, and retry a failed post without uploading the file again, as long as the media has not expired on X’s side.

The post itself is the same POST /2/tweets call described in the posting and reading guide, with one extra field:

{
  "text": "Release notes for v0.4",
  "media": { "media_ids": ["1880028106020515840"] }
}

How do you run the chunked upload?

Initialize, append each chunk with an index starting at 0, then finalize. The same three steps work for a 200 KB PNG and a 2 GB video, so it is simpler to write one code path than two.

  1. Initialize. POST /2/media/upload/initialize with the total size in bytes, the MIME type, and a media_category such as tweet_image, tweet_gif or tweet_video. The response contains the media_id.
  2. Append. POST /2/media/upload/{id}/append once per chunk, sending the bytes and a segment_index that starts at 0. X recommends chunks of 5 MB or less and rejects anything over 8 MB.
  3. Finalize. POST /2/media/upload/{id}/finalize. For images this usually completes the upload. For video and GIFs the response may include processing_info.
  4. Check status. If you got processing_info, call GET /2/media/upload?command=STATUS&media_id={id} after the suggested wait, and repeat until the state is succeeded or failed.

A minimal append loop in Node looks like this:

const CHUNK = 4 * 1024 * 1024; // stay under the 5 MB guidance
for (let i = 0, seg = 0; i < buf.length; i += CHUNK, seg++) {
  const form = new FormData();
  form.append("segment_index", String(seg));
  form.append("media", new Blob([buf.subarray(i, i + CHUNK)]));
  await fetch(`https://api.x.com/2/media/upload/${id}/append`, {
    method: "POST",
    headers: { Authorization: `Bearer ${userToken}` },
    body: form,
  });
}

Check each response status inside the loop. A silent failure on chunk 3 surfaces later as a confusing finalize error.

What are the size and count limits?

X documents these limits per media category:

Category media_category Limit
Image tweet_image 5 MB
Animated GIF tweet_gif 15 MB
Video tweet_video 20 minutes or 8 GB (125 minutes or 16 GB for Premium)

One post can carry up to 4 photos, or 1 GIF, or 1 video. Video length and size are checked again when the post is created, and going over returns a 403. Validate on your side before uploading so the user does not wait for a multi-gigabyte upload that will be refused.

Which authentication works for uploads?

Uploads need a user-context token; with OAuth 2.0 that means requesting the media.write scope. Add it next to tweet.read, tweet.write and users.read in the authorize URL. If your app already has users who authorized without it, they need to authorize again before uploads work, because a token never gains scopes after it is issued. The authentication chapter shows where the scope list goes in the PKCE flow.

App-only Bearer tokens cannot upload media on behalf of a user. If you see 403 errors on initialize, check the token type before anything else.

What goes wrong most often?

Most failures come from the old protocol, wrong chunk indexes, or posting before processing finishes.

  • Old command parameters. X’s docs say not to send command=INIT, command=APPEND or command=FINALIZE to POST /2/media/upload. Code ported from v1.1 often does exactly that.
  • Index gaps. segment_index must start at 0 and increase by one. Parallel uploads that finish out of order are fine; missing numbers are not.
  • Posting too early. A video that is still in_progress cannot be attached. Wait for succeeded.
  • DM categories by mistake. Categories such as dm_image and dm_video are meant for direct messages. If you omit media_category, X treats the upload as post media based on its content type, which is safer than guessing.

Keep upload code in one module with its own retries. When X changes something about media again, that is the only file you will need to touch.

Sources

  1. Chunked media upload quickstart, X Developer Platform documentation.
  2. Manage Posts: create a Post, X Developer Platform documentation.
  3. OAuth 2.0 Authorization Code with PKCE, X Developer Platform documentation.

Frequently asked questions

Which endpoint uploads media in X API v2?

The chunked flow uses POST /2/media/upload/initialize, then POST /2/media/upload/{id}/append for each chunk, then POST /2/media/upload/{id}/finalize. You poll GET /2/media/upload with command=STATUS while video processes.

How big can an image or video be?

X documents 5 MB for images, 15 MB for GIFs, and 20 minutes or 8 GB for video by default, with 125 minutes or 16 GB for Premium accounts. Check the media docs before you hard-code these.

How many images can one post have?

Up to 4 photos, or 1 animated GIF, or 1 video. You cannot mix a video with photos in the same post.

What scope does OAuth 2.0 need for uploads?

Add media.write alongside tweet.write and tweet.read when you request the user's authorization, then send the user access token as a Bearer token.

Can I still send command=INIT to the v2 upload endpoint?

No. X's documentation says not to send command=INIT, APPEND or FINALIZE to POST /2/media/upload; those belong to the previous protocol. Use the separate initialize, append and finalize paths.