What does it do? 

Ai3 Alt Text (|extension_key|) is a TYPO3 extension that automates the creation of accessible alternative texts for images stored in the TYPO3 file storage. It communicates with the ZAK-AI REST API — provided by wegewerk/ai3_core — to generate descriptive, language-aware alt texts using a vision-capable AI model.

The extension adds a dedicated backend module under File > AI3 metadata with two views:

File metadata view

Lists all images in a selected folder. For each image the current alt text, AI-generated suggestion, usage count, and available actions are shown. Editors can generate alt texts individually or in bulk, review suggestions, and approve or edit them before they are saved to the file metadata record.

Folder view

Shows the sub-folder tree of the file storage. Editors can accept all pending AI suggestions across an entire folder hierarchy with a single click.

In addition, a FormEngine field control button is injected into the Alternative Text field of the file metadata edit form, allowing editors to queue a single image for alt text generation without leaving the record editor.

Screenshots 

Requirements 

• TYPO3 CMS |min_typo3|, 13.4, or 14.0
• wegewerk/ai3_core (installed automatically as a Composer dependency)
• A valid ZAK-AI account with ZAKAI_API_KEY and ZAKAI_SECRET environment variables set on the server

Installation via Composer 

The recommended way to install ai3-alttext is via Composer:

composer require wegewerk/ai3_alttext

This will also pull in wegewerk/ai3_core automatically.

Activate the extension 

After installation, activate the extension in the TYPO3 backend:

1. Open Admin Tools > Extensions
2. Find Ai3 Alt Text in the list
3. Click the Activate button

Database update 

No additional database tables are created by this extension. All generation task data is stored via wegewerk/ai3_core .

Run the database analyser after installation to ensure the core tables are up to date:

Admin Tools > Maintenance > Analyze Database Structure

Environment variables 

The following environment variables must be set on the server before the extension can communicate with the ZAK-AI API:

Set these variables in your server environment, .env file, or TYPO3 config/system/additional.php:

putenv('ZAKAI_API_KEY=your-api-key');
putenv('ZAKAI_SECRET=your-secret');

TCA override 

The extension overrides the alternative column of the sys_file_metadata table to add the Add alttext generation to batch field control button. No manual TCA configuration is required.

JavaScript modules 

The extension registers its JavaScript modules under the @wegewerk/ai3alttext/ namespace via Configuration/JavaScriptModules.php. The following modules are available:

Backend module 

The extension adds the AI3 metadata module to the File section of the TYPO3 backend. The module has two sub-views, accessible via the button bar at the top:

• File Metadata — work with images in a specific folder
• Folders — manage suggestions across the folder tree

File metadata view 

Open File > AI3 metadata and select a folder from the folder tree on the left. The main area shows a table of all images in that folder with the following columns:

Folder view 

Switch to the Folders sub-view via the button bar. The view lists all sub-folders of the current storage root together with the number of pending AI suggestions in each folder.

Click Accept %cntGens Suggestions in %cntFolder Subfolders to approve all pending suggestions recursively across the entire folder tree. A flash message confirms how many files were updated.

FormEngine field control 

When editing a file metadata record directly (File > Filelist > Edit metadata), an additional button Add alttext generation to batch appears next to the Alternative Text field. Clicking it queues the current image for alt text generation without leaving the edit form.

The button shows the current generation state:

• No indicator — no generation task exists yet
• In progress — a generation task is currently running
• AI generated — a suggestion is available and waiting for review
• Approved — the suggestion has already been accepted

Architecture overview 

ai3-alttext follows the capability pattern introduced by wegewerk/ai3_core . The central pieces are:

ZakAiAlttext API class 

Wegewerk\Ai3Alttext\Api\ZakAiAlttext implements Wegewerk\Ai3Core\Api\ZakAiEndpointInterface and exposes a single public method:

public function generate(
    string $imagePath,
    string $caption,
    string $language
): string

The method:

1. Verifies the image file exists on disk.
2. Resizes the image to a maximum of 512 × 512 px using ImageService and ImageProcessingService to keep API payload sizes small.
3. Base64-encodes the resized image and POSTs it to the /alttexts endpoint via ZakAiClient::postJson().
4. Returns the alttext string from the API response, or an empty string if the API reports an error.

Ajax routes 

All Ajax endpoints are registered in Configuration/Backend/AjaxRoutes.php:

Capability registration 

AlttextCapability is registered as a DI-tagged service so that the wegewerk/ai3_core capability registry picks it up automatically:

Wegewerk\Ai3Alttext\Domain\Capabilities\AlttextCapability:
    autowire: false
    arguments:
        $key: 'alttext'
        $title: 'Alt Text'
        $endpoint: '@Wegewerk\Ai3Alttext\Api\ZakAiAlttext'
    tags:
        - name: ai3.capability

FormEngine field control 

The field control is registered as a custom FormEngine node in ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['formEngine']['nodeRegistry'][1759225979] = [
    'nodeName' => 'ai3AlttextAddToBatch',
    'priority' => 30,
    'class' => \Wegewerk\Ai3Alttext\FormEngine\FieldControl\Ai3AlttextAddToBatch::class,
];

The TCA override in Configuration/TCA/Overrides/sys_file_metadata.php attaches this node to the alternative field of sys_file_metadata as a fieldControl.

Event listener 

AfterFormEnginePageInitializedEventListener listens to AfterFormEnginePageInitializedEvent and injects the extension language labels into the page renderer so that the JavaScript modules can use them via the TYPO3 inline label API.

0.9 — 2026-06-17 

• Initial release by refactoring from the monolithic Ai3 extension into a dedicated wegewerk/ai3_alttext package