Skip to main content
POST https://xquik.com/api/v1/x/media
10 credits per call · All plans from $0.00012/creditA write that must sign in to your X account first adds 10 credits. Xquik refunds them if the sign-in fails. A sign-in that works keeps them, even if X then refuses the write. See the X sign-in fee.
Call POST /x/media. The route accepts one local file or hosted HTTPS media URL. Each request uses one connected X account. A completed upload returns a media ID and reusable mediaUrl. Skip this endpoint when a tweet already has public HTTPS media URLs. Call Create Tweet directly with those URLs.

Use the X (Twitter) API upload media workflow

Send multipart/form-data for a file. Send application/json for a hosted URL. Authenticate with an API key or OAuth bearer token. Add one Idempotency-Key per intended upload. Any HTTP client works.

Upload a hosted media URL

Both inputs return the same lifecycle record. Poll statusUrl after 202. Store mediaId, mediaUrl, the account, and the idempotency key.

Handle media types, large videos & multiple images

Supported media files include AVIF, GIF, JPEG, PNG, WebP, and MP4. Match the content type to the file. Use a public URL. Xquik rejects private and reserved addresses. The download timeout is 30 seconds. The file limit is 15,728,640 bytes. Xquik shrinks images over 5 MiB to fit X. GIFs and videos go to X unchanged. An unreadable image returns 415 unsupported_media_type. An image Xquik can’t shrink enough returns 413 media_too_large. Set is_long_video to true for MP4 files longer than 140 seconds. Xquik handles the chunked upload and media category. Send one request, then poll its lifecycle. For multiple images, call once per file. Collect up to 4 mediaId values. Send them together in Create Tweet media_ids. DMs accept exactly 1 media ID. Media IDs expire 24 hours after upload. Schedulers that post later store mediaUrl until send time. This endpoint does not schedule tweets.

Store the X (Twitter) API media upload receipt

Store the account, success, source reference, and idempotency key with each receipt. For replies, add reply_to_tweet_id in Create Tweet. Send mediaUrl values in media or mediaId values in media_ids, never both. Tweet and reply writes cost 30 credits, plus media surcharges. DM writes cost 10 credits.

Fix X (Twitter) media upload API errors

Fix invalid fields or content types after 400. Replace credentials after 401. Add credits after 402. Reconnect the X account after 403. Connect a missing account after 404. Keep the original action after 409. Replace unreachable or private URLs after 422 media_download_failed. Replace rejected media after other 422 errors. Honor Retry-After after 429. Check safeToRetry after 500 or 503.

Headers

Body

Response

Connect the requested account, then submit a newly approved write.

Durable write recovery

Send one unique Idempotency-Key per intended write. Replay the same account, target, payload, and media after a lost response. Keep the original key for that replay.
  1. Store id, the nested hash in request, billing, and statusUrl.
  2. Poll after Retry-After or pollAfterMs when terminal is false.
  3. Retry only when safeToRetry is true.
  4. Use a new key when nextAction.requiresNewIdempotencyKey is true.

200 terminal or 202 active

  • After HTTP 200, store the result and settled billing.
  • After HTTP 202, poll the same action. Never submit another write.
  • After HTTP 400, fix the named field. Use a new idempotency key.
  • After HTTP 401, fix authentication. Do not retry unchanged.
  • After HTTP 402, fund the account before another write.
  • After HTTP 403, reconnect the account.
  • After HTTP 409, keep the original action. Use a new key for new input.
  • After HTTP 422, fix the rejected request before retrying.
  • After HTTP 429, wait for Retry-After. Follow nextAction.
See Get Write Action Status for every lifecycle field and terminal state. That page also lists every billing field and retry rule.

Response examples

200 example

202 example

  • 400 { "error": "missing_idempotency_key", "message": "Idempotency-Key is required. Generate one unique key for this write.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true }
  • 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": "account_not_found", "message": "X account not found. Connect it first at /dashboard/x-accounts." }
  • 409 { "error": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true }
  • 413 { "error": "media_too_large", "message": "This image stays over X's size limit after shrinking. Send a smaller one." }
  • 415 { "error": "unsupported_media_type", "message": "Xquik couldn't read this image. Send a valid image file." }
  • 422 { "error": "x_rejected", "message": "X rejected this request. Check what you sent & the account on x.com before you try again." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 500 { "error": "x_write_failed", "message": "Write action failed unexpectedly. Contact support if this persists." }
  • 503 { "error": "write_tracking_unavailable", "message": "Write tracking unavailable. Try again.", "charged": false, "chargedCredits": "0", "retryable": true, "safeToRetry": true }