Skip to main content
POST
Twitter media downloader API for photos & video
Use this Twitter media downloader API with 1-50 tweet IDs or URLs. Download Twitter media from one tweet or a batch of 50. Each response contains a gallery of photos, videos, and GIFs.
1 credit per fresh tweet processed with media · cache hits are free · All plans from $0.00012/credit
This endpoint creates a saved media gallery from 1-50 tweet URLs or IDs. The response gives a galleryUrl plus cache or bulk counts. It does not return per-file downloads, file metadata, or an uploaded mediaId.

Headers

string
required
Your API key. You can also authenticate with an OAuth bearer token.
string
required
Must be application/json.

Body

Use tweetIds for bulk downloads. If tweetIds is present with at least 1 string value, the route uses bulk mode and ignores single-tweet fields. Otherwise, use tweetInput, tweetId, or tweetUrl for a single tweet.
string
Tweet URL or numeric tweet ID for a single download. Accepts x.com and twitter.com URL formats.
string
Numeric tweet ID alias for tweetInput. Use it when tweetInput is absent.
string
Tweet URL alias for tweetInput. Use it when both earlier fields are absent.
string[]
Array of tweet URLs or IDs for bulk download. Maximum 50 string items. The route skips invalid IDs. It fails only when no valid tweet IDs remain.

Media download handoff

Use this endpoint when your agent needs a saved gallery for tweet images, videos, or GIFs. Write one manifest row per request so downstream jobs can store the gallery link without treating it as an uploaded media ID or an individual media file URL.

Gallery URL

Store gallery_url from galleryUrl as the durable link for downloaded media.

Single tweet

Store requested_tweet_id, tweet_id, and cache_hit. cacheHit: true means the single-tweet request used cached media and is free.

Bulk result

Store requested_tweet_ids, successful_tweet_count from totalTweets, and media_item_count from totalMedia. totalTweets counts successful tweets with media after invalid or failed IDs are skipped.

Input mode

Send tweetIds for bulk. When it contains at least 1 string, bulk mode ignores tweetInput, tweetId, and tweetUrl.

Batch limit

Keep tweetIds at 50 items or fewer. Split larger backfills into multiple requests.

Write handoff

This endpoint creates a gallery download, not an uploaded media ID. Use Upload Media before DMs or hosted tweet assets.

Store a tweet media download manifest

Keep one manifest row per single or bulk request. A gallery URL represents the download result. A gallery URL is neither an uploaded media ID nor a direct asset URL. Use these outcomes when reconciling a download request:
  • cacheHit: true confirms a free cached single result.
  • cacheHit: false confirms a fresh single result.
  • If totalTweets is below the valid input count, review skipped Tweet IDs.
  • A 400 no_media response means the source tweet has no downloadable media.
  • Preserve rejected inputs while processing valid Tweet IDs.
  • Split more than 50 inputs into groups of 50 or fewer.
Fresh downloads cost 1 credit per tweet processed with media. Cached single downloads return cacheHit: true and are free. Bulk responses do not return freshCount; store the request IDs with totalTweets and totalMedia for reconciliation.

Response

200 OK (single)

string
Identifies the resolved tweet.
Links the shareable gallery containing all downloaded media.
boolean
Shows whether the cache supplied the media. Cached requests consume no credits.

200 OK (bulk)

Links the combined gallery containing media from all tweets.
number
Counts processed tweets with media.
number
Counts downloaded images, videos, and GIFs.

400 Invalid input

Missing, malformed, or non-JSON request body. Malformed JSON can also return invalid_json.

400 Invalid tweet ID

The provided tweet ID or URL could not be resolved to a valid tweet ID.

400 Too many tweets

The tweetIds array exceeds the 50-item limit. Split into multiple requests.

400 No media

The tweet does not contain any images, videos, or GIFs.

401 Unauthenticated

Supply a valid API key or OAuth bearer token.

402 Insufficient credits

The available balance cannot cover the download. Top up or subscribe from the dashboard billing page.

404 Tweet not found

The tweet ID is valid, but the tweet cannot be fetched or no longer exists.

429 Rate limit exceeded

The API key, user, or plan tier is sending requests too quickly. Respect the Retry-After header before retrying.

502 X API unavailable

The read service failed. Retry after a short delay.

424 Dependency failed

The opt-in normalized contract returns 424 when the read service fails. Send xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.

Twitter media downloader questions

How do I download Twitter media?

Copy the tweet link or numeric ID. Send it through tweetInput. The gallery can contain Twitter videos and GIFs plus images.

Can I save Twitter videos or GIFs on a phone?

Yes. Open the returned galleryUrl in a web browser. The API does not return direct per-file URLs.

Does this work like a browser extension?

No. This is a server-side API. Keep the API key or bearer token server-side.

Can I download Twitter video files directly?

No. This Twitter video downloader route creates a gallery. It does not expose per-file downloads or resolution controls.

Can I download media from many tweets?

Yes. Send 1-50 tweet IDs through tweetIds. The response returns one gallery with tweet and media counts.
First download is metered and counts toward your monthly credit allowance. Subsequent requests for the same tweet return cached URLs at no cost (cacheHit: true). All downloads are saved to your gallery at https://xquik.com/gallery.
This endpoint accepts an API key or OAuth bearer token. Keep either credential server-side.Related. Get Tweet to look up tweet details and metrics, or use the execute MCP tool for AI agent access.