Upload an image

Parameters

• cookiebody · string · required

  Cookie header of your own logged-in X session. Must contain auth_token and ct0; guest_id is used when present.

• proxybody · string · required

  Your proxy, format http://user:pass@host:port. The requests to X go out through it. Used only for this request.

• mediabody · string (base64) · required

  The image file, base64-encoded. JPEG, PNG or WebP up to 5 MB, GIF up to 15 MB; at most 8192 x 8192 pixels.

• media_typebody · string · optional

  MIME type, e.g. image/jpeg or image/png. Optional: the API detects the type from the file's bytes and uses the detected type if this is missing or wrong.

Body parameters are sent as a JSON object with Content-Type: application/json.

Notes

• The response field you need is media_id_string inside response.
• Limits (X): JPEG, PNG, WebP up to 5 MB; GIF up to 15 MB; at most 8192 x 8192 pixels. BMP, TIFF and other formats are refused. For videos use /client/media/video.

Example request

curl -X POST 'https://api.twittrapi.com/client/media' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"cookie":"auth_token=...; ct0=...","proxy":"http://user:pass@host:port","media":"<base64>","media_type":"image/jpeg"}'

import httpx

resp = httpx.post(
    "https://api.twittrapi.com/client/media",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    json={
        "cookie": "auth_token=...; ct0=...",
        "proxy": "http://user:pass@host:port",
        "media": "<base64>",
        "media_type": "image/jpeg",
    },
    timeout=60,
)
print(resp.status_code, resp.json())

const resp = await fetch("https://api.twittrapi.com/client/media", {
  method: "POST",
  headers: { "X-API-KEY": process.env.TWITTRAPI_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    cookie: "auth_token=...; ct0=...",
    proxy: "http://user:pass@host:port",
    media: "<base64>",
    media_type: "image/jpeg",
  }),
});
console.log(resp.status, await resp.json());

Base URL https://api.twittrapi.com, key in the X-API-KEY header. The SDKs do not wrap account actions, so the examples are plain HTTP calls.

Response

Wrapper built by the API: {"status_code": <X status>, "response": "<X response body as a string>"}. The HTTP status is X's status when X answered 4xx or 5xx, otherwise 200. Parse response a second time to get X's JSON.

Simple format (?format=simple or X-Response-Format: simple): {data: {mediaId, mediaKey, expiresAfterSecs}}. Pass mediaId in media_ids of /client/create or /client/reply. When X reports an error inside the wrapper (for example a tweet that is already liked), the usual wrapper is returned unchanged. Schema.

{
  "status_code": 201,
  "response": "{\"media_id\":2109885561359986688,\"media_id_string\":\"2109885561359986688\",\"media_key\":\"1_2109885561359986688\",\"size\":1330,\"expires_after_secs\":86400,\"image\":{\"image_type\":\"image/jpeg\",\"w\":32,\"h\":11}}"
}

{
  "data": {
    "mediaId": "2109885561359986688",
    "mediaKey": "1_2109885561359986688",
    "expiresAfterSecs": 86400
  }
}

In the raw format, field names and nesting come from X and can change without notice. See Response format; the simple format keeps a fixed schema.

Errors

• 400The body is not valid JSON.
• 422A required field is missing (including proxy), an ID is not numeric, or the cookie has no ct0. Also: the account is suspended, X rejected the session, or the text was already posted.
• 407The proxy is unreachable or timed out.
• 400The file breaks X's limits (not JPEG, PNG, GIF or WebP; over 5 MB, or 15 MB for a GIF; over 8192 x 8192 pixels; or a damaged image header). Checked before anything is sent to X, refunded. The error names the limit and the file's value, e.g. "Banner must be between 200x100 and 8192x8192 pixels (got 120x60)" or "Profile photo must be at most 2 MB (got 3.4 MB)".
• 422media is not valid base64.
• X'sAny status X answers with (for example 401, 403, 404): passed through with X's body.

Errors every endpoint can return (401, 402, 403, 404, 408, 409, 429, 5xx), and which of them are charged, are on the Errors page. Calls that fail with 400, 408, 409 or a 5xx error are refunded.