Skip to main content
PATCH
Twitter profile picture API: update avatar images
Use this Twitter profile picture API to update one connected account’s avatar. Choose this Twitter API profile image route for automated avatar changes. A Twitter API update profile image request accepts a JPEG or PNG file. It may also use a fetchable HTTPS image URL. The maximum image size is 700 KB. X recommends a 400 × 400 pixel profile picture.

Update a Twitter profile picture through the API

Call PATCH /x/profile/avatar to replace the square profile image. Use Update Banner for the header image. Use Update Profile for names and other public text fields. This route never retrieves another user’s avatar.
10 credits per call · All plans from $0.00012/credit

Prepare a Twitter avatar image

Choose one direct file or one fetchable HTTPS URL. Never send both sources. Accept only JPEG or PNG images. Reject GIF, WebP, and files above 700 KB. Review the square crop before approval. Keep faces and important marks near the center. Use only images you own or may publish. Read X’s profile image guidance before uploading.

Automate a safe profile picture update

Create one idempotency key for the selected account and image. Reuse it only after an exact network interruption. Generate a new key after changing the image or account. A 200 response is terminal. Poll statusUrl after 202 until terminal becomes true. Never start another avatar update before that result.

Verify the updated Twitter profile image

After a terminal write, use Twitter Profile Lookup. Open its profilePicture URL. Compare the rendered avatar with the approved source. Review the public square crop. Keep the action ID and verification timestamp. X may return a profile image URL like https://pbs.twimg.com/profile_images/example.jpg.

Fix Twitter profile picture API errors

Fix invalid image fields after 400. Replace authentication after 401. Add credits after 402. Reconnect after 403. Connect a missing account after 404. Keep the original action after 409. Replace rejected media after 422. Honor Retry-After after 429. Check safeToRetry after 500 or 503.

Twitter profile picture API questions

How do I authenticate an avatar update?

Send an x-api-key header or OAuth bearer token. The account field selects the connected profile. Never place credentials inside an image URL.

Can I update several Twitter profile pictures in one request?

No. Each request updates one connected account. Give each request its own idempotency key. Wait for each account’s terminal result.

Can I use usernames or user IDs for avatar updates?

Yes. Set account to a connected username or numeric user ID. The selected user’s profile receives the new image. Verify that identity before uploading.

Can I update a Twitter profile image with Python or an SDK?

Yes. Call the REST API with import requests, as shown above. Generated SDKs can send the same multipart file, account, API key, and idempotency key.

Does this route retrieve Twitter profile pictures?

No. It changes one connected account’s avatar. Use Twitter Profile Lookup to retrieve a public profilePicture URL.

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 for file uploads or application/json for URL uploads. Most HTTP clients set the multipart boundary automatically.

Body

string
required
X username or account ID of your connected account to act as.
binary
Multipart upload file. Required unless url is provided. Accepted formats: JPEG, PNG. Maximum file size: 700 KB.
string
HTTPS image URL. Required unless file is provided. The URL must use HTTPS and remain directly fetchable.

Response

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.
  1. Store id, the nested hash in request, billing, and statusUrl.
  2. Poll after Retry-After or pollAfterMs when terminal is false.
  3. 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.