Configure Commerce AI Features
Save provider credentials in Stores → Configuration → Hyvä AI → Settings, and complete Worker Setup. Open Hyvä AI → Hyvä CMS for AI Translation, Generation and Image Generation. Each group appears when its integration is installed. Translation-only installations keep AI Translation under Settings.
Provider accounts, keys and text-model connection tests are covered in Provider Configuration. A successful worker connection test verifies runtime access and secrets; it does not prove that your provider key or chosen model can generate content.
Execution and Inheritance
The shared Run requests using value in Settings is the default. An explicit feature override takes precedence. Keep existing feature choices preserves each feature's existing route.
| Feature | Execution choices |
|---|---|
| AI Translation | Use default, Direct PHP or AI Worker. DeepL always runs directly. |
| Generation | Use default or AI Worker. Inheriting Direct PHP makes this feature unavailable. |
| Image Generation | Use default or AI Worker, independently of Generation. Inheriting Direct PHP makes images unavailable. |
For example, choose Direct PHP globally for short translations, then select AI Worker explicitly in Generation and Image Generation. Alternatively, choose AI Worker globally and override translation to Direct PHP.
AI Worker includes the PHP worker. With Enable External Worker → No and Enable PHP Worker → Yes, configured worker features remain available. A saved external URL is ignored. With an external worker enabled and configured, it takes priority and PHP can provide backup. See runtime selection.
Direct PHP calls a provider through the base AI module. PHP worker execution uses the worker's request and streaming flow on Magento. Neither removes PHP hosting limits; use Node or a serverless worker for the recommended setup.
Generation Models
Under Hyvä CMS → Generation, enable generation and select one Default model and its options. Full pages and planning use this default. The following profiles initially inherit both the model and options:
| Profile | Used for |
|---|---|
| Sections | Individual section generation. |
| Text updates | Plain-text and rich-text writing or rewriting. |
| HTML generation | HTML field generation and rewriting. |
| Instance components | Reusable component definitions and their HTML. |
| Page optimization | Reviewing and improving page content. |
Set Use generation default to No to choose a separate model and options for a profile. Its options are a separate configuration, not a partial merge into the shared model's options. Turning inheritance back on uses the shared default again.
Image Generation has a separate provider/model picker. Clearing its image model disables images. The per-run generation and planning controls can offer another registered model; these are request choices, not personal editor defaults. There is no personal AI-model tab in Editor Preferences.
Image Generation
Image generation requires the worker and CMS integration. The current provider packages register these model families:
| Provider | Models | Official reference |
|---|---|---|
| OpenAI | gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2 |
Image generation. Flare prioritises everyday speed; Sunburst prioritises precise editing/quality. Account verification may be required. |
| Gemini | gemini-3.1-flash-lite-image, gemini-3.1-flash-image, gemini-3-pro-image; older saved gemini-2.5-flash-image |
Gemini models and image generation. |
Commerce AI Worker 1.0.0 supports OpenAI and Gemini image generation. The integration generates one image per request, maps aspect ratios to supported provider sizes and expects image bytes in the response. It does not expose every feature of the upstream image APIs. Image creation needs a separate smoke test; a successful text connection test is insufficient.
Check Each Feature
- Save the worker configuration and run Test Connection. Confirm the intended runtime passes.
- Enable Generation, choose its default model and save. Generate a small section and save it as a draft.
- If images are needed, select and save a separate image model, then generate one image.
- If translations are needed, configure the translation integration and test a small selection of fields.
Feature checks use your provider account
These feature checks call your AI provider and can incur usage charges. Inspect the output before publishing.
Saved configuration paths for developers
Generation defaults remain at hyva_ai/ai_worker_cms/model and model_options; profiles inherit them unless overridden. Images use hyva_ai/ai_worker_cms/image_model and the independent hyva_ai/image_generation/execution_mode. Translation uses hyva_ai/hyva_cms_translations/.... The admin section does not change these stored paths.