Skip to main content
POST
/
x
/
media
Upload media API
curl --request POST \
  --url https://xquik.com/api/v1/x/media \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "account": "<string>",
  "file": {},
  "url": "<string>",
  "is_long_video": true
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.xquik.com/llms.txt

Use this file to discover all available pages before exploring further.

10 credits per call · All plans from $0.00012/credit
curl -X POST https://xquik.com/api/v1/x/media \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -F "account=myxhandle" \
  -F "file=@/path/to/image.png" | jq
URL-based upload (for AI agents and MCP clients): 
curl -X POST https://xquik.com/api/v1/x/media \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"account": "myxhandle", "url": "https://example.com/image.png"}' | jq

​
Media upload handoff

Use POST /x/media when an app, support queue, CRM, workflow tool, or AI agent needs to turn a local file or hosted HTTPS media URL into media that Xquik can attach to a tweet, reply, or DM.

mediaUrl

Store mediaUrl for tweet and reply attachments. Pass it in the media array on POST /x/tweets.

mediaId

Store mediaId for direct message attachments. Pass it as the only item in media_ids on POST /x/dm/{userId}.

success

Store success to confirm the upload completed before the next write call.

account

Store the account you submitted to audit which connected X account uploaded and sent the media.

Source input

Store the source URL or filename to reconcile generated images, support files, or CRM assets with the uploaded media.
For tweets with already-public image URLs or exactly 1 public MP4 video URL up to 100 MB, skip this endpoint and call POST /x/tweets directly with media. After uploading through this endpoint, call POST /x/tweets and pass media: ["<mediaUrl>"]. To post a media reply, also pass reply_to_tweet_id. Do not send media_ids to POST /x/tweets; that endpoint returns 400 unsupported_field and expects public media URLs. For DMs, call POST /x/dm/{userId} after upload and pass media_ids: ["<mediaId>"]. DMs accept exactly 1 uploaded media ID. For JSON URL upload, the URL must use HTTPS, resolve to a public address, return AVIF, GIF, JPEG, PNG, WebP, or MP4 content, finish within 30 seconds, and stay at or below 15,728,640 bytes. URL download failures return 422 media_download_failed; fix the URL or switch to multipart upload. Upload media costs 10 credits per upload call. Posting the tweet, posting the reply, or sending the DM is a separate 10-credit write call.

​
Headers

​
x-api-key
string
required
Your API key. Session cookie authentication is also supported. Generate a key from the dashboard.
​
Content-Type
string
required
Use multipart/form-data when uploading a file. Use application/json when providing a URL.

​
Body

​
account
string
required
The connected X account to upload media as. Must be a username you have connected to your Xquik account.
​
file
binary
The media file to upload. Required if url is not provided. Supported formats: AVIF, GIF, JPEG, PNG, WebP, MP4.
​
url
string
HTTPS URL to download media from. Required if file is not provided. The server fetches the file from this URL. Useful for AI agents and MCP clients that work with URLs instead of binary file uploads.
​
is_long_video
boolean
Multipart video uploads only. Set to true for video/mp4 files longer than 140 seconds. Defaults to false.

​
Response

​
mediaId
string
The uploaded media ID. Supply it as the only item in the media_ids array on POST /x/dm/{userId} when sending a direct message with media.
​
mediaUrl
string
A public media URL. Pass it in the media array on POST /x/tweets when creating a tweet with uploaded media.
​
success
boolean
Always true on success.
{
  "mediaId": "1893726451023847424",
  "mediaUrl": "https://media.xquik.com/uploads/1893726451023847424.png",
  "success": true
}
10 credits per call · All plans from $0.00012/credit
Use mediaUrl when creating tweets. Use mediaId as the only item in the media_ids array when sending a direct message.
Related endpoints: Create Tweet to post with the returned mediaUrl, or Send Direct Message to send a DM with one uploaded media item.
Last modified on May 15, 2026