The ALTtext API

The same engine that powers alttext.org and theALTer Mac app, as a simple keyed API. One POST, one JSON response: a title and an accessibility description for any photo — or any video, from sampled frames and an optional transcript.

Authentication

Every request carries an ALTtext Pro license key as a bearer token. Your key from ALTtext Pro is your API key — there is nothing separate to provision.

Authorization: Bearer ALTTEXT-XXXX-XXXX-XXXX

Describe an image

POST https://alttext.org/api/v1/describe

curl https://alttext.org/api/v1/describe \
  -H "Authorization: Bearer $ALTTEXT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64 JPEG or PNG>",
    "mimeType": "image/jpeg",
    "style": "concise"
  }'

Response:

{
  "title": "Moulton Barn under a violet sunset",
  "description": "A weathered wooden barn stands in sagebrush …",
  "mode": "image",
  "usage": { "today": 42 }
}

Describe a video

Send 2–8 stills sampled evenly across the clip asframes, in order. The engine describes themotion, not the stills. An optionaltranscript (up to 4,000 characters, from your own speech-to-text) lets the description report what's said.

{
  "frames": ["<base64>", "<base64>", "<base64>"],
  "transcript": "So the first thing you'll notice …",
  "mimeType": "image/jpeg",
  "style": "concise"
}

Request fields

image: Base64 media payload. Required unless frames is sent. Downscale to ≤1024px on the long edge — larger buys nothing.
frames: 2–8 base64 stills sampled across a video, in order.
transcript: Optional speech transcript for video, ≤4,000 characters.
mimeType: image/jpeg (default) or image/png.
style: concise (default) or detailed.

Errors

401 missing_key: No Authorization: Bearer header.
401 invalid_key: The key isn't valid or is no longer active.
400 missing_media: Neither image nor frames present.
400 too_many_frames: More than 8 frames.
502 model_error: The model returned unusable output after retries — try again.
503 engine_unavailable: Engine outage on our side.

Dogfooded, not just documented

ALTer — our own pro Media Editor for the Mac — generates every photo and video description through this exact endpoint. If it's rough, it cuts us first.

Get a key with ALTtext Pro →