Skip to main content
This workflow returns an uploaded media ID for tweets, replies, and direct messages. It also returns a hosted media URL for tweet media arrays. Use it when a product, support, CRM, or AI agent system needs either. Xquik accepts local files with multipart/form-data and HTTPS media URLs with application/json. You may already have public image URLs or a public MP4 video URL. If so, skip POST /x/media for a tweet or reply. Pass those URLs in the media array on POST /x/tweets. Send up to 4 images or exactly 1 MP4 video up to 100 MB. Use POST /x/media to host local files, check generated URLs, or get a mediaId.
Need to post an MP4 tweet? If the MP4 is already a public HTTPS URL, skip upload. In that case call Create Tweet with media: ["https://example.com/video.mp4"]. For a local file, call POST /x/media first. Then pass the returned mediaId in media_ids on POST /x/tweets.

When to use this workflow

Upload a local file

Upload a local image, GIF, or MP4 with POST /x/media and multipart/form-data.

Upload generated media

Upload AI-generated media from a URL with POST /x/media and application/json.

Post tweets with public media URLs

Pass the URLs directly in the media array on POST /x/tweets.

Post tweets with media uploaded through Xquik

Pass returned mediaId values in the media_ids array on POST /x/tweets.

Post tweet replies with uploaded media

Pass media_ids plus reply_to_tweet_id on POST /x/tweets.

Send a DM with uploaded media

Pass returned mediaId as the only item in media_ids on POST /x/dm/{userId}.

Data you get

Media ID

mediaId is the uploaded media ID for tweet media_ids and one-item DM media_ids arrays. Media IDs are valid for 24 hours after upload.

Tweet media URL

mediaUrl is the public media URL for tweet media arrays.

Upload confirmation

success is true after upload completes.

Tweet confirmation

POST /x/tweets returns tweetId after Xquik confirms the media tweet or reply.

End-to-end media handoff

Use one checkpoint object after upload and the downstream tweet, reply, or DM write. Tweets and replies use the uploaded mediaId in media_ids. They can also take public mediaUrl values in media. DMs use the uploaded mediaId as the only media_ids item.

Upload checkpoint

Store returned mediaId, mediaUrl, success, source URL or filename, and the upload endpoint.

Tweet media checkpoint

Store media_ids or the public mediaUrl in media. Also store the returned tweetId, chargedCredits, and optional writeActionId.

Reply media checkpoint

Store reply_to_tweet_id, media_ids or public mediaUrl, returned tweetId, and pending confirmation state when present.

DM ID checkpoint

Store exactly one uploaded mediaId in media_ids, plus returned messageId and recipient ID.

Field boundary

Reject tweet handoffs that put uploaded media IDs in media. Also reject those that send both media and media_ids.

Audit row

Store upload, tweet, reply, and DM IDs together. Downstream systems can then reconcile each media path.

Step 1. Upload media by URL

AI agents, MCP clients, or workflow tools may hold generated image or MP4 URLs. If Xquik should validate and host one, use JSON URL upload. Some tweet-only workflows already have public image URLs or exactly 1 public MP4 URL. The MP4 can be up to 100 MB. For those workflows, call POST /x/tweets directly with media. The URL must use HTTPS and resolve to a public address. It must return a supported media content type within 30 seconds. It must stay under the 15,728,640-byte URL download cap.

URL upload checklist

HTTPS URL

Non-HTTPS URLs return 422 media_download_failed.

Public host

Xquik rejects private or reserved IP targets.

Supported content type

Xquik accepts AVIF, GIF, JPEG, PNG, WebP, and MP4.

Size cap

Larger URL downloads than 15,728,640 bytes return 422 media_download_failed.

30-second response window

Slow origins can time out before upload starts.

Step 2. Post a tweet or reply with mediaUrl or mediaId

POST /x/tweets accepts public media URLs in media. Send up to 4 images or exactly 1 MP4 video up to 100 MB. Use the mediaUrl returned by POST /x/media. Text-only tweet or reply writes cost 30 credits. Attached media adds 2 credits per started MB across all files.
To post a media reply, send the same media URL array and add reply_to_tweet_id.
Store the action id, request.hash, billing, result, original mediaUrl, and parent reply_to_tweet_id. Poll Get write action status while terminal is false. Retry only when safeToRetry is true, using a new Idempotency-Key. To skip the URL, send the returned mediaId in media_ids instead. Send up to 4 image IDs or exactly 1 video ID within 24 hours. Never send media and media_ids together.

Step 3. Send a DM with mediaId

POST /x/dm/{userId} accepts one uploaded media ID in media_ids. Use the mediaId returned by POST /x/media.
DMs accept exactly one uploaded media item. Send no media_ids field for text-only DMs. Store message_id, media_id, recipient, account, and send status in shared handoff rows. Keep full DM body text in private systems only.

JSON Lines handoff

For queues, CRM syncs, warehouse loads, or agent memory, write to xquik-media-handoff.jsonl. Write one record per upload and downstream write.

Media upload row

Tweet or reply row

DM media row

Use media_id for tweet and reply media_ids, or media_url for their media arrays. Use media_id for the single DM media_ids item.

Step 4. Upload a local file

Use multipart upload when your app has the file bytes. Supported formats are AVIF, GIF, JPEG, PNG, WebP, and MP4.
For MP4 files longer than 140 seconds, add is_long_video=true.

Cost and error handling

Upload media costs 10 credits per upload call. Posting a tweet or reply is a separate 30-credit create-tweet call before media surcharges. Sending the DM is a separate 10-credit write call.

Invalid input

Status 400. Error invalid_input. Check account, file type, file presence, URL presence, and is_long_video.

Billing or credits

Status 402. Errors no_subscription or insufficient_credits. Subscribe or top up credits before retrying.

Reconnect account

Status 403. Error account_needs_reauth. Reconnect the X account from the dashboard.

Media download failed

Status 422. Error media_download_failed. Use an HTTPS URL that returns a supported media file. Or switch to multipart upload.

Media ID not found

Status 400. Error media_not_uploaded. Upload the file again from the posting account, then post within 24 hours.

Rate limit or temporary failure

Status 429 or 503. Retry with exponential backoff and respect Retry-After when present.

Handoff checklist

Tweet workflow

Save mediaId and pass it to POST /x/tweets in media_ids, or pass mediaUrl in media.

Reply workflow

Save the parent tweet ID, mediaId or mediaUrl, returned tweetId, and any writeActionId.

DM workflow

Save mediaId and pass it to POST /x/dm/{userId} as one media_ids item.

JSON Lines

Store upload, tweet, reply, or DM handoff rows in xquik-media-handoff.jsonl with media_id and media_url.

Agent workflow

JSON URL upload validates or hosts a generated URL, or returns a DM mediaId. Use it only when the agent needs one of those. For tweet-only public URLs, pass them directly to POST /x/tweets.

File workflow

Prefer multipart upload when your app owns the file bytes.