X's developer documentation lists text/vtt among the media types its upload endpoint accepts, while X's help centre pages on captions mention only .srt — X has not published a page that states WebVTT caption files are supported. That gap is the honest answer, and it is worth more than a yes or a no, because it tells you which file to actually upload.
If you only want the practical version: the format X documents end to end, with format rules and an error message of its own, is SRT. VTT appears in one machine-readable enum and nowhere else.
What each official page actually says
| Official source | What it says about caption formats |
|---|---|
| Developer docs, Initialize Media Upload (OpenAPI schema) | The media_type enum includes both text/srt and text/vtt |
| Help centre, How to upload caption (.srt) file to Posts | Only .srt, including in the page title |
| Help centre, Media Studio Library | "Subtitles: CEA 608/708 embedded, .SRT sidecar" |
| Developer docs, Chunked Media Upload | The subtitles media category has a 1 MB ceiling |
| Developer docs, Create Media subtitles (OpenAPI schema) | media_category enum: AmplifyVideo, TweetVideo |
The enum entry is real and checkable. In the OpenAPI schema for the media upload initialize endpoint, the accepted media_type values include video/mp4, video/webm, video/mp2t, video/quicktime, text/srt and text/vtt, alongside the image types. Both subtitle MIME types sit in the same list.
The help centre never follows up on that. X's caption walkthrough is titled "How to upload caption (.srt) file to Posts," and it opens by defining the format it wants: "Caption files are a specific file type called SRT. SRT stands for Secure Reliable Transport." It ends with a scope note people miss — "Note: Currently this feature is available on web only." Nothing on that page mentions WebVTT.
Why the enum is not the same thing as support
media_type is a parameter on the INIT request in the API upload flow. It describes what that one call accepts. X has not published a page listing which caption formats its other upload paths accept — the help centre pages on captions name .srt and nothing else — so check the official documentation rather than reading the enum as a site-wide format list.
X's own developer docs are explicit that clearing one stage does not clear the next: "Upload limits and Post-create limits are separately enforced. A media_id that finalized successfully can still be rejected by POST /2/tweets." The docs also warn that "using the wrong category (for example a DM category on a Post) is a common reason an upload succeeds and Post create then fails." So a permissive list at initialize is not documented as a promise about the steps after it.
The category you declare matters for the same reason. X describes it 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." Captions have their own category, subtitles, with its own ceiling — which is another sign that the MIME list at initialize is only one of several gates a file passes through.
There is a second oddity in the captions schema worth knowing before you write code against it. In Create Media subtitles, the language_code field is described as a "BCP47 language code of the subtitle track," but its validation pattern is ^[A-Z]{2}$ — two uppercase letters only. The description and the regex do not agree, and X has not published a page resolving which one to follow. Check the official documentation before assuming a value.
What to upload to X today
Ship SRT. It is the only format with a documented workflow, documented formatting rules, and a documented error message, and it is what both the help centre and the Media Studio specifications name.
If your captions came out of a transcription tool, a browser player workflow, or a screen recorder, they are often WebVTT. Converting is a text-level operation — the cue text is identical, and the timestamp separator and header differ — so you can do it locally without re-uploading your video anywhere: VTT to SRT.
Going the other way is just as common: you built an SRT for X, and now the same video needs captions on your own site's HTML5 player, which wants WebVTT.
Try it right here
Runs in your browser. Your file is not uploaded anywhere.
This runs in your browser tab — the subtitle file is parsed and rewritten locally, never uploaded. That matters more than usual for captions, since a subtitle file is a full transcript of whatever you said.
The four format checks X publishes for .srt
If your SRT is rejected, X's Media Studio page gives the error text and the checklist behind it. The error reads: "There was a problem uploading your subtitle (.srt) file," and X explains that "this means that there is likely an issue with the formatting of the file."
The four things it tells you to check, verbatim:
- Chronology — "Any end time needs to be before the next start time. All subtitle headers need to be in chronological order."
- Spaces — "Remove any unnecessary spaces that appear before a time code. Ensure there is one space before and one space after the "-->" in each time code."
- Timestamp — "A colon ":" is required between the hours, minutes, and seconds. A comma "," is required between seconds and milliseconds."
- Digits — "Time codes must have double digits in all values for hours, minutes, and seconds. Milliseconds need to have three digits."
Note what is not on that list: character encoding. X's four checks say nothing about UTF-8, byte order marks, or line endings, so treat encoding advice from elsewhere as unverified against X's documentation.
Check 3 is the one to re-read after any conversion: X asks for a colon between the hours, minutes and seconds, and a comma between the seconds and the milliseconds. A file that carries a different separator into an .srt extension conflicts with that check.
X publishes both a correct and an incorrect example on the same page, which is the fastest way to eyeball your own file. The correct one is formatted 00:00:06,000 --> 00:00:08,000, with a cue number on its own line above it. The incorrect one is 0:00:36.801--> 0:00:42.239, and in that same incorrect sample the block numbered 22 sits above the block numbered 21.
Gotchas that are not about the file format
- Scope: the Media Studio specifications open with their own disclaimer — "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."
- One file per video: X states, for Media Studio, "Currently we only support one subtitle file uploaded per video." Whether the web upload path has the same restriction is not stated.
- Language matching decides whether anyone sees your captions: "the subtitles will appear as an overlay atop the video when the subtitles language matches the language set on the viewing user's device... If the subtitles language is not the same as the language of the user, subtitles will not appear."
- Sound-off default: "By default, subtitles appear when the video's sound is not playing, and will be hidden when sound is playing." Viewers with subtitles enabled in device accessibility settings always see them.
- Preview will not show them: asked why an uploaded subtitle does not appear in the Media Studio preview player, X answers, "Correct. Subtitle files will only be shown once posted."
- Size: the
subtitlesmedia category is listed at 1 MB in the chunked upload documentation.
FAQ
Does X support VTT subtitle files?
X has not said so. text/vtt appears in the media_type enum of the API's initialize-upload schema, but the help centre pages about captions describe .srt only. Treat VTT as undocumented rather than confirmed either way, and check the official documentation for changes.
What subtitle file should I upload to an X video? SRT. It is the format named in X's caption help page and in the Media Studio encoding specifications, which list "CEA 608/708 embedded, .SRT sidecar."
Can I convert my VTT captions to SRT for X? Yes — the timing data is the same and only the formatting differs. Use VTT to SRT, then check the result against X's four rules above, particularly the comma before milliseconds.
Why won't my .srt file upload to X? X attributes the "There was a problem uploading your subtitle (.srt) file" error to formatting, and publishes four checks: chronology, spaces around the arrow, colon and comma placement in timestamps, and digit counts. Encoding is not among them.
Can I upload captions from the X mobile app? X's caption page ends with a note: "Currently this feature is available on web only." See more platform limits in our limits guides.
Sourced from X's help centre caption and Media Studio pages and from the X API media documentation, checked 16 September 2026. X publishes conflicting figures across its own pages — see X video file size limits for the side-by-side. Browser-based subtitle and video utilities: all Clapr tools.
