GetAltTexts / API Documentation
v1.0

API Documentation

Generate WCAG-compliant alt-texts, validate existing descriptions, and scan entire websites for accessibility issues — all through a simple REST API.

Base URL https://getalttexts.com
All endpoints require authentication via Authorization: Bearer <key> or x-api-key: <key> unless noted otherwise.
POST /v1/alt-text

Generate a WCAG-compliant alt-text for a single image. Supports multiple languages, page context, image type hints, and gallery-aware sibling deduplication.

Request body
ParameterTypeDescription
image_urlrequired string URL of the image or base64 data URI
languageoptional string Output language: en, de, fr, es. Default: en
contextoptional string Page context for better results (e.g. "Product detail page for running shoes"). Max 500 chars.
captionoptional string Existing image caption. The AI will complement it instead of repeating the same information. Max 300 chars.
image_typeoptional string Image type hint: photo, icon, chart, screenshot, text, decorative, auto. Default: auto
page_typeoptional string Page context type: product, blog, landing, docs, social, news, ecommerce, other
max_lengthoptional number Maximum characters (20–500). Default: 125
qualityoptional string standard (Gemini Flash) or premium (GPT-4o). Premium uses 5 credits. Default: standard
formatoptional string plain or html. Default: plain
surrounding_textoptional string Text content around the image (paragraphs before/after). Helps the AI understand page context. Max 1000 chars.
sibling_imagesoptional array Alt-texts of other images in the same gallery/group. Each object: {"alt_text": "...", "position": 1}. Max 20 items. Prevents repetitive descriptions.
Example request
curl -X POST https://getalttexts.com/v1/alt-text \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/hero.jpg",
    "language": "de",
    "context": "Product detail page for running shoes",
    "caption": "Nike Air Zoom Pegasus 41",
    "image_type": "photo",
    "page_type": "product",
    "max_length": 125,
    "quality": "standard",
    "surrounding_text": "Der neue Pegasus 41 bietet reaktionsfreudige Dämpfung für tägliches Training.",
    "sibling_images": [
      {"alt_text": "Nike Air Zoom Pegasus 41 Frontansicht", "position": 1},
      {"alt_text": "Nahaufnahme der Zoom-Air-Sohle", "position": 2}
    ]
  }'
Response · 200
{
  "alt_text": "Seitenansicht mit atmungsaktivem Mesh-Obermaterial und Zoom-Air-Dämpfung in der Sohle",
  "language": "de",
  "characters": 82,
  "quality": "standard",
  "decorative": false,
  "image_type_detected": "photo",
  "processing_ms": 1200,
  "credits_used": 1,
  "credits_remaining": 449,
  "credits_total": 500,
  "plan": "starter",
  "overage": false,
  "overage_rate": 0.03
}
Decorative image response
{
  "alt_text": "",
  "decorative": true,
  "reason": "Image appears to be purely decorative (background pattern)",
  "image_type_detected": "decorative",
  "credits_used": 1,
  "credits_remaining": 448,
  "credits_total": 500,
  "plan": "starter",
  "overage": false,
  "overage_rate": 0.03
}
POST /v1/alt-text/batch

Process up to 50 images asynchronously. Results are delivered via webhook.

Request body
ParameterTypeDescription
imagesrequired array Array of objects with id, image_url, and optional language, context, caption, image_type, page_type, surrounding_text, sibling_images
webhook_urlrequired string URL to receive results when batch completes
qualityoptional string standard or premium. Default: standard
Response · 202 Accepted
{
  "batch_id": "batch_abc123",
  "total_images": 5,
  "status": "processing",
  "webhook_url": "https://your-server.com/callback"
}
POST /v1/validate

Validate an existing alt-text against the actual image. Returns a quality score, WCAG compliance check, issues, and an improved suggestion. Costs 1 credit per call.

Request body
ParameterTypeDescription
image_urlrequired string URL of the image or base64 data URI
alt_textrequired string The alt-text to validate
languageoptional string Language for the response: en, de, fr, es. Default: en
contextoptional string Page context for relevance checking. Max 500 chars.
page_typeoptional string Page type: product, blog, landing, docs, social, news, ecommerce, other
captionoptional string Existing image caption. Max 300 chars.

Issue types

TypeDescription
inaccurateAlt-text does not match what is actually in the image
genericToo vague or generic, lacks specific detail
too_longExceeds recommended length (150+ characters)
too_shortToo short to be meaningfully descriptive (<20 characters)
redundant_prefixStarts with "Image of", "Photo of", etc.
missing_contextDoes not reference important page context (e.g. product name)
seo_stuffingAppears to be keyword-stuffed for SEO rather than descriptive
should_be_decorativeImage appears decorative and should have an empty alt attribute
Example request
curl -X POST https://getalttexts.com/v1/validate \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/product.jpg",
    "alt_text": "Image of shoes",
    "language": "en",
    "context": "Running shoe product page",
    "page_type": "product"
  }'
Response · 200
{
  "score": 35,
  "issues": [
    {
      "type": "redundant_prefix",
      "message": "Starts with 'Image of' — screen readers already announce images."
    },
    {
      "type": "generic",
      "message": "Too generic — does not describe the specific shoe model or features."
    },
    {
      "type": "missing_context",
      "message": "Does not mention product-relevant details like brand or model."
    }
  ],
  "suggestion": "Nike Air Zoom Pegasus 41 running shoe in black with white sole, side view",
  "is_decorative": false,
  "wcag_compliant": false,
  "model": "gemini-2.0-flash",
  "credits_used": 1,
  "credits_remaining": 49
}
POST /v1/scan

Scan a website and find images with missing or poor alt-texts. No credits consumed — the scanner uses heuristic analysis, not Vision API calls.

Authentication

ModeMax imagesQuality checkAuth required
Basic (free)10NoNo
Extended200YesYes (API key)
Request body
ParameterTypeDescription
urlrequired string URL of the page to scan (must be public, http or https)
max_imagesoptional number Maximum images to analyse (1–200). Default: 50. Capped to 10 without auth.
check_qualityoptional boolean Run heuristic quality scoring on existing alt-texts. Default: false. Requires auth.

Image status values

StatusDescription
missingNo alt attribute present on the <img> tag
emptyalt="" — intentionally empty (may be decorative)
has_altHas an alt-text value. quality_score available when check_quality is enabled.
Example request (no auth)
curl -X POST https://getalttexts.com/v1/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "max_images": 10}'
Example request (with auth + quality check)
curl -X POST https://getalttexts.com/v1/scan \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "max_images": 100,
    "check_quality": true
  }'
Response · 200
{
  "url": "https://example.com",
  "total_images": 8,
  "missing_alt": 3,
  "empty_alt": 1,
  "has_alt": 4,
  "score": 62,
  "images": [
    {
      "src": "https://example.com/hero.jpg",
      "alt": "",
      "status": "empty",
      "context": "Welcome to our store",
      "position": 1,
      "quality_score": null
    },
    {
      "src": "https://example.com/product.jpg",
      "alt": "Blue running shoes on white background",
      "status": "has_alt",
      "context": "Featured Products",
      "position": 2,
      "quality_score": 85
    },
    {
      "src": "https://example.com/banner.jpg",
      "alt": "",
      "status": "missing",
      "context": "",
      "position": 3,
      "quality_score": null
    }
  ]
}
GET /v1/usage

Check your current credit balance and billing period.

Response fields
FieldTypeDescription
plan string Current plan name
credits_total number Total credits in billing period
credits_used number Credits consumed so far
credits_remaining number Remaining credits (0 when in overage)
overage boolean true when usage exceeds plan credits
overage_credits number Number of credits used beyond the plan limit
overage_cost number Current overage cost in EUR (overage_credits × overage_rate)
overage_rate number|null Cost per image above plan limit. null for free plan (blocked instead)
Response · 200
{
  "plan": "starter",
  "credits_total": 500,
  "credits_used": 520,
  "credits_remaining": 0,
  "overage": true,
  "overage_credits": 20,
  "overage_cost": 0.60,
  "overage_rate": 0.03,
  "period_start": "2026-03-01",
  "period_end": "2026-03-31"
}
POST /v1/register

Create a new account. Returns a user object and your first API key.

Request body
ParameterTypeDescription
emailrequired string Valid email address
passwordrequired string Min. 8 characters
POST /v1/api-keys

Create additional API keys (max 5 per account). Requires authentication.

Error codes

StatusMeaning
400Bad request — missing or invalid parameters
401Unauthorized — missing or invalid API key
402Payment required — credit limit exceeded (free tier)
429Rate limited — too many requests
500Internal server error

Rate limits

PlanRequests / min
Free60
Starter120
Pro300
Scale600