X write
Twitter profile picture API: update avatar images
Use the Twitter profile picture API to update an X avatar. Upload a JPEG or PNG file, or provide an HTTPS image URL, with authentication and polling examples.
- 200
- 202
- 400
- 401
- 402
- 403
- 404
- 409
- 422
- 429
- 500
- 503
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
CallPATCH /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. PollstatusUrl 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 itsprofilePicture 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. HonorRetry-After after 429. Check safeToRetry after 500 or 503.
Twitter profile picture API questions
How do I authenticate an avatar update?
Send anx-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. Setaccount 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 withimport 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 publicprofilePicture 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
- 404 Account not found
Connect the requested account, then submit a newly approved write.
Durable write recovery
- Store
id, the nestedhashinrequest,billing, andstatusUrl. - Poll after
Retry-AfterorpollAfterMswhenterminalisfalse. - Trust
safeToRetryandnextActionbefore 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 forRetry-After. Preserve the same key. - After HTTP
500, retry only whensafeToRetryistrue. - After HTTP
503, poll whileterminalisfalse.
- 200
- 202
- 400
- 401
- 402
- 403
- 404
- 409
- 422
- 429
- 500
- 503
Twitter profile picture API: update avatar images