Skip to content

Upload Media

POST/tw-v2/interaction/upload-media

1 API unit per call · How billing works

Description

Upload a photo, GIF or video to use in a later post.

Usage notes

Send one file in media, either as url or as data with type. The accepted types and size limits are the same as for /tw-v2/interaction/create-post-with-media: photos up to 5 MB, GIFs up to 15 MB, and videos up to 512 MB and 140 seconds. A file over its size limit returns 413, and a longer video returns 400. A url must use HTTPS and point to a public address, and a url that can't be fetched returns 422. The whole request body can be at most 30 MB, so send larger files as a url rather than as data.

After the file is uploaded, the request waits up to 30 seconds while it is processed, so set your client timeout above 30 seconds, with extra time for large files. Photos, and GIFs and videos that finish processing within that time, come back with state set to succeeded and are ready to post. Media that is still processing comes back with state set to pending or in_progress and a checkAfterSecs value; check it with /tw-v2/interaction/media-status until state is succeeded. A file X rejects returns 400 with X's reason.

To post the media, pass mediaId as media_id in the media array of any endpoint that posts with media: /tw-v2/interaction/create-post-with-media, /tw-v2/interaction/reply-post-with-media, /tw-v2/interaction/create-community-post-with-media, /tw-v2/interaction/reply-community-post-with-media or /tw-v2/interaction/create-community-quote-with-media. Send the post with the same authToken, and preferably the same proxy. Only the account that uploaded the media can use it, and X discards an unused upload when expiresAfterSecs runs out.

Each upload costs one API unit. 400, 401, 403, 409, 422, 429 and 5xx errors are free.

Request Body

ParameterDescription
authTokenstringrequiredAuthentication token (auth_token cookie value) of the X account that will post the media
proxystringrequiredProxy in format 'hostname:port@username:password'
mediaobjectrequiredOne media object: {url: string} or {data: string, type: string}. Use only one source.

Code Examples

const body = {
  authToken: 'YOUR_AUTH_TOKEN',
  proxy: 'proxy.example.com:8080@username:password',
  media: {
    url: 'https://example.com/sample.jpg'
  }
};

const response = await fetch('https://api.tweetapi.com/tw-v2/interaction/upload-media', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

const data = await response.json();
console.log(data);

Response

Success Response (200 OK)

Synthetic example:

200
{
  "data": {
    "mediaId": "2100000000000000001",
    "mediaKey": "3_2100000000000000001",
    "type": "image",
    "size": 245810,
    "state": "succeeded",
    "progressPercent": null,
    "checkAfterSecs": null,
    "expiresAfterSecs": 86400
  }
}
  • mediaId: Pass it as media_id in a post with media.
  • mediaKey: X's media key, or null.
  • type: image, gif or video.
  • size: File size in bytes.
  • state: succeeded when the media is ready to post; pending or in_progress while X is still processing it.
  • progressPercent: Processing progress from 0 to 100, or null when X doesn't report it.
  • checkAfterSecs: Seconds to wait before checking /tw-v2/interaction/media-status. null when the media is ready or X gives no wait time.
  • expiresAfterSecs: Seconds until X discards the upload if no post uses it, or null.

A video that is still processing after 30 seconds comes back with its progress and when to check again:

200
{
  "data": {
    "mediaId": "2100000000000000002",
    "mediaKey": "7_2100000000000000002",
    "type": "video",
    "size": 48104220,
    "state": "in_progress",
    "progressPercent": 40,
    "checkAfterSecs": 5,
    "expiresAfterSecs": 86399
  }
}

Errors

Errors return { statusCode, message } with a non-2xx HTTP status.

400
{
  "statusCode": 400,
  "message": "Request validation failed"
}

TweetAPI is a third-party API and is not affiliated with X Corp.