Twitter Video Downloader API (REST)

A simple JSON REST API for extracting and downloading media from public Twitter/X posts — video (MP4), GIFs, and images. This page documents both endpoints, auth, rate limits, the result shape, and error codes.

Short answer: call GET /api/extract?url=<TWEET_URL> to get media metadata and direct URLs, or GET /api/download?url=<TWEET_URL>&quality=1080p to stream the MP4 as a file.

GET /api/extract

Returns metadata plus every downloadable variant for a tweet. Pass the tweet URL as the url query parameter, or POST a JSON body {"url":"..."}.

curl "https://download-twitter-video.drummerduck.com/api/extract?url=https://x.com/user/status/1234567890"

const res = await fetch(
  "https://download-twitter-video.drummerduck.com/api/extract",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ url: "https://x.com/user/status/1234567890" }),
  },
);
const { ok, data } = await res.json();

A success response is { "ok": true, "data": <result> }. The result shape:

{
  "source": "twitter",
  "id": "1234567890",
  "url": "https://x.com/user/status/1234567890",
  "author": { "name": "User", "handle": "user", "avatar": "https://..." },
  "text": "the tweet text",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "thumbnail": "https://.../thumb.jpg",
  "media": [
    {
      "type": "video",
      "poster": "https://.../poster.jpg",
      "durationMs": 30000,
      "width": 1920,
      "height": 1080,
      "variants": [
        {
          "quality": "1080p",
          "width": 1920,
          "height": 1080,
          "bitrate": 2176000,
          "container": "mp4",
          "mimeType": "video/mp4",
          "url": "https://.../1080p.mp4"
        }
      ]
    }
  ],
  "engine": "..."
}

media[].type is "video", "gif" (a silent MP4 — see the GIF guide), or "image".

GET /api/download

Streams the MP4 back as a file attachment (with a Content-Disposition header), so a browser or client saves it directly.

curl -L "https://download-twitter-video.drummerduck.com/api/download?url=https://x.com/user/status/1234567890&quality=1080p&n=0" -o video.mp4

Parameters:

• url — the tweet URL (required).
• quality — matches a variant label such as 1080p or 720p. Defaults to the best video. See downloading in 1080p.
• n — the media index for multi-media tweets (default is the best video).

Authentication

Auth is optional. Send an API key to raise your limits:

curl -H "Authorization: Bearer <API_KEY>" \
  "https://download-twitter-video.drummerduck.com/api/extract?url=https://x.com/user/status/1234567890"

You can also pass the key as X-API-Key: <API_KEY>.

Rate limits

• Anonymous: 30 requests/hour and 100/day per IP.
• API key: higher limits (default 300/hour, 2000/day).

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Exceeding a limit returns HTTP 429 with a Retry-After header.

Errors

Failures return { "ok": false, "error": { "code": "...", "message": "..." } }.

{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Tweet not found" } }

| Code | Meaning | | --- | --- | | INVALID_URL | The URL isn't a valid tweet link | | NOT_FOUND | The tweet doesn't exist | | NO_MEDIA | The tweet has no downloadable media | | PROTECTED | The account is protected/private | | RATE_LIMITED | You hit a rate limit (HTTP 429) | | UPSTREAM_ERROR | Twitter returned an error |

Frequently asked questions

Do I need an API key?

No. The API works anonymously within the per-IP limits. A key just raises those limits.

Can I download GIFs and images through the API?

Yes. Check media[].type — "gif" items are silent MP4s and "image" items are photos.

Is there a tool for AI agents?

Yes — an MCP server wraps the same functionality for agents. Non-developers can use the web downloader or the how-to guide.

Only download public content you have the right to use, and respect copyright.