🔌 API Documentation

Alt-Words AI RESTful API for generating SEO-optimized image alt text.

📑 Table of Contents

Authentication
POST /api/generate - Generate alt text
POST /api/batch - Batch generate
POST /api/scan - Site scanner FREE
POST /api/scan/generate - Generate for scan results
GET /api/usage - Check usage
Pricing

🔐 Authentication

API requests can be made without authentication for free tier (100 images/month). For higher limits, include your API key:

Authorization: Bearer YOUR_API_KEY

Generate Alt Text

POST https://api.altwordsai.com/api/generate

Generate SEO-optimized alt text for a single image.

Request Body

Parameter	Type	Description
`image_url` *	string	URL of the image
`language`	string	Output language: en, zh, ja, ko, es, fr, de (default: en)
`style`	string	seo \| descriptive \| simple (default: seo)
`tier`	string	free \| standard \| quality \| premium (default: free)

Example Request

curl -X POST https://api.altwordsai.com/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "language": "en",
    "style": "seo"
  }'

Example Response

{
  "alt_text": "Professional laptop on wooden desk with code editor open",
  "cached": false,
  "language": "en",
  "style": "seo",
  "tier": "free",
  "model": "gemini-2.0-flash-lite-001"
}

Batch Generate

POST https://api.altwordsai.com/api/batch

Generate alt text for multiple images (max 10 per request).

Request Body

{
  "images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "language": "en",
  "style": "seo",
  "tier": "standard"
}

Site Scanner FREE

POST https://api.altwordsai.com/api/scan

Scan a website for images and check alt text status. Completely free!

Request Body

Parameter	Type	Description
`url` *	string	Website URL to scan
`maxImages`	number	Max images to return (default: 50)

Example Response

{
  "success": true,
  "summary": {
    "total_images": 25,
    "with_alt": 20,
    "without_alt": 5,
    "seo_score": 80,
    "seo_grade": "B"
  },
  "images": [...],
  "recommendations": [...],
  "cost_estimate": {
    "images_needing_alt": 5,
    "total_estimate": "$0.0005"
  }
}

Generate for Scan Results

POST https://api.altwordsai.com/api/scan/generate

Generate alt text for images from scan results (max 20 per request).

{
  "images": ["https://example.com/img1.jpg", "https://example.com/img2.jpg"],
  "language": "zh",
  "style": "seo"
}

Check Usage

GET https://api.altwordsai.com/api/usage

Check your daily usage and remaining quota.

{
  "date": "2026-02-06",
  "used": 45,
  "limit": 100,
  "remaining": 55
}

💰 Pricing

Tier	Model	Cost per Image	Best For
free	Llama 3.2 Vision	~$0.00005	Testing, low volume
standard	Gemini Flash Lite	~$0.0001	Production use
quality	Gemini 2.5 Flash	~$0.0003	Higher quality
premium	GPT-4o-mini	~$0.001	Best quality

Questions? Contact us at support@altwordsai.com