Upload Media
/tw-v2/interaction/upload-media1 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| auth | string | required | Authentication token (auth_token cookie value) of the X account that will post the media |
| proxystringrequired | string | required | Proxy in format 'hostname:port@username:password' |
| mediaobjectrequired | object | required | One 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:
{
"data": {
"mediaId": "2100000000000000001",
"mediaKey": "3_2100000000000000001",
"type": "image",
"size": 245810,
"state": "succeeded",
"progressPercent": null,
"checkAfterSecs": null,
"expiresAfterSecs": 86400
}
}mediaId: Pass it asmedia_idin a post with media.mediaKey: X's media key, ornull.type:image,giforvideo.size: File size in bytes.state:succeededwhen the media is ready to post;pendingorin_progresswhile X is still processing it.progressPercent: Processing progress from 0 to 100, ornullwhen X doesn't report it.checkAfterSecs: Seconds to wait before checking/tw-v2/interaction/media-status.nullwhen the media is ready or X gives no wait time.expiresAfterSecs: Seconds until X discards the upload if no post uses it, ornull.
A video that is still processing after 30 seconds comes back with its progress and when to check again:
{
"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.
{
"statusCode": 400,
"message": "Request validation failed"
}TweetAPI is a third-party API and is not affiliated with X Corp.