X's animated GIF cap for a Post is <= 15 MB — but X's own documentation says staying under it is not enough. The Media best practices page in X's developer documentation puts it in one sentence: "A GIF may fail during Post creation even if it is within the file size limit."
That single line explains the situation almost everyone lands on this page with: a GIF that is clearly under 15 MB, that X still refuses to post. There are three more constraints alongside the file size, and one of them is a number you cannot see in any file manager.
What "too large" actually means for a GIF on X
X's developer documentation lists four constraints together, under the heading "Animated GIF recommendations." Quoted verbatim, after the sentence above, it says: "Adhere to the following constraints to improve success rates."
| Constraint | Value in X's developer documentation |
|---|---|
| Resolution | <= 1280x1080 (width x height) |
| Number of frames | <= 350 |
| Number of pixels | <= 300 million (width * height * num_frames) |
| File size | <= 15 MB |
The first three rows come from the "Animated GIF recommendations" block quoted above. The <= 15 MB figure also appears separately, under the heading "Image specifications and recommendations," as "Animated GIF size: <= 15 MB."
Two things are worth noticing before you go any further.
First, file size is only one of four. The other three describe the shape of the animation, not the size of the file on disk.
Second, these are from the developer documentation for the Media API. X's Media Studio help page publishes its own GIF row — maximum file size 15 MB, file type .GIF, maximum resolution 2048x2048 — and that page carries an explicit scope statement: "These instructions are only valid for Media Studio, and should not be followed for usage of the X developer API, Pro Media API, desktop upload, or mobile upload." The two resolution figures are different. Check the official documentation for the set that applies to how you are uploading.
The pixel budget is the constraint nobody checks
The third row is the interesting one, and it is almost absent from other write-ups of this problem.
width * height * num_frames is a total pixel budget across the whole animation, capped at 300 million. It is not a resolution limit and not a length limit — it is the product of both. That means two GIFs can fail for opposite reasons:
- A small but long GIF: 480x270 at 340 frames is 44 million pixels, comfortably fine.
- A large but short GIF: at the maximum 1280x1080, each frame costs about 1.38 million pixels, so the 300 million budget runs out long before the 350-frame figure does.
That arithmetic is just X's own formula applied — it is not an extra rule. But it is the reason a GIF that looks small on disk can behave differently from a chunkier-looking one: X's instruction is to "Adhere to the following constraints to improve success rates," and that sentence introduces all four rows, not the file size alone.
The practical upshot is that the two levers that help most are the two that reduce the product directly: fewer frames (a shorter clip, or a lower frame rate) and smaller dimensions. Both also cut the file size as a side effect, which is why re-exporting usually fixes several constraints in one pass.
The fastest fix: rebuild the GIF smaller
Trimming a second off the source clip and dropping the output width is almost always faster than trying to squeeze an existing GIF with a lossy optimiser, and it gives you direct control over frame count and dimensions — the two numbers X is actually measuring.
Try it right here
Runs in your browser. Your file is not uploaded anywhere.
This runs entirely inside your browser tab: the video is read from disk, converted locally, and handed back.
Start from the source video rather than the finished GIF if you still have it — see MP4 to GIF for the straight conversion. Choose a width first, then shorten the clip until the frame count looks sane. A 3-second clip at 15 frames per second is 45 frames, which leaves enormous headroom on both the frame cap and the pixel budget.
Other reasons a GIF gets rejected
The upload succeeding does not mean the Post will. X's developer documentation is explicit about this two-stage behaviour: "Upload limits and Post-create limits are separately enforced. A media_id that finalized successfully can still be rejected by POST /2/tweets." That is exactly the shape of the failure described at the top of this page — the bytes arrive, then the Post is refused.
The media category changes which limits apply. X describes the parameter this way: "The Media Category parameter defines the use case of the media file to be uploaded, and can affect file size limits or other constraints enforced for media uploads." It also names a specific trap: "Using the wrong category (for example a DM category on a Post) is a common reason an upload succeeds and Post create then fails."
Larger GIFs need the chunked path. Quoted verbatim: "In order to process larger GIFs, use the chunked upload endpoint with the media_category parameter. This allows the server to process the GIF file asynchronously, which is a requirement for processing larger files. Pass media_category=tweet_gif to enable async upload behavior for Posts with an animated GIF." On that path the same documentation says to "Keep each segment at or below 5 MB (the server maximum is 8 MB)," lists the processing states as "pending → in_progress → succeeded or failed," and gives the benefits as "Improved reliability on slow networks," uploads that "can be paused and resumed," and failed chunks that "can be retried individually."
One GIF per Post. X states: "You may attach up to 4 photos, 1 animated GIF or 1 video in a Post." If you are trying to attach a GIF alongside other media, that is a different wall entirely.
How to tell it worked
Before you retry, read four numbers off the new file rather than guessing: width, height, frame count, and size on disk. Multiply the first three and check the result against 300 million. If all four clear the table above and the Post still fails, the problem is no longer size — the category and two-stage checks above are the next things to look at.
FAQ
What is the maximum GIF file size on X?
<= 15 MB for an animated GIF, per X's developer documentation, which lists the same figure for a GIF on a Post (tweet_gif) and a GIF in a Direct Message (dm_gif). The Media Studio help page also gives 15 MB, but with its own scope statement and a different maximum resolution.
Why does my GIF fail when it is only 8 MB?
Because file size is one of four constraints. X's documentation states that a GIF "may fail during Post creation even if it is within the file size limit," then lists resolution <= 1280x1080, frames <= 350, and total pixels <= 300 million. An 8 MB GIF can fail any of the other three.
How many frames can a GIF have on X?
X's developer documentation lists <= 350 frames and, separately, the product width * height * num_frames at <= 300 million, both under "Adhere to the following constraints to improve success rates." At high resolutions the pixel budget runs out before the frame count does, so check both.
Can I post more than one GIF at a time? No. X's wording: "You may attach up to 4 photos, 1 animated GIF or 1 video in a Post."
Will my GIF animate in an X ad? X's Ads creative specs page says otherwise for ad creatives: "Note: GIFs uploaded will render as a static image." That is the advertising surface specifically — do not read it as the behaviour of a GIF in a normal Post.
Is it safe to convert a GIF on a website? Only if the tool does not upload your file. The converter on this page works inside your browser tab. See all Clapr tools, or browse more fix guides for other upload failures.
Constraints cited from X's developer documentation (Media best practices and chunked upload) and X's Media Studio and Ads help pages, checked 16 September 2026. X publishes different figures on different official pages — verify against the page that matches how you upload. For the video equivalent of this problem, see X's video file size limit.
