API Documentation — GetAltText

POST /v1/alt-text

Generate a WCAG-compliant alt-text for a single image.

Request body

Parameter	Type	Description
`image_url` required	string	URL of the image or base64 data URI
`language` optional	string	Output language: `en`, `de`, `fr`, `es`. Default: `en`
`context` optional	string	Page context for better results (e.g. "Product detail page for running shoes")
`max_length` optional	number	Maximum characters. Default: 125
`quality` optional	string	`standard` (Gemini Flash) or `premium` (GPT-4o). Premium uses 5 credits. Default: `standard`
`format` optional	string	`plain` or `html`. Default: `plain`

Example request

curl -X POST https://api.getalttext.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",
    "max_length": 125,
    "quality": "standard"
  }'

Response (200)

{
  "alt_text": "Roter Laufschuh von der Seite auf weißem Hintergrund",
  "language": "de",
  "characters": 52,
  "quality": "standard",
  "decorative": false,
  "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)",
  "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

Parameter	Type	Description
`images` required	array	Array of objects with `id`, `image_url`, and optional `language`/`context`
`webhook_url` required	string	URL to receive results when batch completes
`quality` optional	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"
}

GET /v1/usage

Check your current credit balance and billing period.

Response

{
  "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"
}

Response fields

Field	Type	Description
`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)

POST /v1/register

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

Request body

Parameter	Type	Description
`email` required	string	Valid email address
`password` required	string	Min. 8 characters

POST /v1/api-keys

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

Error codes

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

Rate limits

Plan	Requests/min
Free	60
Starter	120
Pro	300
Scale	600