Alt text and filenames, straight from your own code

Why an API rather than a download

Renaming a few images in a browser is fine. Fixing a media library of several hundred is not, because the output has to get back into the site — and re-uploading hundreds of files by hand is more work than the problem you started with.

With the API both ends stay under your control. A script, a build step or a CMS plugin reads each image, sends it, and writes the alt text straight back through your platform’s own API. No ZIP, no CSV, no manual re-upload, and no broken URLs because you never had to replace the file.

Authentication

Sign in and open /api/key. You get back a key beginning pxr_. Send it as a bearer token:

Authorization: Bearer pxr_YOUR_KEY

The key is derived from your account rather than stored, so requesting it twice returns the same value. It spends your allowance and nothing else — it cannot read billing, change your account, or reach another user’s images. Keep it server-side.

Request

POST https://image-seo.net/api/optimize

curl -X POST https://image-seo.net/api/optimize \
  -H "Authorization: Bearer pxr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original": "DSC_1553.jpg",
    "type": "image/jpeg",
    "data": "<base64 of the image bytes>",
    "industry": "Real estate",
    "keywords": "",
    "context": "Front elevation of a new-build listing."
  }'

data is the raw image bytes, base64 encoded, without a data-URL prefix. type must match the actual format of those bytes — the server checks the file signature and rejects a mismatch. industry, keywords and context are optional but meaningfully improve the wording; context is used for the request and is not stored against the image.

Response

{
  "result": {
    "id": "0f0c...",
    "original": "DSC_1553.jpg",
    "filename": "modern-farmhouse-front-elevation-custom-home.jpg",
    "alt": "Front elevation of a white modern farmhouse with covered porch and attached garage",
    "title": "Modern Farmhouse Custom Home Front Elevation",
    "description": "A two-storey white farmhouse with a deep covered porch ...",
    "width": 1200,
    "height": 801,
    "bytes": 152866
  }
}

Review before publishing. The model describes only what is visibly present and will not assert a brand, price, location or certification a photograph cannot establish — which is exactly why a human check is worth the few seconds.

Errors

• 400 — the image is not valid JPG/PNG/WebP, or the declared type does not match the bytes.
• 401 — missing or invalid key.
• 413 — over 5 MB.
• 429 — monthly allowance spent, or another image is still processing for this account. Retry after the in-flight one finishes.
• 503 — analysis briefly unavailable. No allowance is consumed; retry.

Failed images never cost you an image. Process sequentially rather than in parallel — one request per account is in flight at a time by design, so a burst will simply return 429.

A worked loop

The shape of almost every integration is the same three steps, whatever the platform:

1. List the images that need work — typically those with an empty alt attribute.
2. For each, read the bytes, base64 them, and POST to /api/optimize.
3. Write result.alt back to the media record through your CMS API. Set the filename too if your platform allows renaming without breaking the URL; if it does not, leave the file alone and keep the alt text.

Alt text is the part worth automating first: it is what a screen reader reads aloud, it is a WCAG 2.2 Level A obligation, and unlike a filename it can be changed on a live site with no redirect risk.

API FAQ

How do I get a key?

Sign in and call GET /api/key from the browser, or open it in a tab while signed in. The key is derived from your account, so the same account always gets the same key and there is nothing to store or rotate on your side.

Does the API use my plan allowance?

Yes. API calls draw on exactly the same monthly images as the web app — 25 on Free, 500 on Pro, 2,000 on Business. There is no separate API price and no surcharge.

What are the limits?

JPG, PNG and WebP, up to 5 MB, 8,000 pixels per side and 24 megapixels. One image per request, and one request in flight per account at a time, so loop rather than firing in parallel.

Can I use it to bulk-fill alt text in a CMS?

That is what it is for. Read each image from your media library, POST it, and write the returned alt text back through your CMS API. Because you control both ends, nothing has to be downloaded or re-uploaded by hand.

Is the key safe to put in a plugin?

Treat it like a password: keep it server-side. Anyone holding it can spend your monthly allowance. It carries no other privilege — it cannot read your billing, change your account or see other users.

What happens if a call fails?

Failed images never consume an allowance. A 429 means either your monthly allowance is spent or another image is still processing; a 503 means image analysis is briefly unavailable and you should retry.