Alt Text Generation

The Generations API can produce AI-generated alt text for an Imgix image, written for screen readers and other assistive technology. You can request up to 10 of the 52 supported languages in a single call.

If the generated text isn’t quite right, you can also edit it by setting a manual override per language. Overrides are stored alongside the AI-generated text and take precedence whenever alt text for that image is requested.

Unlike Video Generation, alt text generation is synchronous: the generated text is returned directly in the response, with no job to poll.

Authentication

All calls to the Generations API require an API key with any permission (billing, asset manager read, etc). To create a key, navigate to the API Keys view in your Dashboard. The API key’s account must own the Source that serves the image.

Alt Text Operations

Generating Alt Text

To generate alt text, make a GET request to /v1/generations/alt-text, identifying the image with either url or url64.

Request Parameters

How generation and caching work

Generated alt text is stored per image, so repeat requests are served from storage rather than regenerating.

Each request generates only the languages that aren’t already available for that image. If you ask for pl,nl,ru,de and later ask for pl,nl,ru,de,th, only Thai is generated — the other four are returned exactly as before, character for character. Languages you have overridden are also already available, so they are never regenerated either.

Different renders of the same image share stored alt text: photo.jpg?w=200 and photo.jpg?fit=crop&h=400 are the same picture, so they reuse the same text. Images generated with text2image are treated as distinct, since a different prompt is a different picture.

To replace text you already have, use regenerate=true.

Supported Languages

Alt text can be generated in the 52 languages below. Codes are matched case-insensitively, so PT and zh-hant are accepted. Requesting any other language returns a 400 response.

Chinese is addressed by script rather than as a bare zh, since Simplified and Traditional are different text.

Response

The response contains an alt_text object keyed by the requested language codes, and a failed_languages array listing any requested languages that could not be generated.

GET api/v1/generations/alt-text?url=https://assets.imgix.net/photo.jpg&language=en,fr

{
  "alt_text": {
    "en": "a havanese puppy sitting on a wooden floor, looking up at the camera",
    "fr": "un chiot havanais assis sur un parquet, regardant l'objectif"
  },
  "failed_languages": [],
  "overridden_languages": []
}

Generating alt text for a URL with parameters

When the image URL contains query parameters — for example an AI image created with text2image — base64url-encode the full URL and pass it as url64:

# Plain URL (contains query parameters):
# https://assets.imgix.net/ai?text2image=true&prompt=a serene mountain lake at sunset
 
GET api/v1/generations/alt-text?url64=aHR0cHM6Ly9hc3NldHMuaW1naXgubmV0L2FpP3RleHQyaW1hZ2U9dHJ1ZSZwcm9tcHQ9YSBzZXJlbmUgbW91bnRhaW4gbGFrZSBhdCBzdW5zZXQ&language=en

Editing Alt Text

If an AI-generated description needs adjusting — for example to name a product or match your brand’s voice — you can set a manual override per language by making a POST request to /v1/generations/alt-text. Overrides take precedence over AI-generated text: once set, the GET endpoint returns your text for that language and lists the language in overridden_languages.

Overrides can only be set for an image that already has generated alt text. Generate it first with a GET request; a POST for an image with no generated alt text returns a 409.

Request Body

The request body is a JSON object identifying the image with exactly one of url or url64 (same semantics as the GET endpoint), plus an alt_text object with the overrides to apply.

You can set and remove overrides for any subset of the supported languages in a single request; the 10-language limit applies to generation, not to overrides. Language codes are matched case-insensitively. Override text must be non-empty (use null to remove, not an empty string) and at most 2,000 characters per language.

Response

POST api/v1/generations/alt-text
{
  "url": "https://assets.imgix.net/photo.jpg",
  "alt_text": {
    "en": "Maya the havanese puppy sitting on a wooden floor, looking up at the camera",
    "fr": null
  }
}

{
  "alt_text": {
    "en": "Maya the havanese puppy sitting on a wooden floor, looking up at the camera"
  },
  "removed_languages": ["fr"]
}

Status Codes

Examples

Generating alt text

curl -X GET "https://api.imgix.com/api/v1/generations/alt-text?url=https://assets.imgix.net/photo.jpg&language=en,es" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response:
# {
#   "alt_text": {
#     "en": "a havanese puppy sitting on a wooden floor, looking up at the camera",
#     "es": "un cachorro habanero sentado en un suelo de madera, mirando a la cámara"
#   },
#   "failed_languages": [],
#   "overridden_languages": []
# }

# To run:
# $ python3 demo.py
# Ensure to export your API key into your environment
import os
import requests
 
IMGIX_API_KEY = os.environ.get("IMGIX_API_KEY")
if not IMGIX_API_KEY:
    raise ValueError(
r"""
An Imgix API Key is required, export it or
use dotenv to load it from an .env file
""")
 
resp = requests.get(
    url="https://api.imgix.com/api/v1/generations/alt-text",
    headers={"Authorization": f"Bearer {IMGIX_API_KEY}"},
    params={
        "url": "https://assets.imgix.net/photo.jpg",
        "language": "en,es",
    },
)
 
if resp.status_code in [401, 403]:
    raise ValueError(
        "You do not have permission, ensure alt text generation is enabled for your source."
    )
 
data = resp.json()
print(data["alt_text"])
if data["failed_languages"]:
    print(f"failed languages: {data['failed_languages']}")

Editing alt text

curl -X POST "https://api.imgix.com/api/v1/generations/alt-text" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://assets.imgix.net/photo.jpg",
    "alt_text": {
      "en": "Maya the havanese puppy sitting on a wooden floor, looking up at the camera"
    }
  }'
# Response:
# {
#   "alt_text": {
#     "en": "Maya the havanese puppy sitting on a wooden floor, looking up at the camera"
#   },
#   "removed_languages": []
# }

# To run:
# $ python3 demo.py
# Ensure to export your API key into your environment
import os
import requests
 
IMGIX_API_KEY = os.environ.get("IMGIX_API_KEY")
if not IMGIX_API_KEY:
    raise ValueError(
r"""
An Imgix API Key is required, export it or
use dotenv to load it from an .env file
""")
 
resp = requests.post(
    url="https://api.imgix.com/api/v1/generations/alt-text",
    headers={"Authorization": f"Bearer {IMGIX_API_KEY}"},
    json={
        "url": "https://assets.imgix.net/photo.jpg",
        "alt_text": {
            "en": "Maya the havanese puppy sitting on a wooden floor, looking up at the camera",
        },
    },
)
 
if resp.status_code == 409:
    raise ValueError(
        "No generated alt text exists for this image yet; generate it first with a GET request."
    )
if resp.status_code in [401, 403]:
    raise ValueError(
        "You do not have permission, ensure alt text generation is enabled for your source."
    )
 
data = resp.json()
print(data["alt_text"])
if data["removed_languages"]:
    print(f"removed overrides: {data['removed_languages']}")