API Reference

Generate alt text programmatically — from GTM, WordPress, Shopify, or any HTTP client.

Overview

The WaytoSEO API accepts an image (as a base64 string or public URL) and returns AI-generated alt text. All requests are authenticated with an API key. Credits are consumed from your account unless you have a BYOK (bring-your-own-key) AI provider configured.

Base URL: https://waytoseo.com

Content-Type: application/json

Authentication

Pass your WaytoSEO API key in the Authorization header. Generate a key in Settings → API Keys.

Authorization: Bearer aat_live_YOUR_KEY_HERE

Keys starting with aat_live_ are production keys. Treat them like passwords — do not commit them to source control. For GTM or other client-side uses, create a dedicated key so you can revoke it independently.

POST /api/generate

POSThttps://waytoseo.com/api/generate

Generate alt text for a single image.

Request body

Field	Type	Required	Description
imageBase64	string	✱ one of	Base64-encoded image data (no data: prefix)
imageUrl	string (URL)	✱ one of	Publicly accessible image URL
mediaType	string	No	image/jpeg · image/png · image/webp · image/gif — default: image/jpeg
style	string	No	descriptive · seo · ecommerce · accessibility — default: descriptive
maxLength	integer	No	Character cap 50–300 — default: 125
language	string	No	Output language — default: English
seoKeyword	string	No	Keyword to weave into the alt text (seo style)
productContext	object	No	{ title?, brand?, category? } — enriches ecommerce output

✱ Provide exactly one of imageBase64 or imageUrl.

Response

HTTP 200 on success:

{
  "altText": "A pair of red running shoes on a white studio background.",
  "imageId": "uuid",
  "creditsRemaining": 23,
  "byok": false,
  "provider": "anthropic"
}

Error codes

Status	error field	Meaning
400	Invalid JSON body / validation	Malformed request or missing required fields
401	Unauthorized / Invalid or revoked API key	Missing, invalid, or revoked API key
402	out_of_credits	No credits remaining — add a BYOK AI key or top up
429	Rate limit exceeded — 60 requests/minute per key	Slow down — wait ~60s and retry
500	Alt text generation failed	Upstream AI error — retry with backoff

Code examples

curl

curl -X POST https://waytoseo.com/api/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer aat_live_YOUR_KEY_HERE" \
  -d '{
    "imageUrl": "https://example.com/shoe.jpg",
    "style": "ecommerce",
    "seoKeyword": "red running shoes"
  }'

JavaScript (fetch)

const response = await fetch('https://waytoseo.com/api/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer aat_live_YOUR_KEY_HERE',
  },
  body: JSON.stringify({
    imageUrl: 'https://example.com/shoe.jpg',
    style: 'descriptive',
    language: 'English',
  }),
});

const { altText, creditsRemaining } = await response.json();
console.log(altText); // "A red running shoe photographed..."

Python (requests)

import requests

response = requests.post(
    'https://waytoseo.com/api/generate',
    headers={
        'Authorization': 'Bearer aat_live_YOUR_KEY_HERE',
        'Content-Type': 'application/json',
    },
    json={
        'imageUrl': 'https://example.com/shoe.jpg',
        'style': 'seo',
        'seoKeyword': 'red running shoes',
        'maxLength': 150,
    }
)

data = response.json()
print(data['altText'])

Rate limits

Each API key is limited to 60 requests per minute. Exceeding this returns a 429 response. The window resets every 60 seconds.

For batch workloads, add a 1-second delay between requests or use the Bulk Upload feature in the dashboard (handles concurrency automatically).