Quick start 

1. Install the package with Composer.
2. Apply the database schema update.
3. Open Media > AutoAlt.ai > Extension Configuration.
4. Connect an existing AutoAlt.ai API key or register with your email.
5. Open Bulk Alt Text Generator, review the choices, and process a small test set before running your full media library.

For the detailed steps, see Installation.

Table of Contents

What AutoAlt.ai does 

Alt Text Generator - AutoAlt.ai connects TYPO3's media library to the AutoAlt.ai image-description service. It helps editors find images that need attention and create a first draft of their metadata directly in the TYPO3 backend.

The extension works with TYPO3 FAL metadata. It does not require editors to download images or leave their normal media workflow.

Benefits 

• Save editorial time: create metadata for one image, selected files, or an entire eligible media library.
• Improve media quality: find missing and unusually short alternative text, and identify weak filenames.
• Keep control: choose independently whether to generate, keep, or clear alternative text, title, and description in a bulk run.
• Support consistent output: use a writing style, character range, keywords, negative keywords, a custom prompt, and optional prefix/suffix.
• Work safely in TYPO3: permissions, FAL file mounts, metadata edit permissions, history, logs, and reversible filename changes are respected.
• Support multilingual sites: generated metadata can be translated for active TYPO3 site languages.

Main features 

Requirements 

• TYPO3 13.0.0 through 14.3.99
• PHP 8.2 or later
• Composer-based TYPO3 installation
• An AutoAlt.ai account and a valid API key, or access to email registration
• Network access from the TYPO3 server to the AutoAlt.ai service

Supported image types 

The default setting includes jpg, jpeg, png, webp, gif, avif, and svg. Administrators can change the allowed list in Configuration/Index.

Accessibility and SEO 

Good alternative text depends on the image's purpose in the page or content element. AutoAlt.ai helps create and review drafts, but editorial review remains important:

• Leave decorative images empty when they do not convey information.
• Describe the purpose of functional images, such as buttons or links.
• Add human-written explanations for complex charts, diagrams, and images that require context not present in the image.
• Use keywords only when they are relevant; do not use the extension for keyword stuffing.

Privacy and support 

Review the AutoAlt.ai Privacy Policy and your organisation's data-protection requirements before enabling generation. For product help, see the AutoAlt.ai TYPO3 guide. For defects or feature requests, use the GitHub issue tracker.

Install with Composer 

Run the command from the root directory of the Composer-based TYPO3 project:

composer require autoaltai/alt-text-generator

Composer installs the package and publishes its TYPO3 public assets. If the extension is not activated automatically, activate all newly installed extensions:

vendor/bin/typo3 extension:setup

Apply the database schema 

The extension stores its configuration, generation history, error log, and rename history in TYPO3 database tables. Apply the database changes before opening the module:

• In the TYPO3 backend, open Admin Tools > Maintenance > Analyze Database Structure and apply the suggested changes; or

• Run the following command, which activates newly installed extensions and performs their database migrations:

  vendor/bin/typo3 extension:setup

  Copied!

Open the module 

Sign in as a TYPO3 administrator. In the backend navigation, open:

Media > AutoAlt.ai > Extension Configuration

The first page shows the connection card and the current configuration.

Connect an existing AutoAlt.ai account 

1. Obtain an API key from your AutoAlt.ai account.
2. In the Connect with API key card, paste the API key.
3. Select Connect & Save.
4. Check that the status changes to Connected and that a credit balance is displayed.

Register or sign in with email 

If you do not already have an API key:

1. Open Media > AutoAlt.ai > Extension Configuration.
2. In the Login / Register card, enter your email address.
3. Select Send verification code.
4. Enter the six-digit code sent to your email.
5. Select Verify code.

The extension creates or connects the account and saves the resulting API key in its TYPO3 configuration.

First-run checklist 

Before processing a complete media library:

1. Review the options in Configuration/Index, especially the allowed image types, overwrite setting, title/description generation, and keywords.
2. Start with a small set of test images using Bulk Alt Text Generator.
3. Review the generated values in the TYPO3 File List or Alt Text History.
4. Adjust your instructions if needed.
5. Enable automatic generation on upload only after you are satisfied with the output.

Security of API keys 

Never commit an AutoAlt.ai API key to Git, a deployment script, a screenshot, or a support ticket. If it has been exposed, revoke or rotate it in AutoAlt.ai and save a replacement in the extension configuration.

Upgrading 

For every extension update:

1. Update the Composer package.
2. Run vendor/bin/typo3 extension:setup.
3. Review and apply any proposed changes in the Database Analyzer.
4. Flush TYPO3 caches if the backend does not show the new assets or module changes.

See Troubleshooting/Index when an update does not complete as expected.

Uninstalling 

Uninstalling AutoAlt.ai removes all data owned by the extension. This includes the configuration, generation history, rename history, error-log tables, legacy extension configuration, and AutoAlt.ai entries in TYPO3's system log. It does not undo generated values in sys_file_metadata or rename files, because those records and files are owned by TYPO3 and may have been edited after generation.

For a Composer installation, register the following root-project Composer script. Composer intentionally runs only scripts declared by the root project, not scripts from dependencies. This project already contains the registration. Other Composer projects should add it before running composer remove autoaltai/alt-text-generator:

{
  "scripts": {
    "pre-package-uninstall": "AutoAltAi\\AltTextGenerator\\Composer\\UninstallCleanup::onPrePackageUninstall"
  }
}

The bridge calls vendor/bin/typo3 autoalt:cleanup while the extension is still available, before Composer deletes its package files.

In TYPO3 13, Extension Manager deactivation invokes the same cleanup through the package-deactivation event. If an installation has disabled Composer scripts, run the command manually before removing the package:

vendor/bin/typo3 autoalt:cleanup

The command is idempotent: it succeeds when some or all AutoAlt.ai tables have already been removed. A later installation followed by the normal schema setup creates empty tables, so no previous AutoAlt.ai history is restored.

Connection 

Use the connection card to add, replace, or remove the AutoAlt.ai API key. The card also displays the connection state and available credit balance.

Data sent for generation 

To generate text, the extension sends the image content to the AutoAlt.ai service together with the generation settings needed for the request. Depending on the action, this can include the image filename, site language, requested metadata fields, writing style, character limits, keywords, negative keywords, prefix/suffix, and custom prompt.

Review the AutoAlt.ai Privacy Policy and your organisation's data-protection requirements before enabling the extension. Do not use prompts or metadata to transmit passwords, API keys, or unnecessary personal or confidential information.

Automation and file selection 

jpg,jpeg,png,webp,gif,avif,svg

Generation defaults 

SEO guidance and custom instructions 

Describe the product clearly. Include material and colour only when they
are visible. Do not make claims that cannot be seen in the image.

Bulk completion notification 

Enable Email notification on bulk completion and provide a recipient address if an administrator should be notified after a bulk run finishes. The TYPO3 installation must have working mail transport for this feature.

Error logs 

The settings page displays recent AutoAlt.ai errors and provides a Clear logs action. Errors are also sent to TYPO3's standard logging system and can be reviewed in System > Log. See Troubleshooting/Index for common causes.

Language behaviour 

The extension uses the TYPO3 site's default language as the source for generation and can create translations for active site languages. Existing editor-written translations are protected unless an overwrite option applies. Review translated content for terminology, product names, and legal wording.

Start at the dashboard 

Open Media > AutoAlt.ai > Bulk Alt Text Generator. The dashboard shows:

• the total number of images and the number missing alt text;
• images with short alt text, based on the configured threshold;
• the available AutoAlt.ai credit balance; and
• the current actions for alt text, title, and description.

Use the action choices to decide what happens when a field is encountered:

• Generate replaces that field with a new AI-generated value;
• Keep leaves the current value unchanged; and
• Clear removes the current value.

Choose Generate for Alternative Text when you want missing descriptions created. A safe starting point is Keep for Title and Description, then enable generation for those fields after reviewing a small batch.

Add optional SEO keywords and negative keywords for the current run. Separate phrases with commas and use only terms that genuinely describe the image or its page context.

Generate metadata in bulk 

1. Select the actions for Alt Text, Title, and Description.
2. Optionally enter SEO keywords and negative keywords.
3. Select any applicable filters, such as processing images with existing alt text, skipping images already processed by AutoAlt.ai, or limiting the run to images whose alt text is shorter than the configured threshold.
4. Review the number shown on the Generate button and start the batch.
5. Keep the browser tab open until the progress panel reports completion.
6. Review generated records in Media > Filelist or in Media > AutoAlt.ai > Alt Text History.

Bulk processing is browser-driven AJAX processing. Closing the tab, losing the browser connection, or putting the computer to sleep stops further requests. Start the batch again to continue with images that remain eligible.

Use a small first batch whenever you change a prompt, keyword, language, or field action. This is the quickest way to verify the results before processing the entire media library.

Generate one image 

Open an image metadata record in Media > Filelist. The Alternative Text field has a Generate with AutoAlt.ai control for users who have permission to use it. Generate the text, review it, and save the metadata record.

This workflow is useful for important editorial images where the editor wants to choose the final wording themselves.

Use the Filelist action 

In Media > Filelist, select one or more image files or folders and choose the AutoAlt.ai bulk-generation action. Folder selections are expanded to their eligible image files. Unsupported extensions and files that the editor cannot modify are skipped.

This is helpful when an editor has just uploaded a campaign folder and wants to process only that folder rather than the whole media library. Keep the browser tab open until the progress indicator completes.

Generate automatically on upload 

When Auto-generate on upload is enabled in the extension configuration, eligible images receive generated metadata when they are added to a TYPO3 FAL storage. Existing alternative text is preserved unless Overwrite existing alt text is also enabled.

Enable Automatically Rename Uploaded Image Files to create an AI-generated, lowercase, hyphenated filename for eligible new uploads. The extension preserves the original file extension and lets TYPO3 FAL keep file references intact. A duplicate filename receives an available numeric suffix. This option is off by default; test it with a small upload folder before enabling it for editors.

Enable this only after testing the configured prompt and field behavior. It is best suited to media libraries with a consistent editorial process.

Rename image files with AI 

Open Media > AutoAlt.ai > Bulk Rename Images to review image filenames and generate SEO-friendly replacements. You can filter the list, select files, and either rename manually or request an AI name. The preview/audit view helps identify poorly named files before making changes.

Before running a batch:

• Verify that the suggested filename accurately represents the image.
• Keep names concise, meaningful, and free of keyword stuffing.
• Confirm that the current backend user has permission to modify the storage.
• Consider testing with a few files first.

TYPO3's FAL references remain connected after a supported rename. The module records rename activity in its history and provides an undo option where the previous filename is available. Read-only or unsupported files are skipped.

Review history and retry failures 

Media > AutoAlt.ai > Alt Text History lists generation attempts with their source, status, language, generated values, and error information. Use the filters to find a specific task. Failed generation attempts can be retried, and metadata values can be reviewed and edited inline.

History is an operational record, not a substitute for normal TYPO3 backups. Keep regular backups before major metadata or filename clean-up campaigns.

Use site languages deliberately 

The extension uses TYPO3 site-language information for multilingual work. Configure the site languages in TYPO3 first, then test a representative image in each language. Review translations and brand terms before bulk processing; AI output should be editorially checked in every language.

Credits and safe operation 

The dashboard displays the credit balance returned by AutoAlt.ai. Generation and AI-assisted file operations can consume credits. Review the remaining balance before a large batch and stop the process if results are not suitable.

Do not place API keys, user credentials, or other secrets in keywords, prompts, filenames, or image metadata.

Backend access and permissions 

Grant a backend user group access to Media > AutoAlt.ai in the usual TYPO3 backend module permissions. Users also need access to the relevant FAL storage and permission to edit file metadata. The extension does not bypass TYPO3 file mount or metadata permissions.

For more granular control, add the following Page TSconfig to a backend user or group configuration:

tx_alttextgenerator.permissions {
    generateSingle = 1
    runBulkGeneration = 1
    manageSettings = 0
}

The values are booleans:

• generateSingle permits the one-image generation control in Filelist.
• runBulkGeneration permits bulk generation workflows and retries.
• manageSettings permits access to the extension settings screens.

Set permissions to 0 where the user should not perform that task. Users must still have the ordinary TYPO3 permissions required for the affected files and metadata records.

API connection and credentials 

Open Media > AutoAlt.ai > Extension Configuration to connect the site to AutoAlt.ai. A user can connect with an existing API key or create/connect an account through the email verification flow.

Treat the API key as a secret:

• Enter it only in the TYPO3 configuration screen or a secure deployment configuration.
• Never commit it to Git, documentation, screenshots, tickets, or browser console logs.
• Rotate the key immediately if it is exposed.
• Remove or replace the key before transferring a site to another team.

Recommended rollout 

1. Install the extension and apply the database schema.
2. Connect a test or production API key.
3. Configure allowed file extensions, writing style, length, and optional keywords.
4. Test one or two representative images in every required language.
5. Run a small batch and have an editor review the output.
6. Enable upload automation only when results are consistently suitable.
7. Give bulk and settings permissions only to users who need them.

This staged rollout keeps metadata quality under editorial control and helps avoid accidental changes to an entire library.

Logging and monitoring 

Enable API-error logging in the extension configuration when diagnosing connection or generation problems. Entries are written through TYPO3's logging framework and can be reviewed in System > Log. The extension also displays recent entries in its Settings error-log panel, where they can be cleared after review.

Check the following after a deployment or configuration change:

• API connection status and credit balance;
• a single test generation;
• TYPO3's System > Log for errors; and
• the extension history for unexpected failures or skipped files.

Upgrades and backups 

Before an extension update, back up the database and application files using your normal TYPO3 deployment process. After updating Composer dependencies, run the extension setup command, then review any proposed changes in the Database Analyzer:

vendor/bin/typo3 extension:setup

Clear TYPO3 caches, verify the connection, and run a small generation test before starting a production batch. Review the release notes and the Changelog for each update.

The extension cannot connect to AutoAlt.ai 

1. Open Media > AutoAlt.ai > Extension Configuration.
2. Verify the API key or reconnect through the email verification flow.
3. Confirm that the server can make outbound HTTPS connections to the AutoAlt.ai service.
4. Check TYPO3's System > Log and the extension error-log panel.
5. If a key may have been shared or committed, rotate it before trying again.

No images appear in a bulk run 

Check the following:

• The image extension is in the allowed-image-extension setting.
• The selected filters do not exclude the image, for example because it was already processed or already has alternative text.
• The current backend user has a File Mount for the storage and permission to edit its metadata.
• The image is a supported file in a writable storage.
• There is sufficient AutoAlt.ai credit balance.

Bulk progress stops 

Bulk workflows require an open browser tab. Keep the page open and avoid browser sleep, network disconnects, or navigating away while processing. If it stops, inspect History/System Log, then start a new batch; the filters can skip items that completed successfully.

Generated text is not suitable 

Use a small test batch and adjust the configuration:

• refine the writing style, prefix, suffix, or custom prompt;
• use accurate SEO and negative keywords sparingly;
• choose Keep for Title or Description if you only want alt text;
• set a sensible length range; and
• review language configuration and sample output for each site language.

Generated content is a draft. It must be reviewed by the responsible editor and does not by itself guarantee accessibility, legal, or SEO compliance.

File rename fails or is skipped 

Confirm that the file is in a writable FAL storage and that the backend user has the required storage access. Unsupported files and read-only storages are skipped. Review the rename history and TYPO3 System Log for the specific reason, then retry after correcting the permission or storage issue.

Where to get help 

Before contacting support, collect the TYPO3 version, extension version, relevant history entry, timestamp, and the exact error message. Do not include an API key or other credentials.

• Documentation: https://www.autoalt.ai/docs/typo3/
• Issue tracker: https://github.com/autoaltai/alt-text-generator/issues
• Support: support@autoalt.ai

1.0.7 

• Restored the AutoAlt.ai backend module placement in TYPO3 13 while retaining its TYPO3 14 Media-module placement.
• Made Filelist bulk-generation progress handling compatible with TYPO3 13 progress-bar elements.
• Updated the single-image metadata control to use the TYPO3 13-compatible FormEngine validation API.
• Updated the backend module icon and release/update documentation.
• No manual data migration or configuration change is required. Existing AutoAlt.ai settings, history, and API connections remain unchanged.

1.0.6 

• Added automatic uninstall cleanup for TYPO3 13 Extension Manager and Composer package removal.
• Removes the AutoAlt.ai configuration, generation history, rename history, error-log tables, legacy settings, and related TYPO3 system-log entries.
• Reinstalling the extension now starts with newly created, empty tables.

1.0.5 

• Added safe plugin data synchronization with AutoAlt.ai.
• Added automatic SEO-friendly filename generation after image upload.
• Added the Automatically Rename Uploaded Image Files setting.
• Improved compatibility with warmed TYPO3 controller caches.