Twitter media upload API for tweets, replies & DMs

{
  "object": "x_write_action",
  "id": "12345",
  "writeActionId": "12345",
  "action": "upload_media",
  "status": "success",
  "terminal": true,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12345",
  "pollAfterMs": null
}

{
  "object": "x_write_action",
  "id": "12346",
  "writeActionId": "12346",
  "action": "upload_media",
  "status": "dispatching",
  "terminal": false,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12346",
  "pollAfterMs": 2000
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check request fields.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "safeToRetry": true
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "account_needs_reauth",
  "message": "X account needs re-authentication. Re-add the account."
}

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

{
  "error": "idempotency_conflict",
  "message": "Idempotency-Key was already used with a different request.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "safeToRetry": true
}

{
  "error": "x_rejected",
  "message": "X rejected this request. Wait a few minutes and try again."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

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

{
  "error": "write_tracking_unavailable",
  "message": "Write tracking unavailable. Try again.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": true,
  "safeToRetry": true
}

POST

media

Twitter media upload API for tweets, replies & DMs

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

import requests

url = "https://xquik.com/api/v1/x/media"

payload = {
    "account": "<string>",
    "file": {},
    "url": "<string>",
    "is_long_video": True
}
headers = {
    "x-api-key": "<api-key>",
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<api-key>',
    'Idempotency-Key': '<idempotency-key>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({account: '<string>', file: {}, url: '<string>', is_long_video: true})
};

fetch('https://xquik.com/api/v1/x/media', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/media"

	payload := strings.NewReader("{\n  \"account\": \"<string>\",\n  \"file\": {},\n  \"url\": \"<string>\",\n  \"is_long_video\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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

Call POST /x/media. This Twitter API media upload route accepts one local file or hosted HTTPS media URL. A Twitter API upload media 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 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.

curl -X POST https://xquik.com/api/v1/x/media \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Idempotency-Key: media-upload-1895432178065391234" \
  -F "account=myxhandle" \
  -F "file=@/path/to/image.png" | jq

const form = new FormData();
form.append("account", "myxhandle");
form.append("file", new Blob([fileBuffer]), "image.png");

const response = await fetch("https://xquik.com/api/v1/x/media", {
  method: "POST",
  headers: {
    "x-api-key": "xq_YOUR_KEY_HERE",
    "Idempotency-Key": "media-upload-1895432178065391234",
  },
  body: form,
});
if (!response.ok) {
  throw new Error(await response.text());
}
const { mediaId, mediaUrl } = await response.json();

Upload a hosted media URL

curl -X POST https://xquik.com/api/v1/x/media \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Idempotency-Key: media-url-1895432178065391234" \
  -H "Content-Type: application/json" \
  -d '{"account": "myxhandle", "url": "https://example.com/image.png"}' | jq

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. Every media type requires validation before upload. Match the content type to the file. Use a public URL. Private and reserved addresses are rejected. The download timeout is 30 seconds. The file limit is 15,728,640 bytes. Set is_long_video to true for MP4 files longer than 140 seconds. Xquik handles the chunked upload and media category internally. Send one request, then poll its lifecycle. For multiple images, call once per file. Collect up to 4 mediaUrl values. Send them together in Create Tweet. DMs accept exactly one media ID. Schedulers store mediaUrl until send time. This endpoint does not schedule tweets.

Store the Twitter API media upload receipt

Output	Next request	Rule
`mediaUrl`	Tweet or reply `media`	Send up to 4 image URLs or 1 MP4 URL up to 100 MB.
`mediaId`	DM `media_ids`	Send exactly 1 media ID.

Store the account, success, source reference, and idempotency key with each receipt. For replies, add reply_to_tweet_id in Create Tweet. Never send media_ids to Create Tweet. Use public mediaUrl values. Tweet and reply writes cost 30 credits, plus media surcharges. DM writes cost 10 credits.

Fix 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

string

required

Your API key. OAuth bearer authentication is also supported. Generate a key from the dashboard.

string

required

Unique key for this intended write. Reuse it only for an exact network replay.

string

required

Use multipart/form-data when uploading a file. Use application/json when providing a URL.

Body

string

required

A connected X username or account ID. The account performs the upload.

binary

Required without url. Accepts AVIF, GIF, JPEG, PNG, WebP, or MP4.

string

Required without file. Provide a public HTTPS URL. AI agents and MCP clients can send URLs instead of binary uploads.

boolean

Multipart MP4 uploads only. Set true when the video exceeds 140 seconds. Defaults to false.

Response

404 Account not found

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

Durable write recovery

Send one unique Idempotency-Key per intended write. Reuse it only for the same account, target, payload, and media.

Store id, the nested hash in request, billing, and statusUrl.
Poll after Retry-After or pollAfterMs when terminal is false.
Trust safeToRetry and nextAction before any new write.

200 Terminal or 202 active

Store terminal results. Poll active actions without creating another write.

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. Preserve the same key.
After HTTP 500, retry only when safeToRetry is true.
After HTTP 503, poll while terminal is false.

See Get Write Action Status for every lifecycle field, terminal state, billing field, and retry rule.

{
  "object": "x_write_action",
  "id": "12345",
  "writeActionId": "12345",
  "action": "upload_media",
  "status": "success",
  "terminal": true,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12345",
  "pollAfterMs": null
}

{
  "object": "x_write_action",
  "id": "12346",
  "writeActionId": "12346",
  "action": "upload_media",
  "status": "dispatching",
  "terminal": false,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12346",
  "pollAfterMs": 2000
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check request fields.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "safeToRetry": true
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "account_needs_reauth",
  "message": "X account needs re-authentication. Re-add the account."
}

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

{
  "error": "idempotency_conflict",
  "message": "Idempotency-Key was already used with a different request.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "safeToRetry": true
}

{
  "error": "x_rejected",
  "message": "X rejected this request. Wait a few minutes and try again."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

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

{
  "error": "write_tracking_unavailable",
  "message": "Write tracking unavailable. Try again.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": true,
  "safeToRetry": true
}

Twitter media upload API for tweets, replies & DMs

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

import requests

url = "https://xquik.com/api/v1/x/media"

payload = {
    "account": "<string>",
    "file": {},
    "url": "<string>",
    "is_long_video": True
}
headers = {
    "x-api-key": "<api-key>",
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<api-key>',
    'Idempotency-Key': '<idempotency-key>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({account: '<string>', file: {}, url: '<string>', is_long_video: true})
};

fetch('https://xquik.com/api/v1/x/media', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/media"

	payload := strings.NewReader("{\n  \"account\": \"<string>\",\n  \"file\": {},\n  \"url\": \"<string>\",\n  \"is_long_video\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

Overview

X API

X write

Trends

Radar

Account

API keys

Guest wallets

Credits

X accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Twitter media upload API for tweets, replies & DMs

Use the Twitter API upload media workflow

Upload a hosted media URL

Handle media types, large videos & multiple images

Store the Twitter API media upload receipt

Fix Twitter media upload API errors

Headers

Body

Response

Durable write recovery

200 Terminal or 202 active

​Use the Twitter API upload media workflow

​Upload a hosted media URL

​Handle media types, large videos & multiple images

​Store the Twitter API media upload receipt

​Fix Twitter media upload API errors

​Headers

​Body

​Response

​Durable write recovery

​200 Terminal or 202 active

Use the Twitter API upload media workflow

Upload a hosted media URL

Handle media types, large videos & multiple images

Store the Twitter API media upload receipt

Fix Twitter media upload API errors

Headers

Body

Response

Durable write recovery

200 Terminal or 202 active