The ALTtext API

The same engine that powers alttext.org and the Alter 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 as frames, in order. The engine describes the motion, not the stills. An optional transcript (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 →