Upload Media API

Upload an image, GIF, or video to Twitter/X and get a media_id for tweets via API. $0.001 per call. GetXAPI media upload endpoint.

POST/twitter/media/upload

This endpoint costs $0.001 per API call.

Upload an image, GIF, or video to Twitter and receive a media_id you can attach to a tweet via Create Tweet.

Request Body

Field	Type	Required	Description
`auth_token`	string	Yes	User's auth token
`media_url`	string	Conditional	Public URL of the media to fetch and upload. Provide exactly one of `media_url` or `media_data`.
`media_data`	string	Conditional	Base64-encoded media bytes. Provide exactly one of `media_url` or `media_data`.
`media_type`	string	Conditional	MIME type (e.g. `image/png`, `image/gif`, `video/mp4`). Required when using `media_data`; auto-detected from `media_url` when possible.
`proxy`	string	No	Proxy URL (`http://`, `https://`, `socks5://`, or `socks4://`)

Notes

Returns a media_id (string) you pass in the media_ids array of Create Tweet.
Media IDs are short-lived — upload shortly before creating the tweet.
Supported: images (PNG, JPG, GIF, WEBP up to 5 MB), GIFs (up to 15 MB), videos (MP4 up to 512 MB).
For videos, the server runs the chunked INIT → APPEND → FINALIZE flow and waits for processing to complete.
media_type is required when sending media_data; for media_url we infer it from the response headers / file extension.

Response (200)

{
  "status": "success",
  "msg": "Media uploaded successfully",
  "data": {
    "media_id": "2058029045372379136",
    "media_type": "image/png",
    "size": 24531
  }
}

Error Responses

400 - No media provided

{
  "error": "Provide either media_url or media_data"
}

502 - Upload failed

{
  "error": "Media upload failed — Twitter did not return a media_id"
}

Examples

Upload by URL

curl -X POST "https://api.getxapi.com/twitter/media/upload" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_token": "your_auth_token",
    "media_url": "https://example.com/photo.jpg"
  }'

const response = await fetch("https://api.getxapi.com/twitter/media/upload", {
  method: "POST",
  headers: {
    Authorization: "Bearer API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    auth_token: "your_auth_token",
    media_url: "https://example.com/photo.jpg",
  }),
});
const data = await response.json();
console.log(data.data.media_id);

import requests

response = requests.post(
    "https://api.getxapi.com/twitter/media/upload",
    headers={"Authorization": "Bearer API_KEY"},
    json={
        "auth_token": "your_auth_token",
        "media_url": "https://example.com/photo.jpg",
    },
)
print(response.json()["data"]["media_id"])

Upload base64 bytes

curl -X POST "https://api.getxapi.com/twitter/media/upload" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_token": "your_auth_token",
    "media_data": "iVBORw0KGgo...",
    "media_type": "image/png"
  }'

Then attach to a tweet

curl -X POST "https://api.getxapi.com/twitter/tweet/create" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_token": "your_auth_token",
    "text": "Posted with a pre-uploaded image",
    "media_ids": ["2058029045372379136"]
  }'

Upload Media

On this page