POST https://xquik.com/api/v1/x/media/download
Send 1 tweet ID or URL, or a list of them.
The route downloads media from one tweet or a batch.
Each response contains a gallery of photos, videos, and GIFs.
1 credit per fresh tweet processed with media · cache hits are freeAll 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
Body
UsetweetIds for bulk downloads. If tweetIds holds at least 1 string value, the route uses bulk mode. In bulk mode it ignores single-tweet fields. Otherwise, use tweetInput, tweetId, or tweetUrl for a single tweet.Save only chart posts
SendimageShows with the posts, & only the posts whose photos show it get saved.imageFilter.uncheckedlists posts without a safe photo & posts X can’t find. They cost nothing.- When no photo shows it, nothing is saved & nothing is billed. A single download answers with empty
items. A bulk download answers withtotalTweets0.
Media download handoff
Your agent may need a saved gallery for tweet images, videos, or GIFs. If so, use this endpoint. Write one manifest row per request. Later jobs can then store the gallery link. It is not an uploaded media ID or an individual media file URL.Gallery URL
Store
gallery_url from galleryUrl as the 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 the route skips invalid or failed IDs.Input mode
Send
tweetIds for bulk. When it contains at least 1 string, bulk mode ignores tweetInput, tweetId, and tweetUrl.Posts left over
A long
tweetIds list saves what fits in the call’s time. Send the posts in unprocessedTweetIds again. They cost nothing.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. - Keep rejected inputs while processing valid Tweet IDs.
- Send
unprocessedTweetIdsagain until the answer has none.
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)
200 OK (bulk)
400 Invalid input
{ "error": "invalid_input", "message": "Invalid request body" }
Missing, malformed, or non-JSON request body. Malformed JSON can also return invalid_json.400 Invalid tweet ID
{ "error": "invalid_tweet_id", "message": "Tweet ID is empty or invalid" }
Xquik could not resolve the provided tweet ID or URL to a valid ID.400 No media
{ "error": "no_media", "message": "Tweet has no downloadable media" }
The tweet does not contain any images, videos, or GIFs.401 Unauthenticated
{ "error": "unauthenticated", "message": "Missing or invalid API key" }
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
{ "error": "tweet_not_found", "message": "Tweet not found" }
The tweet ID is valid. Xquik cannot fetch that tweet, or it no longer exists.429 Rate limit exceeded
The API key, user, or plan tier is sending requests too fast. Respect theRetry-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. Sendxquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.X (Twitter) media downloader questions
How do I download X (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 X (Twitter) video files directly?
No. This route creates a gallery. It does not expose per-file downloads or resolution controls.Can I download media from many tweets?
Yes. Send the tweet IDs throughtweetIds.
The response returns one gallery with tweet and media counts.Xquik meters the first download against your monthly credit allowance. Later requests for the same tweet return cached URLs at no cost (
cacheHit: true). Xquik saves all downloads to your gallery at https://xquik.com/gallery.Response examples
- 400
{ "error": "invalid_input", "message": "Invalid input. Check the request body." } - 401
{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." } - 402
{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." } - 403
{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." } - 404
{ "error": "tweet_not_found", "message": "Tweet not found." } - 424
{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." } - 429
{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 } - 502
{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }