Table of Contents

  1. Ext: sg_ai
  2. SG AI for TYPO3: End-User Documentation
  3. AI Watermark Overlay API

Ext: sg_ai

sgalinski logo

License: GNU GPL, Version 3

Repository: https://gitlab.sgalinski.de/sg-ai/sg_ai

Please report bugs here: https://gitlab.sgalinski.de/sg-ai/sg_ai/-/work_items

Overview

sg_ai brings AI-assisted editorial workflows directly into TYPO3 backend forms and modules.

The extension covers:

  • Alt text generation for images (sys_file_reference and sys_file_metadata)
  • AI image generation in file fields (including automatic file reference creation)
  • AI text generation in configured text fields
  • SEO title/description generation for pages and social meta fields
  • Technical SEO, content SEO, and accessibility recommendations
  • Queue-based background processing for long-running operations
  • Backend history views for queued/generated AI results
  • Prompt persistence for image generation (including image settings block)
  • Automatic SEO-friendly image filename generation based on alt text

For end-user focused documentation, see:

Requirements

  • TYPO3 v13 LTS (13.4)
  • PHP >= 8.3
  • Valid SG AI API key

Installation

  1. Install extension:
composer require sgalinski/sg_ai
  1. Activate extension in Extension Manager.
  2. Run database schema updates in TYPO3 Install Tool / Admin Tools.
  3. Configure extension settings (see next section).

Configuration

Open:

  • Admin Tools > Settings > Extension Configuration > sg_ai

Available extension settings (ext_conf_template.txt):

  • apiKey
  • useImageAnalysis
  • useBase64Encoding
  • useContextForAltText
  • language
  • watermarkEnabled
  • watermarkOverlayEnabled
  • watermarkPreserveMetadataOnProcessing
  • watermarkBadgeAssetPath
  • watermarkPosition
  • watermarkMargin
  • watermarkRelativeSize
  • watermarkMaxWidth
  • watermarkMaxHeight
  • watermarkOpacity
  • watermarkMinWidth
  • watermarkMinHeight
  • watermarkScreenReaderLabelEnabled
  • watermarkScreenReaderSuffix
  • watermarkOverlayAccessibilityLabel

Recommended API key setup:

  • Preferred: provide SG_AI_API_KEY as environment variable (for example in .env.local)
  • Alternative: set apiKey directly in extension configuration

AI Image Watermarking

  • Watermark overlays are applied via PSR-14 image-rendering events.

  • sg_ai provides a frontend SASS partial for overlay positioning at Resources/Public/Sass/Bootstrap5/_sg-ai.scss.

  • Theme integrations (for example project-theme) should import this partial.

  • watermarkEnabled=1 means watermark logic is active for images marked as AI-generated (tx_sgai_is_ai_generated in metadata or file references).

  • watermarkOverlayEnabled=1 enables frontend HTML/CSS overlay badge rendering (default: 0, disabled).

  • watermarkPreserveMetadataOnProcessing=1 sets SG AI provenance metadata during TYPO3 processing in the same ImageMagick call.

  • Mode-only override is available via sgAiWatermarkMode (on|off).

  • Structured per-call override is available via sgAiWatermarkOverride and supports: mode|enabled (on|off|true|false|1|0), badgeAssetPath, position, margin, relativeSize, maxWidth, maxHeight, opacity, minWidth, minHeight, overlayAccessibilityLabel, screenReaderSuffix, screenReaderLabelEnabled.

  • Default badge asset is a high-resolution PNG (Resources/Public/Icons/ai-watermark-badge.png).

  • Watermark badge sizing uses watermarkRelativeSize and is capped by default via watermarkMaxWidth / watermarkMaxHeight (80/80); set either to 0 for no cap.

  • Accessibility suffix behavior is configurable through watermarkScreenReaderLabelEnabled and watermarkScreenReaderSuffix and keeps alt and aria-label synchronized for non-decorative images.

  • Watermark badge accessibility text (alt/aria-label) is configurable through watermarkOverlayAccessibilityLabel and supports LLL translation references.

  • watermarkScreenReaderSuffix and watermarkOverlayAccessibilityLabel both support LLL translation references.

  • Optional overlay API integration for custom ViewHelpers is documented in Docs/Developer/WatermarkOverlayApi.md.

What the HTML overlay does:

  • It appends additional markup (<span class="sgai-watermark-overlay">...) to the rendered image/picture HTML.
  • CSS positions this badge absolutely on top of the image.
  • No image pixels are changed in this mode.
  • The required CSS contract and fallback examples are documented in Docs/Developer/WatermarkOverlayApi.md.

Integrator Example (Event-Based Integration)

After generating image markup, dispatch AfterImageRenderingEvent:

$event = new \SGalinski\SgAi\Event\AfterImageRenderingEvent(
	$imageHtml,
	$file,
	[
		'width' => $width,
		'height' => $height,
		'accessibleText' => $alternative,
		'isDecorative' => $alternative === '',
		'sgAiWatermarkOverride' => [
			'mode' => 'on',
			'badgeAssetPath' => 'EXT:site_package/Resources/Public/Icons/custom-ai-badge.svg',
			'maxWidth' => 40,
			'maxHeight' => 40,
		],
	]
);
$event = $eventDispatcher->dispatch($event);
$imageHtml = $event->getImageHtml();

Integrating Into Any Renderer (Recommended)

Use your existing image rendering pipeline and dispatch SGalinski\SgAi\Event\AfterImageRenderingEvent after generating image HTML. SG AI listens to this event and applies overlay/accessibility updates.

This keeps image rendering in one place and avoids duplicate integration paths.

Implementation outline:

  1. Render your image markup (<img> or <picture>) in your own ViewHelper/renderer.
  2. Create and dispatch AfterImageRenderingEvent with:
    • the rendered HTML
    • the resolved FileInterface
    • render context (width, height, accessibleText, isDecorative, optional override keys)
  3. Return getImageHtml() from the dispatched event object.

Integrator Example (Direct Overlay API)

For rendering pipelines without events, use:

$overlayService = GeneralUtility::makeInstance(\SGalinski\SgAi\Service\AiImageWatermarkOverlayService::class);
$overlayResult = $overlayService->buildPictureOverlayResult($file, [
	'width' => $width,
	'height' => $height,
	'accessibleText' => $alternative,
	'isDecorative' => $alternative === '',
	'sgAiWatermarkOverride' => [
		'mode' => 'on',
	],
]);

$overlayMarkup = (string) ($overlayResult['overlayMarkup'] ?? '');
if ($overlayMarkup !== '') {
	$imageHtml .= $overlayMarkup;
}

Why this pattern is recommended:

  • It avoids full-page HTML middleware scanning.
  • It keeps SG AI decision logic centralized and reusable.
  • It supports per-render overrides without custom data attributes.

Required Queue Setup (2.x)

Queue processing must be active for asynchronous tasks.

Required scheduler command:

vendor/bin/typo3 sg_ai:process-queue

Recommended execution interval:

  • every 5 minutes (*/5 * * * *)

Setup options:

  1. Backend shortcut:
    • Open module group AI Assistant > Dashboard
    • Click Create scheduler task now if inactive warning is shown for the queue worker
    • Optionally create additional tasks directly there:
      • sg_ai:cleanup-queue (daily)
      • sg_ai:generate-seo-meta (nightly)
      • sg_ai:generate-alt-texts (early morning)
      • sg_ai:generate-ai-recommendations --limit=25 (weekly, can consume many credits)
  2. Manual scheduler setup:
    • Open TYPO3 Scheduler module and create Execute console commands tasks in group SGAI
    • Use the same command/interval recommendations as shown in the dashboard cards

SGAI MCP Auto-API Setup

sg_ai can automatically expose a site-scoped MCP API (sgai_mcp) via sg_apicore.

Important: there are two different MCP servers

To avoid confusion, treat these as separate integrations:

  • SGAI Cloud MCP: your existing MCP for SG AI platform functions (external to TYPO3).
  • SGAI TYPO3 MCP: the MCP auto-generated by this extension for TYPO3 content/data access.

They use different endpoints and usually different tokens. Tokens are not interchangeable.

Recommended client naming:

  • sgai for SG AI platform MCP (existing/released name)
  • sgai_typo3 for TYPO3 MCP (sgai_mcp)

Setup flow:

  1. Open AI Assistant > Dashboard
  2. In SGAI TYPO3 MCP, review the entitlement state shown in the card:
    • Included: TYPO3 MCP is available on the current SG AI subscription
    • Trial: a 14-day TYPO3 MCP trial is active
    • Upgrade required: TYPO3 MCP is not available until the SG AI account is upgraded to Silver or higher
    • Expired: previously active TYPO3 MCP access is no longer active
  3. If the card shows Upgrade required and the account is eligible, click Start 14-day TYPO3 MCP trial.
  4. Once the card shows Included or Trial, choose the target site and click Enable SGAI TYPO3 MCP
  5. Copy the one-time token shown in the modal (it is not shown again on reruns)

Canonical MCP endpoint:

  • /api/sgai_mcp/v1/mcp

Compatibility alias endpoint:

  • /sgai_mcp/mcp

Behavior:

  • v1 supports one active target site per TYPO3 instance.
  • TYPO3 MCP access is driven by the locally stored package and trial state in TYPO3.
  • TYPO3 MCP setup and runtime usage are available only when the locally stored state allows it:
    • paid access on Silver or higher, or
    • an active 14-day TYPO3 MCP trial
  • Permissions are compiled from backend group SGAI MCP (tables_select, tables_modify, non_exclude_fields).
  • Permission changes on that group trigger immediate sync; fallback sync is available via scheduler/CLI:
    • vendor/bin/typo3 sg_ai:mcp:sync
  • Fail-closed: if the managed SGAI MCP backend group is missing, compiled MCP resources are cleared until setup/sync is run again.
  • Opening the SG AI dashboard refreshes the local package snapshot from /v1/credits.
  • MCP runtime uses only the local snapshot and never performs a remote entitlement request in the request path.
  • If the local trial is expired or the last known package state is stale or not eligible, setup and runtime usage stay blocked until the dashboard refreshes the package snapshot again.

How MCP setup works internally

When you click Enable SGAI TYPO3 MCP, sg_ai performs a deterministic sync, not a one-time wizard:

  1. Resolves the selected site (or auto-selects when exactly one site exists).
  2. Creates or updates backend group SGAI MCP with default table/field permissions and DB mount.
  3. Compiles MCP resources and scopes from that group:
    • tables_select -> list,get
    • tables_modify -> create,update,delete
    • special case: sys_file stays a read-only MCP resource, but tables_modify=sys_file still compiles the write scope sgai_mcp:sys_file:write for upload tools
  4. Creates or reuses one token for API sgai_mcp and synchronizes its scopes.
  5. Persists setup state (site/group/token/resource/signature/timestamp) in TYPO3 registry.
  6. Invalidates API/discovery caches.

Repeated clicks are safe and expected:

  • If configuration changed, they resynchronize state/resources/scopes.
  • If token already exists and is reusable, it is reused (no historical plaintext token is shown again).
  • A new plaintext token is returned only when a new token record had to be created.

Dashboard behavior:

  • Before setup, the dashboard card shows one of four entitlement states:
    • Included
    • Trial
    • Upgrade required
    • Expired
  • Depending on that entitlement state, the primary action becomes:
    • Enable SGAI TYPO3 MCP
    • Start 14-day TYPO3 MCP trial
    • or a disabled setup button plus Manage plan
  • After setup, the card switches to Disable SGAI TYPO3 MCP and exposes compact TYPO3 MCP client configuration examples inline.
  • Disabling MCP hides the managed backend group, revokes the active token, clears compiled MCP state, and removes the MCP surface until setup is run again.
  • The card also shows the current plan, optional trial end timestamp, and the last successful entitlement check.

When a new token is created

A new MCP token is created only if no reusable token can be found:

  • The stored preferred token UID is missing/invalid/revoked/deleted, and
  • No active reusable token exists for api_id=sgai_mcp + selected tenant/site.

Otherwise the existing token is reused and updated (scopes, tenant, pid, label).

MCP client configuration (Codex, Cursor, Junie, ...)

sg_ai exposes a standard HTTP MCP endpoint. For Codex-style clients, configure:

  • URL: canonical /api/sgai_mcp/v1/mcp (or alias /sgai_mcp/mcp)
  • Auth: use bearer_token_env_var

Recommended: use the canonical endpoint in clients and keep alias only for backward compatibility.

Use separate environment variables for the two MCP tokens:

  • SGAI_API_TOKEN for SG AI platform MCP (existing)
  • SGAI_TYPO3_API_TOKEN for TYPO3 MCP

Example shell exports:

export SGAI_API_TOKEN="..."
export SGAI_TYPO3_API_TOKEN="..."

Example (Codex-style TOML, TYPO3 MCP only):

[mcp_servers.sgai_typo3]
bearer_token_env_var = "SGAI_TYPO3_API_TOKEN"
transport = "http"
url = "https://your-site.example/api/sgai_mcp/v1/mcp"

Example (Codex-style TOML, both MCP servers):

[mcp_servers.sgai]
bearer_token_env_var = "SGAI_API_TOKEN"
transport = "http"
url = "https://sgai.mateevsolutions.com/api/sgai/v1/mcp"

[mcp_servers.sgai_typo3]
bearer_token_env_var = "SGAI_TYPO3_API_TOKEN"
transport = "http"
url = "https://your-site.example/api/sgai_mcp/v1/mcp"

Example (JSON-style clients such as Cursor/Junie variants, TYPO3 MCP only):

{
  "mcpServers": {
    "sgai_typo3": {
      "transport": "http",
      "url": "https://your-site.example/api/sgai_mcp/v1/mcp",
      "bearer_token_env_var": "SGAI_TYPO3_API_TOKEN"
    }
  }
}

tt_content positioning for MCP clients

When creating TYPO3 content elements through sgai_typo3, the default TYPO3 behavior is position=top.

For tt_content create endpoints, the generated MCP/OpenAPI description now exposes two optional request fields:

  • position: top, bottom, or after
  • afterUid: required when position=after

Behavior:

  • top: insert at the top of the target placement context
  • bottom: insert after the last sibling in the same pid, colPos, and sys_language_uid context
  • after: insert directly after an existing tt_content record

Notes for MCP clients:

  • position defaults to top if omitted.
  • afterUid must reference an existing tt_content record.
  • If position=after and pid, colPos, or sys_language_uid are omitted, they are inherited from the referenced record.
  • For column-aware placement, pass colPos when that field is available in the resource schema.

AI image generation flow for MCP clients

sgai_typo3 now exposes one dedicated MCP tool for TYPO3 content images:

  • generate_and_attach_image_to_content
  • generate_and_attach_image_to_page

This is the preferred image workflow for MCP clients. The TYPO3 backend uses its configured SG AI API key, generates the image server-side, stores it in TYPO3 FAL, creates the sys_file_reference, and attaches it to the correct TYPO3 media field for the target record.

Recommended flow for adding an image to tt_content.image:

  1. Create the target content element.
  2. Call generate_and_attach_image_to_content in sgai_typo3.

Example tool arguments:

{
  "contentUid": 456,
  "prompt": "Editorial hero image about TYPO3 AI workflows, modern office scene, realistic, clean composition",
  "imageSize": "landscape_16_9",
  "outputFormat": "png"
}

Expected result:

{
  "contentUid": 456,
  "fileUid": 123,
  "fileReferenceUid": 987,
  "publicUrl": "/fileadmin/user_upload/ai_generated/editorial-hero-image.png",
  "altText": "Editorial hero image about TYPO3 AI workflows"
}

Notes:

  • sgai_typo3 still exposes sys_file as a read-only resource so stored files can be listed and found later.
  • The tool requires a configured SG AI API key in the TYPO3 backend.
  • It requires sgai_mcp:tt_content:write, sgai_mcp:sys_file:write, sgai_mcp:sys_file_reference:write, and sgai_mcp:sys_file_metadata:write.
  • For CType=textmedia, generate_and_attach_image_to_content writes to tt_content.assets. For standard image-based content elements, it usually writes to tt_content.image.
  • tt_content.image is a built-in non-exclude field in TYPO3, so no separate non_exclude_fields entry is required for it.
  • generate_and_attach_image_to_page works for pages.media and pages.og_image, defaults to media, and requires sgai_mcp:pages:write plus the same file-related write scopes. Because both page fields are exclude fields, the managed backend group must allow pages:media and/or pages:og_image for the targets you want to use.

Localize a page before editing translated fields

Use localize_page to create or reuse the translated page record first. Then call pages.update on the returned localizedPageUid.

Example flow:

  1. localize_page with: 
    {
  "pageUid": 123,
  "languageUid": 1
}
  2. pages.update on the returned localized page UID with translated fields such as title, slug, description, or seo_title.

Filtering examples for MCP clients

List endpoints use the filter shape filter[field]=value.

Typical pages examples:

{
  "filter": {
    "title": "News"
  }
}

{
  "filter": {
    "slug": "/news"
  }
}

Do not send title or slug as top-level arguments for list tools. They must be nested inside filter.

Client notes:

  • Keep tokens in environment variables or client secret storage. Do not hardcode credentials in VCS.
  • If you rotate/revoke token records in TYPO3, update client configs with the new token.
  • Effective tool/resource exposure is driven by the SGAI MCP backend group's permissions and token scopes.

Backend Usage

Modules

  • AI Assistant (/module/web/ai-assistant)
    • Backend module group for SG AI workflows
  • Dashboard (/module/web/sg-ai-dashboard)
    • Overview for all SG AI modules, onboarding checklist, scheduler status/setup
  • AI Page Insights (/module/web/sg-ai)
    • Unified workspace for analysis and history (tabs in one module)
    • Run URL checks, trigger recommendation tasks, monitor active queue work, and inspect/reuse past results
  • Legacy AI History URL (/module/web/sg-ai-history)
    • Redirects to the unified AI Page Insights history tab for backward compatibility

Field Controls

Depending on TCA configuration and field type, backend forms can show:

  • Generate alt text button
  • Generate image button
  • Generate text button
  • Generate SEO title/description buttons
  • Generate technical/content/a11y recommendation buttons

Generated images are marked as AI-generated in TYPO3 metadata/reference flags (tx_sgai_is_ai_generated) and receive automatic alt text handling. If the SG AI image response provides provenance/generation metadata, sg_ai preserves it for generated originals by mapping values into sys_file_metadata (for example creator, creator_tool, source, copyright, description, title). Additionally, sg_ai writes AI provenance markers for generated originals:

  • IPTC/XMP Digital Source Type (trainedAlgorithmicMedia URI)
  • AI system fields (system name/version and model name) when provided by the API response
  • A normalized provenance summary in TYPO3 sys_file_metadata.note

For processed image variants, SG AI can add this provenance metadata within TYPO3's processing command (watermarkPreserveMetadataOnProcessing, default 1). Metadata persistence in image binaries depends on file format and ImageMagick/GraphicsMagick capabilities. In practice, PNG/JPEG usually keep more metadata than WEBP in many environments. SG AI still attempts metadata embedding for all processed target formats as best effort.

EU AI Act transparency support is declared at extension metadata level (ext_emconf.php and composer.json), not as an image-embedded compliance statement.

EU AI Act (Pragmatic Note)

This extension provides technical support for transparency workflows:

  • AI-generated image marking (tx_sgai_is_ai_generated)
  • Optional visual watermark overlays in frontend output
  • Accessible label suffixes for non-decorative AI images
  • Provenance metadata best effort during image processing
  • Prompt/result traces in TYPO3 data structures for editorial review
  • AI-generated text/recommendation outputs are persisted in TYPO3 records and queue/history tables for review before publication

Integrators are responsible for deciding where and when labels/disclosures are shown, based on their legal and organizational requirements. This extension does not provide legal advice.

Not Yet Added: C2PA Manifest Signing

sg_ai does not yet add a C2PA manifest to generated images.

What this would provide:

  • A cryptographically signed provenance manifest embedded in or bound to the image
  • Verifiable claim of origin and transformation chain (tamper-evident)
  • Stronger interoperability with Content Credentials / C2PA-aware verification tools

Why this is separate from ordinary metadata:

  • XMP/IPTC fields are editable metadata and are not cryptographically protected by default
  • C2PA requires a signing pipeline (private key management, certificates, manifest generation, and signature validation strategy)
  • Operationally this introduces trust infrastructure and key-rotation requirements that must be configured per environment

Planned scope for a future implementation:

  • Optional C2PA signer integration (disabled by default)
  • Configurable key/certificate handling and signer identity
  • Fail-safe behavior (image generation still succeeds if signing is unavailable, with explicit logging)

Queue and History Behavior

  • Long-running tasks are enqueued and processed asynchronously.
  • Queue records are persisted in tx_sgai_queue.
  • Results/history are persisted in tx_sgai_url_check.
  • Remote background processing (HTTP 202/message ID) is supported and finalized via queue polling.
  • Queue entries store cloud tracking metadata (remote_message_id, remote_status) for remote runs.
  • History views support search, sorting, pagination, and result preview via View action.
  • If the cloud API rate limits (HTTP 429), processing is deferred and retried safely.

Image Generation Behavior

  • The last image prompt is persisted and reused per record/field (tx_sgai_last_image_prompt).
  • Prompt persistence keeps the image settings comment block, including image_size and output_format.
  • Generated images are automatically marked as AI-generated (tx_sgai_is_ai_generated).
  • AI-generated images can be watermarked automatically during rendering based on extension configuration.
  • Generated images can be renamed from alt text to SEO-friendly slugs.
  • Renamed files are capped at 60 characters total (including hash suffix and extension).

TCA Configuration Example (AI Image Generation)

'images' => [
	'config' => [
		'sg_ai' => [
			'promptProvider' => 'Vendor\\Extension\\PromptProvider\\CustomPromptProvider',
			'promptTemplate' => 'Generate an image for ###title### with ###category### theme',
			'disabled' => true,
			'image_size' => 'landscape_16_9',
			'output_format' => 'png',
		],
		'type' => 'file',
	],
],

Supported image size presets:

  • square_hd
  • square
  • portrait_4_3
  • portrait_16_9
  • landscape_4_3
  • landscape_16_9

You can also pass custom dimensions:

  • ['width' => 1280, 'height' => 720]

CLI Commands

Alt text generation

vendor/bin/typo3 sg_ai:generate-alt-texts

Options:

  • --limit
  • --dry-run

SEO meta generation

vendor/bin/typo3 sg_ai:generate-seo-meta [page-uid]

Options include:

  • --force
  • --title-only
  • --description-only
  • --limit
  • --exclude-hidden
  • --exclude-deleted

AI recommendations generation

vendor/bin/typo3 sg_ai:generate-ai-recommendations [page-uid]

Options include:

  • --force
  • --accessibility-only
  • --content-seo-only
  • --technical-seo-only
  • --limit
  • --exclude-hidden
  • --exclude-deleted

Queue operations

Process queue:

vendor/bin/typo3 sg_ai:process-queue

List queue:

vendor/bin/typo3 sg_ai:list-queue

Cleanup queue/results:

vendor/bin/typo3 sg_ai:cleanup-queue

Troubleshooting

  • Tasks stay pending:
    • verify scheduler task exists and is enabled
    • run one manual queue cycle: vendor/bin/typo3 sg_ai:process-queue --limit=5
  • API key error:
    • check SG_AI_API_KEY / extension configuration
  • URL/page checks fail:
    • ensure target pages are publicly reachable for checks that require rendered output

Testing

Run extension checks from the project root:

composer phpunit vendor/sgalinski/sg-ai
composer phpstan vendor/sgalinski/sg-ai
composer ecs vendor/sgalinski/sg-ai

SG AI for TYPO3: End-User Documentation

This guide explains how to use the sg_ai TYPO3 extension in daily editorial work.

It is focused on:

  • real backend workflows for editors and SEO managers
  • all user-facing buttons introduced by the extension
  • setup and configuration that affects behavior
  • practical benefits, limits, and troubleshooting

For extension-level setup and upgrade notes, also see:

1. Purpose of the Extension

sg_ai adds AI-assisted content and quality workflows directly into TYPO3 backend forms.

Main goals:

  • speed up content production
  • improve SEO and accessibility quality
  • reduce repetitive manual work for editors
  • standardize outputs across large teams

The extension currently covers:

  1. Alt text generation for images
  2. AI image generation for file fields
  3. AI text generation for RTE content
  4. SEO title and description generation for pages
  5. AI-powered technical/content SEO recommendations
  6. AI-powered accessibility recommendations
  7. URL checks in the backend module
  8. bulk processing through CLI commands

2. Target Users and Responsibilities

Editors

  • generate text, images, and alt text
  • refine generated output before publishing
  • trigger page-level recommendation generation

SEO / Accessibility Managers

  • review scores and recommendation tables
  • prioritize fixes by impact
  • re-run checks after content updates

TYPO3 Administrators / Integrators

  • configure API access and defaults
  • control field-level behavior in TCA
  • automate bulk generation via commands

3. Prerequisites

Before users can work with the buttons:

  1. The extension sg_ai must be installed and active.
  2. Queue processing must be active by creating the TYPO3 scheduler task sg_ai:process-queue.
  3. SG AI API credentials must be configured.
  4. Editors need backend access to the affected records/tables.
  5. For URL/page-based checks, the checked page must be reachable as rendered HTML.

3.1 Required queue activation (TYPO3 2.x)

Queue processing is mandatory in 2.x for asynchronous workflows (recommendations, history updates, remote background results).

Recommended setup path:

  1. Open Web > AI Assistant > Dashboard.
  2. If the warning Scheduler task inactive is shown, click Create scheduler task now for sg_ai:process-queue.
  3. Add the additional recommended scheduler tasks from the dashboard:
    • sg_ai:cleanup-queue (daily)
    • sg_ai:generate-seo-meta (nightly)
    • sg_ai:generate-alt-texts (early morning)
    • sg_ai:generate-ai-recommendations --limit=25 (weekly; may consume many credits)

Recommended execution interval for sg_ai:process-queue: every 5 minutes (*/5 * * * *).

3.2 Optional MCP auto-API setup (sgai_mcp)

If you want to connect MCP clients directly to TYPO3 content data:

Important distinction:

  • SGAI Cloud MCP = your existing SG AI platform MCP server.
  • SGAI TYPO3 MCP = this extension's TYPO3 MCP server (sgai_mcp).

Use separate client names and tokens for these two servers.

  1. Open Web > AI Assistant > Dashboard.
  2. In SGAI TYPO3 MCP, first check the access state shown in the card:
    • Included: TYPO3 MCP is available on the current SG AI subscription
    • Trial: a 14-day TYPO3 MCP trial is active
    • Upgrade required: TYPO3 MCP is not yet available; upgrade to Silver or higher
    • Expired: previous TYPO3 MCP access is no longer active
  3. If Upgrade required is shown and the account is eligible, start the 14-day TYPO3 MCP trial.
  4. Once the state is Included or Trial, select one target site and run Enable SGAI TYPO3 MCP.
  5. Save the shown token immediately (it is shown once only).

Endpoints:

  • Canonical: /api/sgai_mcp/v1/mcp
  • Compatibility alias: /sgai_mcp/mcp

Notes:

  • v1 supports one active target site per TYPO3 instance.
  • TYPO3 MCP access is controlled by the locally stored package and trial state in TYPO3.
  • TYPO3 MCP is available only for:
    • SG AI subscriptions from Silver upwards
    • or an active 14-day TYPO3 MCP trial
  • The setup manages backend group SGAI MCP and compiles resources/scopes from that group's table/field permissions.
  • Permission changes are synced immediately; fallback command: sg_ai:mcp:sync.
  • Opening the SG AI dashboard refreshes the local package snapshot from /v1/credits.
  • MCP runtime uses only the local snapshot and never performs a remote entitlement request in the request path.
  • If the local trial is expired or the last known package state is stale or not eligible, setup and runtime usage stay blocked until the dashboard refreshes the package snapshot again.

How setup behaves:

  1. Setup is idempotent and can be executed multiple times.
  2. Re-running setup resynchronizes group permissions, resources, scopes, and cache state.
  3. The token is only shown in plaintext when a new token was created.
  4. If a reusable token already exists, it is reused and not shown again.
  5. After setup, the dashboard card switches from Enable SGAI TYPO3 MCP to Disable SGAI TYPO3 MCP and shows compact TYPO3 MCP client configuration examples inline.
  6. Disabling MCP revokes the active token, hides the managed backend group, and removes the MCP surface until setup is run again.
  7. The card shows the current plan, trial end date if applicable, and the last local package refresh timestamp.

When a new token is created:

  • No valid preferred token exists from previous setup state, and
  • No reusable token is found for API sgai_mcp + selected site/tenant.

3.3 MCP client configuration (Codex/Cursor/Junie)

Use the token from setup and configure your MCP client (Codex) with HTTP transport:

  • URL: https://your-site.example/api/sgai_mcp/v1/mcp
  • Auth: use bearer_token_env_var (Codex-style)

Recommended naming:

  • sgai for SG AI platform MCP (existing/released name)
  • sgai_typo3 for TYPO3 MCP

Recommended environment variables:

  • SGAI_API_TOKEN
  • SGAI_TYPO3_API_TOKEN

Codex-style TOML (TYPO3 MCP):

[mcp_servers.sgai_typo3]
bearer_token_env_var = "SGAI_TYPO3_API_TOKEN"
transport = "http"
url = "https://your-site.example/api/sgai_mcp/v1/mcp"

Codex-style TOML (both MCP servers):

[mcp_servers.sgai]
bearer_token_env_var = "SGAI_API_TOKEN"
transport = "http"
url = "https://sgai.mateevsolutions.com/api/sgai/v1/mcp"

[mcp_servers.sgai_typo3]
bearer_token_env_var = "SGAI_TYPO3_API_TOKEN"
transport = "http"
url = "https://your-site.example/api/sgai_mcp/v1/mcp"

JSON-style client example (Cursor/Junie variants, TYPO3 MCP):

{
  "mcpServers": {
    "sgai_typo3": {
      "transport": "http",
      "url": "https://your-site.example/api/sgai_mcp/v1/mcp",
      "bearer_token_env_var": "SGAI_TYPO3_API_TOKEN"
    }
  }
}

3.4 tt_content positioning for MCP clients

By default, TYPO3 inserts newly created tt_content records at the top.

For tt_content create endpoints, the generated MCP/OpenAPI schema exposes these optional request fields:

  • position: top, bottom, or after
  • afterUid: required when position=after

How they work:

  • top: insert at the top of the target context
  • bottom: insert after the last sibling in the same pid, colPos, and sys_language_uid context
  • after: insert directly after an existing tt_content element

Important:

  • If position is omitted, top is used.
  • afterUid must point to an existing tt_content record.
  • If position=after and you do not send pid, colPos, or sys_language_uid, TYPO3 inherits them from the referenced record.
  • If you want deterministic placement within a column, send colPos when it is available in the endpoint schema.

3.5 AI image generation flow for MCP clients

sgai_typo3 provides one dedicated MCP tool for TYPO3 content images:

  • generate_and_attach_image_to_content
  • generate_and_attach_image_to_page

This is the preferred image workflow for MCP clients. The TYPO3 backend uses its configured SG AI API key, generates the image server-side, stores it in TYPO3 FAL, creates the sys_file_reference, and attaches it to the correct TYPO3 media field for the target record.

Recommended flow for tt_content.image:

  1. Create the target content element.
  2. Call generate_and_attach_image_to_content in sgai_typo3.

Example call:

{
  "contentUid": 456,
  "prompt": "Editorial hero image about TYPO3 AI workflows, modern office scene, realistic, clean composition",
  "imageSize": "landscape_16_9",
  "outputFormat": "png"
}

Expected result:

{
  "contentUid": 456,
  "fileUid": 123,
  "fileReferenceUid": 987,
  "publicUrl": "/fileadmin/user_upload/ai_generated/editorial-hero-image.png",
  "altText": "Editorial hero image about TYPO3 AI workflows"
}

Notes:

  • sys_file remains exposed as a read-only MCP resource so stored files can still be listed and found later.
  • The tool requires a configured SG AI API key in the TYPO3 backend.
  • It requires sgai_mcp:tt_content:write, sgai_mcp:sys_file:write, sgai_mcp:sys_file_reference:write, and sgai_mcp:sys_file_metadata:write.
  • For CType=textmedia, generate_and_attach_image_to_content writes to tt_content.assets. For standard image-based content elements, it usually writes to tt_content.image.
  • tt_content.image is a built-in non-exclude field in TYPO3, so no separate non_exclude_fields entry is required for it.
  • generate_and_attach_image_to_page works for pages.media and pages.og_image, defaults to media, and requires sgai_mcp:pages:write plus the same file-related write scopes. Because both page fields are exclude fields, the managed backend group must allow pages:media and/or pages:og_image for the targets you want to use.

3.6 Localize a page before editing translated fields

Use localize_page to create or reuse the translated page record first. Then call pages.update on the returned localizedPageUid.

Example flow:

  1. localize_page with: 
    {
  "pageUid": 123,
  "languageUid": 1
}
  2. pages.update on the returned localized page UID with translated fields such as title, slug, description, or seo_title.

3.7 Filtering examples for MCP clients

List endpoints expect filters in the shape filter[field]=value.

Examples for pages:

{
  "filter": {
    "title": "News"
  }
}

{
  "filter": {
    "slug": "/news"
  }
}

Do not send title or slug as top-level list arguments. They must be nested inside filter.

Operational recommendations:

  • Prefer canonical endpoint /api/sgai_mcp/v1/mcp.
  • Treat tokens as secrets and keep them in environment variables/secure client settings.
  • After token revocation/rotation in TYPO3, update the MCP client token.

4. Global Configuration (Extension Configuration)

Open:

  • Admin Tools > Settings > Extension Configuration > sg_ai

4.1 Required

  • apiKey
    • SG AI API key.
    • Recommended: do not store in TYPO3 DB; use environment variable SG_AI_API_KEY.

4.2 Optional but Important

  • useImageAnalysis (0/1)

    • 1: analyzes actual image content for alt text generation.
    • 0: metadata-only alt text generation.
    • Impact: quality vs. processing complexity.

  • useBase64Encoding (0/1)

    • 1: sends image data as base64 to SG AI.
    • 0: sends image URL.
    • Recommended: keep 1 for private/staging/non-public environments.

  • useContextForAltText (0/1)

    • 1: includes surrounding TYPO3 context when generating alt text.
    • 0: no contextual page data.
    • Impact: often better relevance, potentially higher token usage.

  • language (e.g. en, de)

    • default language for recommendation output (SEO/a11y checks and module usage).

  • watermarkEnabled (0/1)

    • global on/off switch for SG AI watermark logic on AI-flagged images (overlay decision + processing metadata hooks).

  • watermarkOverlayEnabled (0/1)

    • enables/disables frontend HTML/CSS watermark overlay rendering.
    • default is 0 (disabled).

  • watermarkPreserveMetadataOnProcessing (0/1)

    • adds SG AI provenance metadata in TYPO3's processing command when processed variants are created.
    • default is 1 (enabled).

  • watermarkBadgeAssetPath

    • EXT: path or absolute path to the badge graphic (default circled AI icon).

  • watermarkPosition, watermarkMargin, watermarkRelativeSize, watermarkOpacity

    • visual styling and placement controls.

  • watermarkMaxWidth, watermarkMaxHeight

    • badge size caps in pixels (default 80/80, 0 = unlimited).

  • watermarkMinWidth, watermarkMinHeight

    • minimum output dimensions for watermarking.

  • watermarkScreenReaderLabelEnabled, watermarkScreenReaderSuffix

    • controls whether non-decorative AI images receive an accessibility suffix in alt and aria-label.

  • watermarkOverlayAccessibilityLabel

    • localized label text used for the watermark badge image (alt / aria-label).

  • per-call overrides

    • mode-only: sgAiWatermarkMode (on|off)
    • structured: sgAiWatermarkOverride supports mode / enabled and visual/accessibility settings.

HTML overlay behavior:

  • the extension appends additional badge markup to rendered image HTML
  • the badge is positioned with CSS on top of the image
  • this does not alter image pixels or binary image data

4.3 Fixed Queue/Polling Defaults

Queue and remote background polling behavior uses fixed defaults in code and is not configurable via Extension Configuration:

  • immediate local processing priorities: 20,30
  • remote synchronous priorities: 20,30
  • polling max retries: 120
  • polling sleep seconds: 2

4.4 EU AI Act (Pragmatic Note)

sg_ai supports practical transparency measures for AI-assisted content:

  • AI-image markers in TYPO3 metadata/reference records
  • optional visual frontend overlay labeling
  • optional accessibility suffixes for non-decorative AI images
  • provenance metadata best effort during processing
  • persisted AI text/recommendation outputs in TYPO3 records/history for editorial approval workflows

What must be shown to end users, in which channel, and at what workflow stage remains an integrator/editorial decision. This documentation does not provide legal advice.

5. Field-Level Configuration in TCA

Several features can be tuned per field using config.sg_ai.

5.1 Common controls

  • disabled
    • hides SG AI controls for that field.
  • promptProvider
    • custom provider class to generate prompts.
  • promptTemplate
    • template with placeholders such as ###title###.

5.2 Image-field specific

  • image_size
    • default generated image size preset or custom dimensions.
  • output_format
    • png or jpeg.

6. Button-by-Button End-User Guide

This section lists all user-facing buttons introduced by sg_ai.

6.1 Generate Alt Text with AI

Where it appears

  • On sys_file_reference.alternative
  • On sys_file_metadata.alternative

Label / title behavior

  • The control uses context-aware titles:
    • context active
    • context ignored

Workflow

  1. Open a record that contains an image reference.
  2. Locate the Alternative (alt text) field.
  3. Click Generate Alt Text with AI.
  4. Wait for the request to finish.
  5. Review the generated text and adjust if needed.
  6. Save the record.

Important notes

  • If image is marked decorative, generation is skipped.
  • If record/file is missing or inaccessible, generation fails with an error message.
  • If API key is missing, users receive an explicit configuration error.

Benefits

  • very fast accessibility baseline
  • improved consistency in alt text style and length
  • lower manual effort for media-heavy pages

6.2 Is Decorative (Toggle)

Where it appears

  • Image overlay palette in sys_file_reference

Purpose

  • Marks an image as decorative.
  • Decorative images are intentionally excluded from alt text generation.

Workflow

  1. Open image reference in backend form.
  2. Enable Is decorative if image has no informative value.
  3. Save.

Benefit

  • prevents misleading or unnecessary alt text
  • improves accessibility quality by using proper decorative-image handling

6.3 Generate Image with AI

Where it appears

  • In inline file controls for image-capable fields (for matching image file types)
  • Can be disabled per field via config.sg_ai.disabled

Modal actions

  • Generate
  • Reset to Default
  • Cancel

Workflow

  1. Open a saved record with an eligible image field.
  2. Click Generate Image with AI.
  3. In modal, edit or keep the prompt.
  4. Optional: click Reset to Default to regenerate default prompt.
  5. Click Generate.
  6. Wait for processing notification.
  7. Page reloads and new image reference is attached.

What happens technically (user-visible outcome)

  • New file is generated and attached to record.
  • Generated file is marked as AI-generated in file metadata.
  • SG AI stores provenance metadata for generated images.
  • Alt text generation is triggered for the new image.
  • Last prompt is persisted per record/field, including the image settings comment block.
  • File may be renamed to an SEO-friendly name derived from alt text.
  • Generated filename length is capped to 60 characters (including suffix and extension).

EU AI Act transparency support is documented in extension metadata (ext_emconf.php and composer.json).

Benefits

  • fast visual content creation without leaving TYPO3
  • consistent style via prompt templates
  • immediate integration into existing media fields

6.4 Generate Text with AI

Where it appears

  • On eligible RTE text fields.
  • The extension auto-injects this button for supported text fields.

Modal actions

  • Generate Text
  • Reset to Default
  • Cancel
  • Checkbox: Include page context

Workflow

  1. Open a saved record with an RTE field.
  2. Click Generate Text with AI.
  3. Review/edit the generated prompt.
  4. Choose whether to include page context.
  5. Click Generate Text.
  6. Generated content is inserted into CKEditor/textarea.
  7. Review, edit, and save.

Page-context option

When enabled, context may include:

  • TYPO3 version metadata
  • page information
  • nearby content data for richer relevance

Restrictions

  • Unsaved records cannot generate text.
  • Non-RTE fields are filtered/removed from this workflow.

Benefits

  • faster drafting, rewriting, and expansion
  • better context-aware results with one click
  • reduced editor switching between tools

6.5 Generate SEO-Friendly Title

Where it appears

  • pages.seo_title field control

Workflow

  1. Open page properties.
  2. Click Generate SEO-friendly title.
  3. Wait for generation.
  4. Value is written to seo_title.
  5. Review and save.

Benefits

  • faster meta optimization
  • consistent and language-aware SEO title generation

6.6 Generate SEO-Friendly Description

Where it appears

  • pages.description field control

Workflow

  1. Open page properties.
  2. Click Generate SEO-friendly description.
  3. Wait for generation.
  4. Value is written to description.
  5. Review and save.

Benefits

  • faster and more complete meta coverage
  • reduced chance of missing or weak descriptions

6.7 Generate Technical SEO Recommendations

Where it appears

  • In page-level SG AI recommendation area

Workflow

  1. Open saved page record.
  2. Click Generate Technical SEO Recommendations.
  3. Wait for background processing notice.
  4. Page reloads.
  5. Review updated score and recommendation table.

Output shown to users

  • score indicator (0-100)
  • recommendation table with:
    • Priority, Where, What, How, Why
  • generation timestamp

Benefit

  • quick technical SEO issue discovery directly in page editing

6.8 Generate Content SEO Recommendations

Workflow

  1. Open saved page record.
  2. Click Generate Content SEO Recommendations.
  3. Page reloads with updated score and recommendations.

Benefit

  • content-quality and relevance guidance for editors and SEO teams

6.9 Generate Accessibility Recommendations

Workflow

  1. Open saved page record.
  2. Click Generate Accessibility Recommendations.
  3. Page reloads with updated score and recommendation table.

Benefit

  • faster identification of accessibility barriers and fixes

6.10 Backend Module Button: Get Recommendations

Use the dashboard first when setting up a fresh instance:

  • Web > AI Assistant > Dashboard for onboarding and scheduler setup
  • then switch to Web > AI Assistant > AI Page Insights for URL checks

Location

  • Web > AI Assistant > AI Page Insights

Inputs

  • URL (required)
  • Type:
    • Technical SEO
    • Content SEO
    • Accessibility

Main action

  • Get recommendations

Workflow

  1. Open module.
  2. Enter public URL.
  3. Select analysis type.
  4. Click Get recommendations.
  5. Review score and structured recommendations in “Last result”.

Benefits

  • quick quality check for arbitrary URLs
  • usable for checks outside the currently edited page

6.11 AI History and Queue Status

Where it appears

  • Web > AI Assistant > AI Page Insights (integrated Analysis + History tabs)
  • Web > AI Assistant > Dashboard (scheduler overview and setup actions)

What users can do

  1. Track queued and completed AI tasks.
  2. Open View to inspect full generated result payloads.
  3. Search, sort, and paginate through past results.
  4. Reuse generated output where action buttons are available.
  5. Identify remote queue runs by message state information in status/details.

Why this matters

  • improves traceability of AI-generated changes
  • supports editorial review before applying outputs
  • helps teams verify that queue processing is healthy

7. Typical End-User Scenarios

7.1 New page creation

  1. Create and save page/content.
  2. Generate draft text in RTE fields.
  3. Generate images where needed.
  4. Generate image alt texts.
  5. Generate SEO title and description.
  6. Run content/technical/a11y recommendations.
  7. Apply improvements and publish.

7.2 Existing page optimization

  1. Run recommendation buttons.
  2. Prioritize high-impact items from table.
  3. Update content, structure, or media.
  4. Re-run recommendation generation.
  5. Track improved score and publish updates.

8. CLI Workflows for Large Sites

For admins/integrators:

  • vendor/bin/typo3 sg_ai:generate-alt-texts
  • vendor/bin/typo3 sg_ai:generate-seo-meta
  • vendor/bin/typo3 sg_ai:generate-ai-recommendations
  • vendor/bin/typo3 sg_ai:process-queue
  • vendor/bin/typo3 sg_ai:list-queue
  • vendor/bin/typo3 sg_ai:cleanup-queue

When to use:

  • initial rollout on existing content
  • scheduled quality maintenance jobs
  • large-batch updates after migrations

9. Best Practices for Content Teams

  1. Always review AI output before publishing.
  2. Use “Is decorative” correctly for non-informative images.
  3. Keep prompts concise and task-specific.
  4. Use TCA templates for consistent tone across fields.
  5. Re-run recommendations after meaningful content changes.
  6. Keep API credentials in environment variables, not in VCS.

10. Troubleshooting Guide

“API key is not configured”

  • Check SG_AI_API_KEY or sg_ai extension configuration.

Buttons are missing

  • Check user permissions.
  • Verify field-level config.sg_ai.disabled.
  • Confirm field type supports that button workflow.

Unsaved record warning

  • Save record first, then run generation.

Recommendation generation fails

  • Ensure target page/URL is reachable and rendered.
  • Check TYPO3/system logs for request details.

Queue tasks stay pending for too long

  • Verify the scheduler task sg_ai:process-queue exists and is enabled.
  • Execute a manual run: vendor/bin/typo3 sg_ai:process-queue --limit=5.
  • If the backend shows Scheduler task inactive, create it in Web > AI Assistant > Dashboard.

Image generation works but no visible result

  • Record reload may be required.
  • Verify file field configuration and storage permissions.

History is empty even after generation

  • Confirm queue processing is active and tasks reach status finished.
  • Verify there are no API/permission errors in TYPO3 logs.

11. Governance and Quality Control

For team leads:

  • define editorial rules for AI output acceptance
  • set periodic accessibility/SEO review cadences
  • document approved prompt patterns for each content type
  • monitor changes in recommendations over time

12. Summary

sg_ai turns TYPO3 backend forms into AI-assisted workflows:

  • generate faster
  • improve quality continuously
  • keep content, SEO, and accessibility work inside TYPO3

For extension-level setup and upgrade information, see:

AI Watermark Overlay API

sg_ai provides a reusable overlay API so extension-level ViewHelpers can render AI watermarks in a generic way.

SG AI watermark overlays are injected through PSR-14 image-rendering events:

  • SGalinski\SgAi\Event\AfterImageRenderingEvent

Recommended integration for all setups: dispatch AfterImageRenderingEvent from your existing renderer right after building the final image HTML (<img>/<picture>). This avoids custom SG AI wrapper ViewHelpers and keeps one rendering path.

Implementation outline:

  1. Render image HTML in your own renderer.
  2. Resolve the corresponding TYPO3 FileInterface.
  3. Dispatch SGalinski\SgAi\Event\AfterImageRenderingEvent with HTML, file, and render context.
  4. Use the returned event HTML (getImageHtml()) as final output.

Services

SGalinski\SgAi\Service\AiImageWatermarkOverlayService

Main methods:

  • buildPictureOverlayResult(FileInterface $file, array $renderContext = []): array

buildPictureOverlayResult() returns a consumer-ready payload for thin integrations:

  • overlayMarkup (ready-to-append badge overlay markup)
  • isWatermarkActive (final decision after global settings, AI flag, dimension limits, and optional per-call override)
  • accessibleText (input accessible text with optional AI suffix applied for non-decorative images)
  • shouldSyncAccessibleText (whether alt/aria-label should be rewritten from accessibleText)

The badge image accessibility label (alt/aria-label inside overlayMarkup) is configured through watermarkOverlayAccessibilityLabel and supports LLL references.

SGalinski\SgAi\Service\AiImageWatermarkService

Relevant integration method:

  • resolvePerCallWatermarkContext(array $context, ?array $watermarkConfiguration = null): array

This method normalizes mode-only and structured overrides and is used by both processing and overlay integrations. Use it if your extension needs to apply SG AI-compatible watermark overrides in custom pipelines.

Render Context

Supported render-context keys:

  • width, height (optional target dimensions used for threshold checks)
  • accessibleText (optional source text for alt and aria-label synchronization)
  • isDecorative (optional boolean to suppress suffixing for decorative images)
  • sgAiWatermarkMode (optional on|off)
  • sgAiWatermarkOverride (optional structured override array)

sgAiWatermarkOverride supports:

  • mode (on|off) or enabled (true|false)
  • badgeAssetPath
  • position
  • margin
  • relativeSize
  • maxWidth, maxHeight
  • opacity
  • minWidth, minHeight
  • overlayAccessibilityLabel
  • screenReaderSuffix
  • screenReaderLabelEnabled

Global extension settings relevant to overlay behavior:

  • watermarkEnabled (global watermark decision base)
  • watermarkOverlayEnabled (frontend overlay rendering switch)

If watermarkOverlayEnabled is disabled, no overlay markup is injected even if image-level watermark conditions are met.

Overlay Markup and CSS Requirements

The overlay is rendered as additional HTML appended to the image/picture output:

<span class="sgai-watermark-overlay" style="--sgai-watermark-margin: ...; --sgai-watermark-size: ...; ...">
	<img class="sgai-watermark-overlay-badge sgai-watermark-overlay-badge--southeast" ... />
</span>

This markup requires CSS to be visually positioned as an overlay. Without CSS, the badge will be rendered as normal inline content.

Required CSS Integration

Import the SG AI stylesheet partial in your frontend build:

EXT:sg_ai/Resources/Public/Sass/Bootstrap5/_sg-ai.scss

If you do not use SASS imports, add equivalent CSS rules manually. The minimum required behavior is:

  1. The image container must be position: relative.
  2. .sgai-watermark-overlay must be position: absolute; inset: 0;.
  3. .sgai-watermark-overlay-badge must be absolutely positioned via the --north/.../--southeast classes.

Plain CSS Fallback Example

.my-image-wrapper {
	position: relative;
}

.my-image-wrapper .sgai-watermark-overlay {
	position: absolute;
	inset: 0;
	pointer-events: none;
}

.my-image-wrapper .sgai-watermark-overlay-badge {
	position: absolute;
	width: var(--sgai-watermark-size, 12%);
	opacity: var(--sgai-watermark-opacity, 0.85);
}

.my-image-wrapper .sgai-watermark-overlay-badge--southeast {
	right: var(--sgai-watermark-margin, 24px);
	bottom: var(--sgai-watermark-margin, 24px);
}

Runtime CSS Variables

The overlay service writes these CSS variables inline:

  • --sgai-watermark-margin
  • --sgai-watermark-size
  • --sgai-watermark-opacity
  • --sgai-watermark-max-width
  • --sgai-watermark-max-height

This allows integrators to keep global CSS generic while sizing and placement are still controlled by SG AI settings and per-call overrides.