Twitter profile banner API: update header images

{
  "object": "x_write_action",
  "id": "12345",
  "writeActionId": "12345",
  "action": "update_banner",
  "status": "success",
  "terminal": true,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12345",
  "pollAfterMs": null
}

{
  "object": "x_write_action",
  "id": "12346",
  "writeActionId": "12346",
  "action": "update_banner",
  "status": "dispatching",
  "terminal": false,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12346",
  "pollAfterMs": 2000
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check request fields.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "safeToRetry": true
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "account_needs_reauth",
  "message": "X account needs re-authentication. Re-add the account."
}

{
  "error": "account_not_found",
  "message": "X account not found. Connect it first at /dashboard/account?tab=x-accounts."
}

{
  "error": "idempotency_conflict",
  "message": "Idempotency-Key was already used with a different request.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "safeToRetry": true
}

{
  "error": "x_rejected",
  "message": "X rejected this request. Wait a few minutes and try again."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_write_failed",
  "message": "Write action failed unexpectedly. Contact support if this persists."
}

{
  "error": "write_tracking_unavailable",
  "message": "Write tracking unavailable. Try again.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": true,
  "safeToRetry": true
}

PATCH

profile

banner

Twitter profile banner API: update header images

curl --request PATCH \
  --url https://xquik.com/api/v1/x/profile/banner \
  --header 'Content-Type: <content-type>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "account": "<string>",
  "file": {},
  "url": "<string>"
}
'

import requests

url = "https://xquik.com/api/v1/x/profile/banner"

payload = {
    "account": "<string>",
    "file": {},
    "url": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "<content-type>"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<api-key>',
    'Idempotency-Key': '<idempotency-key>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({account: '<string>', file: {}, url: '<string>'})
};

fetch('https://xquik.com/api/v1/x/profile/banner', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/profile/banner"

	payload := strings.NewReader("{\n  \"account\": \"<string>\",\n  \"file\": {},\n  \"url\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

Use this Twitter profile banner API to update one connected account’s header image. Upload a JPEG or PNG file, or provide a fetchable HTTPS image URL. The maximum file size is 2 MB. X recommends 1500 × 500 pixels for profile banners. Call PATCH /x/profile/banner to replace the wide header image. Use Update Avatar for the profile picture. Use Update Profile for names and other public text fields. This route never retrieves another user’s banner.

10 credits per call · All plans from $0.00012/credit

curl -X PATCH https://xquik.com/api/v1/x/profile/banner \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Idempotency-Key: banner-update-1895432178065391234" \
  -F "account=myxaccount" \
  -F "file=@banner.png" | jq

const fs = require("fs");
const FormData = require("form-data");

const form = new FormData();
form.append("account", "myxaccount");
form.append("file", fs.createReadStream("banner.png"));

const response = await fetch("https://xquik.com/api/v1/x/profile/banner", {
  method: "PATCH",
  headers: {
    "x-api-key": "xq_YOUR_KEY_HERE",
    "Idempotency-Key": "banner-update-1895432178065391234",
  },
  body: form,
});
const data = await response.json();

import requests

with open("banner.png", "rb") as f:
    response = requests.patch(
        "https://xquik.com/api/v1/x/profile/banner",
        headers={
            "x-api-key": "xq_YOUR_KEY_HERE",
            "Idempotency-Key": "banner-update-1895432178065391234",
        },
        files={"file": ("banner.png", f, "image/png")},
        data={"account": "myxaccount"},
    )
data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func main() {
    var buf bytes.Buffer
    writer := multipart.NewWriter(&buf)
    writer.WriteField("account", "myxaccount")

    file, err := os.Open("banner.png")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    part, err := writer.CreateFormFile("file", "banner.png")
    if err != nil {
        panic(err)
    }
    io.Copy(part, file)
    writer.Close()

    req, err := http.NewRequest("PATCH", "https://xquik.com/api/v1/x/profile/banner", &buf)
    if err != nil {
        panic(err)
    }
    req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")
    req.Header.Set("Idempotency-Key", "banner-update-1895432178065391234")
    req.Header.Set("Content-Type", writer.FormDataContentType())

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
        panic(err)
    }
    fmt.Println(data)
}

curl -X PATCH https://xquik.com/api/v1/x/profile/banner \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Idempotency-Key: banner-url-update-1895432178065391234" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "myxaccount",
    "url": "https://example.com/banner.png"
  }' | jq

Use a 1500 × 500 pixel canvas. This Twitter banner size has a 3:1 aspect ratio. These Twitter profile banner dimensions match X’s recommended header dimensions. The Twitter profile banner size must remain at 2 MB or smaller. Preserve high resolution while meeting that file size. Accept only JPEG or PNG image formatting. This route does not support animated GIFs. Export JPEG or PNG with your design tool or Twitter header template. Review every template export before uploading. Read X’s profile banner guidance for current layout recommendations. Preview the banner on desktop and a mobile device. The profile picture can cover the bottom left corner. Keep faces, logos, and text outside that area. Different banner sizes or crops can hide important artwork. Validate the Twitter header size before queueing the write. A saved 1500 x 500 pixels template can save time on recurring updates. Keep one perfectly sized source for each approved campaign. Export banner images from that source instead of resizing previous uploads. Record the header dimensions and final file size beside the source. A social media platform preview cannot replace the desktop and mobile checks above. Keep the account’s online presence consistent with approved logos and colors. Check the image size before upload. Do not assume a banner will boost engagement. Measure profile visits and follows separately. Create one idempotency key for the selected account and banner. 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. After a terminal write, use Twitter Profile Lookup. Open its profileBannerUrl value. Compare the rendered header with the approved source. Check desktop and mobile crops. Store the action ID and verification timestamp.

Profile banner update column	Request or response source	Review rule
Acting X account	Request `account`	Confirm the intended profile.
Uploaded file	Request `file`	Accept JPEG or PNG up to 2 MB.
Image URL	Request `url`	Use one fetchable HTTPS source.
Source choice	`file` or `url`	Send exactly one image source.
Idempotency key	Request header	Change it after editing the image.
Write action ID	Response `id`	Poll the matching lifecycle record.
Profile result	Later profile lookup	Confirm the public banner URL.

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.

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: 2 MB.

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

Send one unique Idempotency-Key per intended write. Reuse it only for the same account, target, payload, and media.

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

{
  "object": "x_write_action",
  "id": "12345",
  "writeActionId": "12345",
  "action": "update_banner",
  "status": "success",
  "terminal": true,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12345",
  "pollAfterMs": null
}

{
  "object": "x_write_action",
  "id": "12346",
  "writeActionId": "12346",
  "action": "update_banner",
  "status": "dispatching",
  "terminal": false,
  "retryable": false,
  "safeToRetry": false,
  "statusUrl": "/api/v1/x/write-actions/12346",
  "pollAfterMs": 2000
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check request fields.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "safeToRetry": true
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "account_needs_reauth",
  "message": "X account needs re-authentication. Re-add the account."
}

{
  "error": "account_not_found",
  "message": "X account not found. Connect it first at /dashboard/account?tab=x-accounts."
}

{
  "error": "idempotency_conflict",
  "message": "Idempotency-Key was already used with a different request.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": false,
  "safeToRetry": true
}

{
  "error": "x_rejected",
  "message": "X rejected this request. Wait a few minutes and try again."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_write_failed",
  "message": "Write action failed unexpectedly. Contact support if this persists."
}

{
  "error": "write_tracking_unavailable",
  "message": "Write tracking unavailable. Try again.",
  "charged": false,
  "chargedCredits": "0",
  "retryable": true,
  "safeToRetry": true
}

Twitter profile banner API: update header images

curl --request PATCH \
  --url https://xquik.com/api/v1/x/profile/banner \
  --header 'Content-Type: <content-type>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "account": "<string>",
  "file": {},
  "url": "<string>"
}
'

import requests

url = "https://xquik.com/api/v1/x/profile/banner"

payload = {
    "account": "<string>",
    "file": {},
    "url": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "<content-type>"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<api-key>',
    'Idempotency-Key': '<idempotency-key>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({account: '<string>', file: {}, url: '<string>'})
};

fetch('https://xquik.com/api/v1/x/profile/banner', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/profile/banner"

	payload := strings.NewReader("{\n  \"account\": \"<string>\",\n  \"file\": {},\n  \"url\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

Overview

X API

X write

Trends

Radar

Account

API keys

Guest wallets

Credits

X accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Twitter profile banner API: update header images

Update a Twitter profile banner through the API

Prepare Twitter profile banner dimensions

Automate a safe Twitter banner update

Verify the updated Twitter banner

Fix Twitter profile banner API errors

Headers

Body

Response

Durable write recovery

200 Terminal or 202 active

​Update a Twitter profile banner through the API

​Prepare Twitter profile banner dimensions

​Automate a safe Twitter banner update

​Verify the updated Twitter banner

​Fix Twitter profile banner API errors

​Headers

​Body

​Response

​Durable write recovery

​200 Terminal or 202 active

Update a Twitter profile banner through the API

Prepare Twitter profile banner dimensions

Automate a safe Twitter banner update

Verify the updated Twitter banner

Fix Twitter profile banner API errors

Headers

Body

Response

Durable write recovery

200 Terminal or 202 active