Skip to content

Contentful.com

The AltText.ai app for Contentful CMS lets you add alt text to your images with the click of a button.

Installation

  • Go to our listing on the Contentful Marketplace.
  • Click the Install Now button to add it to your Contentful space.

Setup

  • When you first install the app, you will be prompted to enter your AltText.ai API Key.
  • Get your API Key by logging into your AltText.ai account, then go to Account: API Keys.
  • Copy an existing API Key, or just create a new one to use. Paste it into the Contentful app settings.

The app will also create a new content model called ImageWithAltText. This model contains an image, plus a text field for alt text. You'll use this whenever you need alt text generated for an image in your system.

Note

When description sync is enabled, the Contentful app copies generated alt text into the image's native Description field. Bulk Update also writes generated text to that field.

Adding Alt Text to Images

To add alt text to an image, just create a new ImageWithAltText entry. You'll see a field to select or upload an image, along with a button to automatically generate the alt text using AltText.ai. You can even add your own SEO keywords that will be blended into the generated alt text:

Adding alt text in Contentful.

Click the Generate Alt Text button, and ... boom! You have alt text for your image.

Alt text added with AltText.ai

Bulk Updating All Images

Our app for Contentful also gives you the ability to bulk update your existing library of images.

  1. From the Apps menu, select AltText.ai: Bulk Update:

    Bulk update menu in the AltText.ai Contentful app.

  2. You will be shown how many images are in your library, along with a setting to control whether or not to skip images that already have alt text. Make your selection, then click the Start button to begin processing your images:

    Bulk update configuration screen.

Bulk Update Image Requirements

The Contentful app processes an asset only when its file is available in the space's default locale and meets all of these requirements:

  • Format: BMP, PNG, GIF, WebP, JPG, or JPEG
  • File size: smaller than 10 MB
  • Dimensions: at least 50 × 50 pixels

Other formats—including SVG, AVIF, HEIC, and TIFF—are not processed by the current Contentful app even if another AltText.ai integration supports them. Assets outside these rules are added to the Failed to process count before they are sent to AltText.ai, so they do not use generation credits.

Generation, Writeback, and Publication

These are three separate states in Contentful:

  1. Generation: AltText.ai creates the text.
  2. Writeback: The Contentful app updates the asset's native Description field.
  3. Publication: You publish that changed asset in Contentful.

The app updates the asset draft; it does not automatically publish the asset. Contentful can therefore show the asset as Changed or unpublished after a successful writeback. Review the Description field and publish the asset when you are ready.

A writeback can also fail after generation. The app updates the asset using the version it fetched from Contentful. If another person or process changes that asset first, Contentful can reject the write with a 409 VersionMismatch response. The app adds that asset to Failed to process, but the generated text can still exist in AltText.ai because generation happens before the Contentful writeback. Reload the Contentful app and retry after concurrent edits have stopped; contact support with the affected asset link if the conflict continues.

Warning

Completed bulk progress does not by itself prove that every asset writeback succeeded or that any changed asset was published. Check the bulk results for failed assets, then inspect the asset's Description and publication status in Contentful. The general AltText.ai Image Library cannot verify Contentful publication state.