Upload media

10 credits per call · All plans from $0.00012/credit

Skip this endpoint when a tweet or reply already has public HTTPS image URLs or a public MP4 URL. Use POST /x/media only when Xquik must host a local file, validate a generated media URL, or return a mediaId for one-item DM media_ids. Tweets use the returned mediaUrl; DMs use the returned mediaId.

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

The file and URL examples both build the same handoff shape. Store media_id, media_url, dm_media_ids, dm_endpoint, and tweet_media_url; pass dm_media_ids only to POST /x/dm/{userId}, and pass tweet_media_url in the media array on POST /x/tweets.

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
}

{ "error": "invalid_input", "message": "Unsupported file format or missing required fields" }

Missing account, or neither file nor url provided, or the media is not a supported format (AVIF, GIF, JPEG, PNG, WebP, MP4).

{ "error": "unauthenticated", "message": "Missing or invalid API key" }

Missing or invalid API key.

{ "error": "no_subscription", "message": "No active subscription" }

An active subscription is required to upload media. Subscribe from the dashboard.

{ "error": "insufficient_credits", "message": "Insufficient credits" }

Insufficient credits for this operation. Top up your credit balance from the dashboard.

{ "error": "account_not_found", "message": "X account not found. Connect it first at /dashboard/account?tab=x-accounts." }

The specified account is not connected to your Xquik account. Connect it from the dashboard.

{ "error": "account_needs_reauth" }

The connected X account failed a recent login attempt and needs to be reconnected. Reconnect it from the dashboard.

{ "error": "account_restricted" }

The connected X account is locked, suspended, recovering, or temporarily restricted. Resolve the restriction on X before retrying.

{ "error": "x_content_too_long", "message": "..." }

X rejected the write or the media URL could not be downloaded. Possible codes: x_content_too_long, x_duplicate_action, x_account_suspended, x_account_protected, x_target_not_found, x_account_feature_required, x_rejected, media_download_failed (URL fetch path only - body.url not HTTPS, resolves to private IP, file too large, origin error, or timeout). See error handling for details.

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

The request hit an Xquik tier limit, or X throttled the upload. Possible codes: rate_limit_exceeded, x_rate_limited, or x_daily_limit. Respect the Retry-After header when present.

{ "error": "x_transient_error", "message": "..." }

A transient write service issue occurred. Safe to retry with exponential backoff.

{ "error": "x_write_failed", "message": "Write action failed unexpectedly. Contact support if this persists." }

The upload could not be completed. Retry after a short delay, then contact support if the failure persists.

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.

Documentation Index

​Media upload handoff

mediaUrl

mediaId

success

account

Source input

​Headers

​Body

​Response

Media upload handoff

Headers

Body

Response