Tweet subtitles API for X video captions and text

{
  "subtitles": {
    "tweetId": "2104593672624886205",
    "tracks": [
      {
        "mediaKey": "13_2104593621043314689",
        "language": "en",
        "name": "Planetary Defenders_Caption.en_US.srt",
        "autoGenerated": false,
        "url": "https://video.twimg.com/subtitles/amplify_video/2104593621043314689/0/-FdxBBY2iGcoP5wb.vtt"
      }
    ]
  }
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "tweet_not_found",
  "message": "Tweet not found. Check the tweet ID."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

GET

tweets

{id}

subtitles

Tweet subtitles API for X video captions and text

curl --request GET \
  --url https://xquik.com/api/v1/x/tweets/{id}/subtitles

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/tweets/{id}/subtitles"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "subtitles": {
    "tweetId": "<string>",
    "tracks": [
      {
        "mediaKey": "<string>",
        "language": "<string>",
        "name": "<string>",
        "autoGenerated": true,
        "url": "<string>",
        "text": "<string>",
        "truncated": true,
        "cues": [
          {}
        ]
      }
    ]
  }
}

1 credit when a track comes back · All plans from $0.00012/credit

Tweet subtitles returns the caption tracks of one public tweet’s videos. The endpoint is GET /api/v1/x/tweets/{id}/subtitles.

curl https://xquik.com/api/v1/x/tweets/2104593672624886205/subtitles \
  -H "x-api-key: xq_your_api_key_here" | jq

const tweetId = "2104593672624886205";
const response = await fetch(`https://xquik.com/api/v1/x/tweets/${tweetId}/subtitles`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const { subtitles } = await response.json();
const transcriptRows = subtitles.tracks.map((track) => ({
  tweet_id: subtitles.tweetId,
  media_key: track.mediaKey ?? null,
  language: track.language ?? null,
  auto_generated: track.autoGenerated,
  cue_count: track.cues.length,
  transcript: track.text,
}));

process.stdout.write(`${JSON.stringify(transcriptRows)}\n`);

import json
import requests

tweet_id = "2104593672624886205"
response = requests.get(
    f"https://xquik.com/api/v1/x/tweets/{tweet_id}/subtitles",
    headers={"x-api-key": "xq_your_api_key_here"},
)
subtitles = response.json()["subtitles"]
transcript_rows = [
    {
        "tweet_id": subtitles["tweetId"],
        "media_key": track.get("mediaKey"),
        "language": track.get("language"),
        "auto_generated": track["autoGenerated"],
        "cue_count": len(track["cues"]),
        "transcript": track["text"],
    }
    for track in subtitles["tracks"]
]
print(json.dumps(transcript_rows))

Use GET /x/tweets/{id}/subtitles when you need what a tweet’s video says as text. Each track holds its language, its timed cues, and the full text as one line. A call that returns a track costs 1 credit. A tweet without captions costs nothing.

Build a transcript from the tracks

Read text for the whole transcript as one line. Read cues for timed lines, to show beside a player or to cut clips. A video can hold several tracks, one per language. Pick a track by language. autoGenerated is true when X transcribed the audio itself. An uploaded caption file has autoGenerated: false and its file name in name. A long video splits its captions into files. Xquik reads the first 50 files of a track and sets truncated to true past that. A tweet with no video, or a video without captions, returns "tracks": [].

Path parameters

string

required

Post ID or URL-encoded post URL, such as x.com/nasa/status/20. See path IDs.

Headers

string

Full account key. Sessions and OAuth also work.

string

Bearer xq_your_guest_key_here for paid_reads.

Response

200 OK

object

The caption tracks of the tweet’s videos. Subtitles object fields.

string

ID of the tweet.

object[]

Caption tracks. Empty when no video has captions. Track object fields.

string

Media key of the video, as media rows carry it.

string

Language code of the track, in lowercase.

string

Track name the uploader or X gave it.

boolean

true when X transcribed the audio itself.

string

Link to the track’s first WebVTT file.

string

Every cue’s text in order, as one line.

boolean

true when the track holds more than 50 caption files. The cues then cover the first 50.

object[]

Timed captions in order. Each cue has startMs and endMs in milliseconds, and text with a line break between lines.

{
  "subtitles": {
    "tweetId": "2104593672624886205",
    "tracks": [
      {
        "mediaKey": "13_2104593621043314689",
        "language": "en",
        "name": "Promo Vid Version 6 - Planetary Defenders - This Is Not an Exercise_Caption.en_US.srt",
        "autoGenerated": false,
        "url": "https://video.twimg.com/subtitles/amplify_video/2104593621043314689/0/-FdxBBY2iGcoP5wb.vtt",
        "text": "This asteroid 2024 YR4 might get interesting. There was a chance that it could impact Earth.",
        "truncated": false,
        "cues": [
          {
            "startMs": 0,
            "endMs": 3370,
            "text": "This asteroid\n2024 YR4 might get interesting."
          },
          {
            "startMs": 3403,
            "endMs": 6406,
            "text": "There was a chance that it could impact\nEarth."
          }
        ]
      }
    ]
  }
}

400 Invalid tweet ID

{ "error": "invalid_tweet_id" }

The provided tweet ID is empty or not a valid format.

401 Unauthenticated

{ "error": "unauthenticated" }

Missing or invalid API key. Check the x-api-key header value.

402 Payment required

Account keys get account options. Guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.

404 Tweet not found

{ "error": "tweet_not_found" }

X has no such tweet. The author may have deleted it, or the account is private.

502 X API unavailable

{ "error": "x_api_unavailable" }

The read service returned an error. Retry after a short delay.

503 Service busy

{ "error": "x_api_unavailable" }

X did not serve a caption file in time, or Xquik is busy. Retry after a short delay. The request costs nothing.

429 Rate limit exceeded

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

You exceeded your tier rate limit. Wait for the Retry-After header before retrying.

424 Dependency failed

{ "error": "x_api_unavailable" }

The normalized v1 response contract can return 424 when the read service is unavailable.

Tweet subtitles API questions

How do I get the transcript of a Twitter video with an API?

Call GET /x/tweets/{id}/subtitles with the tweet ID or URL. Read subtitles.tracks[0].text for the transcript.

Does it work for videos without uploaded captions?

Yes, when X transcribed the audio itself. Those tracks have autoGenerated: true. A video X has no captions for returns no track.

Which format are the captions in?

Each cue has a start and an end in milliseconds, and its text. url links to the track’s first WebVTT file on X’s video host.

How much does a tweet’s subtitles call cost?

A call that returns at least 1 track costs 1 credit. A tweet without captions costs nothing. A refused or failed request costs nothing.

Does Xquik transcribe the audio?

No. Xquik reads the caption tracks X serves with the video.

Does this replace X’s official API?

No. This page documents Xquik, an independent third-party service. It does not document X’s official API.

Next steps. Get tweet reads the tweet’s fields as JSON, or Download media saves its photos and videos.

{
  "subtitles": {
    "tweetId": "2104593672624886205",
    "tracks": [
      {
        "mediaKey": "13_2104593621043314689",
        "language": "en",
        "name": "Planetary Defenders_Caption.en_US.srt",
        "autoGenerated": false,
        "url": "https://video.twimg.com/subtitles/amplify_video/2104593621043314689/0/-FdxBBY2iGcoP5wb.vtt"
      }
    ]
  }
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "tweet_not_found",
  "message": "Tweet not found. Check the tweet ID."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

Tweet subtitles API for X video captions and text

curl --request GET \
  --url https://xquik.com/api/v1/x/tweets/{id}/subtitles

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/tweets/{id}/subtitles"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "subtitles": {
    "tweetId": "<string>",
    "tracks": [
      {
        "mediaKey": "<string>",
        "language": "<string>",
        "name": "<string>",
        "autoGenerated": true,
        "url": "<string>",
        "text": "<string>",
        "truncated": true,
        "cues": [
          {}
        ]
      }
    ]
  }
}

Overview

X API

X write

Trends

Radar

Account

API keys

Guest wallets

Credits

X accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Tweet subtitles API for X video captions and text

Build a transcript from the tracks

Path parameters

Headers

Response

200 OK

400 Invalid tweet ID

401 Unauthenticated

402 Payment required

404 Tweet not found

502 X API unavailable

503 Service busy

429 Rate limit exceeded

424 Dependency failed

Tweet subtitles API questions

How do I get the transcript of a Twitter video with an API?

Does it work for videos without uploaded captions?

Which format are the captions in?

How much does a tweet’s subtitles call cost?

Does Xquik transcribe the audio?

Does this replace X’s official API?

​Build a transcript from the tracks

​Path parameters

​Headers

​Response

​200 OK

​400 Invalid tweet ID

​401 Unauthenticated

​402 Payment required

​404 Tweet not found

​502 X API unavailable

​503 Service busy

​429 Rate limit exceeded

​424 Dependency failed

​Tweet subtitles API questions

​How do I get the transcript of a Twitter video with an API?

​Does it work for videos without uploaded captions?

​Which format are the captions in?

​How much does a tweet’s subtitles call cost?

​Does Xquik transcribe the audio?

​Does this replace X’s official API?

Build a transcript from the tracks

Path parameters

Headers

Response

200 OK

400 Invalid tweet ID

401 Unauthenticated

402 Payment required

404 Tweet not found

502 X API unavailable

503 Service busy

429 Rate limit exceeded

424 Dependency failed

Tweet subtitles API questions

How do I get the transcript of a Twitter video with an API?

Does it work for videos without uploaded captions?

Which format are the captions in?

How much does a tweet’s subtitles call cost?

Does Xquik transcribe the audio?

Does this replace X’s official API?