FAQ & troubleshooting

Here you'll find answers to the most common questions – and concrete fixes should an error message ever show up.

Common questions

Do I need my own OpenAI account?

Yes. The plugin uses your own OpenAI key. That way the cost is billed transparently through your account and you stay in control. You can create the key for free at platform.openai.com – see Setting up the OpenAI API key.

What does generating cost?

The plugin license is separate from the OpenAI cost. Per image you only pay a few cents in OpenAI fees – often fractions of that. With GPT-4o mini and low resolution it stays very cheap.

Which languages does the plugin work in?

Since version 1.3.0, in every language your shop has – Polish, Swedish or Czech included. You pick your target languages in the configuration and get a dedicated alt text per language for each image. Leave the target languages empty and the plugin generates in the shop's default language only, just as before. In detail: multilingual alt texts.

Does every extra language cost twice as much?

No – in the default "one request per image" mode the AI returns all languages in a single response. That only adds a few response tokens, not a whole extra request. Only in "one request per image and language" mode does the cost scale linearly with the number of languages.

Do existing alt texts get overwritten?

By default, no. The "Skip existing alt texts" option is enabled and makes sure only what's missing gets generated – per language, too. You can overwrite deliberately via "Regenerate" in the "AI-generated" tab. Generated texts live in the normal alt text field and are flagged as "AI-generated", so you can find them all in one place, edit them or remove them at any time.

I added a new shop language – how do I fill in just that one?

Add the new language to your target languages, leave "Skip existing alt texts" enabled and generate from the "Language missing" tab. Your existing texts are neither touched nor paid for. Step by step under multilingual alt texts.

Do I have to process images one by one?

No. You can select several images with the checkboxes, or work through a whole tab with Generate all – up to 100 images per run. For larger volumes there's Generate in background and the nightly automatic generation, see background & scheduled runs.

Which image formats are supported?

JPG, PNG, GIF and WebP. Other files (PDF, video or SVG, for instance) are skipped.

What happens to my alt texts when I uninstall the plugin?

They stay – in every language. Generated alt texts are perfectly ordinary shop content, so even the "remove all data" option doesn't touch them (it only concerns the plugin's own structures such as history tables and custom field definitions). If you want them gone, use the "Remove all AI alt texts" action in the module before uninstalling – it deletes exactly the languages the plugin wrote and leaves hand-maintained texts alone.

Troubleshooting

If an error occurs for an image, a short message appears in the progress list. Here are the most common ones – and what to do about them.

"API token is not configured"

No OpenAI key is stored. Enter it in the configuration under OpenAI API token. If you use channel-specific settings, make sure you're on the right sales channel.

"No AI model selected"

No model is selected. Pick a model in the configuration (default: GPT-4o mini) and save again.

"Invalid API token"

The key is wrong or expired. Check that you copied it completely and without extra spaces. When in doubt, create a new key at OpenAI and enter that.

"OpenAI Rate Limit reached"

You made a lot of requests in a short time and OpenAI is throttling you temporarily. Wait a moment and start again. Tip: process large batches in smaller chunks.

"The media is not an image"

The selected file is not an image. The plugin only processes image files (JPG, PNG, GIF, WebP).

"Image file could not be found"

The image file wasn't found. Check whether the file exists in the public folder. With offloaded storage (external CDN/cloud storage) the image must be reachable via its URL.

"Generated alt text is too short"

The generated text is shorter than your minimum length. In the configuration, lower the minimum number of characters or raise the maximum response length (tokens) so longer texts can be produced.

One individual language is missing from the result

In "one request per image" mode the AI can occasionally leave a language out of its response. The other languages are saved regardless, and only the missing one is logged as an error. Two things help: repeat the run via "Retry failed", or switch to "one request per image and language" mode for that image.

The background run doesn't start

Background and scheduled runs need Shopware's background services: an active message consumer (messenger:consume) and the scheduled task worker. If either isn't running, the job simply sits in the queue. Details under background & scheduled runs.

An image sits under "Language missing" even though it has an alt text

That's intentional: the tab lists images missing a text in at least one language. The "Languages" column shows you with red and green badges which language is meant. Note that only the explicitly maintained text per language counts – Shopware's language inheritance is deliberately not factored in, since otherwise child languages could never get their own alt texts.