---
canonical: https://amplience.com/developers/docs/dev-tools/assets/image-alt-text/
title: Working with image alt text
description: Overview of how to work with image alt text in Content Hub and Dynamic Content
image: https://cdn.media.amplience.net/i/ampproduct/media-card-alt-text-1?w=1200&h=630
image_width: 1200
image_height: 630
audience: Developer
date_published: 2025-02-20
date_modified: 2025-11-03
---
# Working with image alt text
Automatic alt text generation helps ensure that images you publish go live with text descriptions that can be read by screen readers. Alt text can be generated in multiple languages for use across multiple locales and can be configured to adhere to your brand rules.
Generating alt text automatically for images helps:
- Improve accessibility of your Web content by enabling screen-reader users to comprehend images
- Enhance your SEO by including descriptive text with images
- Adhere to accessibility laws such as "The European Accessibility Act" in the European Union and the "Websites and Software Applications Accessibility Act" in the US
> **Note: Automatic alt text generation and Amplience credits**
This page describes how to set up and use the Automatic alt text generation service. For other approaches to implementing alt text see [choosing your approach to implementing alt text](#choosing-your-approach-to-supporting-alt-text).
## Setting up automatic alt text
To start generating alt text automatically, you'll need to reach out to Amplience Support, who will configure the service for your chosen asset stores. You'll need to provide the default locale to use for image descriptions, and any additional locales you would like to use. Also, you need to let Support know if you are [using custom templates with the automatic alt text service](https://amplience.com/developers/docs/workforce/templates/example-prompts/#examples-for-automatic-alt-text).
> **Tip: Tune image alt text generation**
> If you're already using Workforce and have set up brand rules, such as words to substitute, these can be included when configuring the service.
## Generating alt text automatically
Once set up, alt text will be automatically generated when you use any of the following upload methods:
- [The GraphQL Asset Management API](https://amplience.com/developers/docs/apis/asset-management/overview/examples/#creating-updating-and-deleting-assets)
- [Automated bulk upload](https://amplience.com/developers/docs/user-guides/assets/upload/#bulk-upload)
- [Manual upload using Content Hub](https://amplience.com/developers/docs/user-guides/assets/upload/#uploading-assets-with-content-hub)
- [Manual upload using the Asset Tab in Dynamic Content](https://amplience.com/developers/docs/user-guides/assets/upload/#uploading-assets-with-dynamic-content)
Alt text will also be generated when you edit images with Image Studio through Dynamic Content. See [Editing images as part of your workflow](https://amplience.com/developers/docs/user-guides/produce-content/create/blog/#edit-images-with-image-studio).
You can [view generated image alt text](https://amplience.com/developers/docs/user-guides/assets/working-with-assets/auto-alt-text-generation/#viewing-generated-image-alt-text) within Content Hub.
> **Tip: Overwriting an image**
> When you upload a new image with the same name, the image alt text will automatically be updated to reflect the new image.
For help with generating alt text for previously uploaded images, please contact your Amplience account director for more information.
When alt text is generated for [sets](https://amplience.com/developers/docs/user-guides/assets/working-with-assets/#creating-sets), descriptions are generated for each individual image in the set. More about [sets](https://amplience.com/developers/docs/user-guides/assets/working-with-assets/#creating-sets).
> **Info: Assets, locales and images**
> The locales that are used for setting up automatic alt text generation are independent from the Content Hub asset locales used to retrieve and group assets. See [Content Hub asset locales](https://amplience.com/developers/docs/user-guides/assets/locate/locales/).
## Fetching image alt text
### Media Delivery API approach
You can retrieve alt text that's stored in image metadata, along with any locale variants, using the [Media Delivery API](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-overview/).
The Media Delivery API will retrieve image alt text for **published** images.
For example, to fetch the metadata for an image with the name `sunglasses-on-beach` use:
`https://cdn.media.amplience.net/i/demobootha/sunglasses-on-beach.json?metadata=true`
For this example, the API returns the following alt text descriptions:
```json
{
"isImage": true,
"alpha": false,
"width": 5184,
"height": 3456,
"format": "JPEG",
"metadata": {
"altText": {
"descriptions": {
"it-IT": "Occhiali da sole con lenti arancioni sulla sabbia al tramonto.",
"de-DE": "Sonnenbrille mit orangefarbenen Gläsern liegt am Strand bei Sonnenuntergang.",
"en-US": "Aviator sunglasses with orange lenses placed on sandy beach at sunset.",
"es-ES": "Gafas de sol con lentes naranja reflejando el atardecer en la playa.",
"fr-FR": "Lunettes de soleil aviateur à verres orange sur une plage de sable au coucher du soleil."
},
"defaultDescription": "Aviator sunglasses with orange lenses placed on sandy beach at sunset."
}
},
"status": "ok"
}
```
### Using manifest files
You can retrieve image alt text metadata by using manifest files, as part of your regular asset export schedule. See [Manifests](https://amplience.com/developers/docs/dev-tools/guides-tutorials/manifests/)
## Managing alt text in Dynamic Content
Alt text can be viewed on the media card when you add an image containing alt text metadata to a content item.
In your content type schema you just need to include an [image property](https://amplience.com/developers/docs/schema-reference/media/#images), with no additional settings required.
### Viewing and editing alt text
To view alt text on the content form, hover over an image and click the "alt text" icon.
A dialog showing the image alt text is displayed. You can edit the alt text by clicking in the text box, making a change and clicking the "apply" button. The edited alt text will be saved with the content but the image asset meta data will not be updated.
### Viewing locale variants
If alt text has been generated for multiple locales then you can choose the locale you want to view from the "Choose variant" menu. If you choose a variant and click the "Apply" button, the variant will be used as the default alt text stored with the content.
Only the default alt text will be saved with the content. See [choosing your approach to supporting alt text](#choosing-your-approach-to-supporting-alt-text) for details of how to manage alt text for multiple locales.
### Alt text in the content item JSON data
Image alt text is stored in the `altText` field of an image property and returned in the content item's JSON. If the image asset does not contain any alt text metadata then the image property will not contain an `altText` field.
Here's the [Content Delivery URL](https://amplience.com/developers/docs/user-guides/produce-content/create/#content-item-properties) to return the JSON for a content item that contains a single image property. We've added an image containing alt text metadata to the content.
`https://demobootha.cdn.content.amplience.net/content/id/375c95a1-a734-4133-b3e6-712369e13458?depth=all&format=inlined`
The JSON for the content item is shown below. In this example we chose to set the image alt text to the es-ES variant.
```json
{
"content":{
"_meta":{
"schema":"https://example.com/image-with-alt-text",
"name":"Image with alt text",
"deliveryId":"375c95a1-a734-4133-b3e6-712369e13458"
},
"image":{
"_meta":{
"schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id":"611acc54-d90d-4d39-95fb-5fefe2db991b",
"name":"sunglasses-on-beach",
"endpoint":"demobootha",
"defaultHost":"cdn.media.amplience.net",
"mimeType":"image/jpeg",
"altText":"Gafas de sol con lentes naranja reflejando el atardecer en la playa."
}
}
}
```
`altText` will contain the default alt text for an image. If you want to fetch the alt text for each locale then you will need to retrieve it from the [image metadata](#fetching-image-alt-text) using the [Media Delivery API](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/#metadata).
> **Info: Alt text and Next Generation Authoring**
> The `altText` field is included with an image property whether or not you're using Next Generation Authoring, but text is only shown in the media card when the new authoring experience is enabled.
### Turning off alt text on the media card
Alt text will be shown on the media card by default, but you can hide the alt text icon by setting the `withAltText` params for an image property in your content type schema. An image property with alt text switched off is shown below.
```json
"type": "object",
"properties": {
"image": {
"title": "Image",
"allOf": [
{ "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link" }
],
"ui:component": {
"params": {
"withAltText": false
}
}
}
```
## Using alt text with the img tag
When you display images on your site with HTML, you use the `![]()
` tag, adding alt text as an attribute to provide a description that screen readers can use, or in case the image doesn't load for some reason.
You can retrieve the alt text for an image either from the [image's metadata](#fetching-image-alt-text) or from the `altText` [field of a content item](#alt-text-in-the-content-item-json-data) that contains the image.
The `![]()
` tag has two attributes:
- `src` to specify the path to the image
- `alt` to specify alternate text that's descriptive enough to give the reader a sense of what the image is about
Here's an example showing alt text with an `![]()
` tag:
`
`
And here's the rendered image for the above example. Hovering your cursor over the image will display the alt text.
If an image has multiple alt text descriptions for different locales, include the text for your chosen locale in the `alt` attribute. For example:
`
`
## Choosing your approach to supporting alt text
There are different approaches for implementing image alt text:
- Automatic alt text generation (as described on this page): this service works with multiple locales and images for comprehensive alt text support. It uses AI, and requires [Amplience credits](https://amplience.com/developers/docs/ai-services/credits/).
- [Automatic alt text extension](https://amplience.com/developers/docs/ai-services/automatic-alt-text/): can be used in two modes, automatic or generated. In **automatic** mode the extension will retrieve the alt text metadata added to images by the Automatic alt text service. In **generated** mode you can generate alt text on the fly for multiple locales using the [Workforce alt text template](https://amplience.com/developers/docs/workforce/templates/#alt-text). This requires Workforce and uses Amplience credits.
- [Image alt text extension](https://amplience.com/developers/docs/ai-services/image-alt-text/) : a limited approach for generating image alt text on an individual basis. Uses AI and requires Amplience credits.
- Entering and managing alt text yourself: this approach is manual and doesn’t use AI or credits.
### Managing multiple locales with Automatic alt text
When using Automatic alt text generation with Dynamic Content, currently only the default alt text (or the locale variant chosen by the user) will be saved in the [content item metadata](#alt-text-in-the-content-item-json-data).
If you are using field level localization and want to store the alt text for each locale in a localized text field, then you can use the [Automatic alt text extension](https://amplience.com/developers/docs/ai-services/automatic-alt-text/). This extension retrieves existing alt text for each locale from Content Hub, and loads it into the Dynamic Content authoring experience where it can be saved with content.
The extension requires the use of the Automatic alt text service to generate the alt text that is stored in the image metadata, it just makes it easier to manage this text.
You can also generate alt text for multiple locales, directly from the authoring experience, using this extension in **generated** mode.
### Using the Image alt text extension
If you are *not* using Automatic alt text and don't have Workforce, then you can use the [image alt text extension](https://amplience.com/developers/docs/ai-services/image-alt-text/) to generate alt text for images and store the text with your content. However this extension has some limitations:
- It is a [Labs preview](https://amplience.com/developers/docs/ai-services/image-alt-text/) and as such is unsupported.
- Alt text is only generated for US English.
- Unlike Automatic alt text, it is not an automated solution.
- Unlike using the Automatic alt text extension in generated mode, you cannot configure the extension to generate alt text to match your brand guidelines.
### Creating and managing your own alt text
If you are not using Automatic alt text then you can manage your own alt text by adding an alt text string property to your content type schemas to allow users to enter their own alt text for an image. The [media schema example](https://amplience.com/developers/docs/schema-reference/schema-examples/core-concepts/media/) is a very simple example of this approach.
## Related pages
[Viewing and editing generated image alt text](https://amplience.com/developers/docs/user-guides/assets/working-with-assets/auto-alt-text-generation/#viewing-generated-image-alt-text)
[Manifests](https://amplience.com/developers/docs/dev-tools/guides-tutorials/manifests/)
[Workforce Alt text template](https://amplience.com/developers/docs/workforce/templates/#alt-text)
[Automatic alt text extension](https://amplience.com/developers/docs/ai-services/automatic-alt-text/)
[Amplience credits](https://amplience.com/developers/docs/ai-services/credits/)
[Media Delivery API](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/#metadata)