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 alt text in several languages in a single call.
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
| Endpoint | Method | Description |
|---|---|---|
/v1/generations/alt-text | GET | Generate alt text for an image in one or more languages. |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
url | String | One of url/url64 | A plain Imgix render URL with no query parameters (e.g. https://assets.imgix.net/photo.jpg). |
url64 | String | One of url/url64 | A base64url-encoded Imgix render URL. Use this when the URL carries query parameters, such as AI generation parameters. |
language | String | No | A BCP-47 language code. Repeat the parameter or pass a comma-separated list for multiple languages. Defaults to en. |
regenerate | Boolean | No | Skip the cache and regenerate the alt text. Defaults to false. |
Note: Provide exactly one of url or url64. Use url for a clean image
URL and url64 whenever the URL contains query parameters (for example, an
image produced with text2image).
Supported Languages
Alt text can be generated in the following languages. Requesting any other language returns a 400 response.
| Code | Language |
|---|---|
en | English |
fr | French |
de | German |
it | Italian |
es | Spanish |
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.
| Attribute | Type | Description |
|---|---|---|
alt_text | Object | Map of language code to the generated alt text string, for each requested language. |
failed_languages | Array | Language codes that were requested but could not be generated. Empty on full success. |
GET api/v1/generations/alt-text?url=https://assets.imgix.net/photo.jpg&language=en,frGenerating 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=enStatus Codes
| Status Code | Description |
|---|---|
200 | OK - Alt text generated (or served from cache) successfully. |
400 | Bad Request - Missing or invalid url/url64, or an unsupported language value. |
402 | Payment Required - The account’s AI credits are depleted (plan_credits_depleted_payment_required). |
403 | Forbidden - Alt text generation is not enabled for the Source, or the API key does not own the Source. |
500 | Internal Server Error - The image could not be fetched, or generation failed for every requested language. |
Credit usage
Alt text generation is metered against your account’s AI credits. A 402
response indicates the account’s credits are depleted; generation resumes once
the balance is replenished.
Examples
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": []
# }