Timeline & DMs
Twitter media downloader API for photos & video
Download images, videos, and animated GIFs from 1-50 tweets. Return a gallery URL and download metadata for bulk review. Includes API request examples.
- 200
- 400
- 401
- 402
- 404
- 424
- 429
- 502
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.
This endpoint creates a saved media gallery from 1-50 tweet URLs or IDs.
The response gives a
Missing, malformed, or non-JSON request body. Malformed JSON can also return
The provided tweet ID or URL could not be resolved to a valid tweet ID.
The
The tweet does not contain any images, videos, or GIFs.
Supply a valid API key or OAuth bearer token.
The available balance cannot cover the download. Top up or subscribe from the dashboard billing page.
The tweet ID is valid, but the tweet cannot be fetched or no longer exists.
The API key, user, or plan tier is sending requests too quickly. Respect the
The read service failed. Retry after a short delay.
The opt-in normalized contract returns 424 when the read service fails.
Send
1 credit per fresh tweet processed with media · cache hits are free · All plans from $0.00012/credit
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
UsetweetIds 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: trueconfirms a free cached single result.cacheHit: falseconfirms a fresh single result.- If
totalTweetsis below the valid input count, review skipped Tweet IDs. - A
400 no_mediaresponse 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.
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.
string
Links the shareable gallery containing all downloaded media.
boolean
Shows whether the cache supplied the media. Cached requests consume no credits.
200 OK (bulk)
string
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
invalid_json.
400 Invalid tweet ID
400 Too many tweets
tweetIds array exceeds the 50-item limit. Split into multiple requests.
400 No media
401 Unauthenticated
402 Insufficient credits
404 Tweet not found
429 Rate limit exceeded
Retry-After header before retrying.
502 X API unavailable
424 Dependency failed
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 throughtweetInput. The gallery can
contain Twitter videos and GIFs plus images.
Can I save Twitter videos or GIFs on a phone?
Yes. Open the returnedgalleryUrl 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 throughtweetIds.
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.- 200
- 400
- 401
- 402
- 404
- 424
- 429
- 502
Twitter media downloader API for photos & video