Access, endpoints and safety

Access controlLink to this section

Generation is gated by a single ai.generate capability, registered only when AI is enabled. The built-in dev, admin and editor roles hold it by default; seoManager does not. The usage log is gated by ai.usage.read (dev-only by default). Adjust via the existing roles API (roles.overrideRoles, custom roles).

EndpointsLink to this section

Registered on the Payload config only when AI is enabled. The generation endpoints (/generate, /generate-image, /seo, /alt) require authentication + the ai.generate capability; /settings and /usage require only authentication — /settings carries no secrets and returns a canGenerate flag the UI uses to enable controls, and /usage feeds the widget shown to every admin:

Endpoint	Method	Purpose
/api/systhema/ai/generate	POST	Text generation — field values (streamed), selection fragments (streamed), layouts (JSON), plus whole-page generate/translate (mode page, returns { changes }) and whole-document translate/proofread/rephrase (mode document, returns { state })
/api/systhema/ai/generate-image	POST	Image generation/refinement — creates a new uploads document, returns { success: true, id, alt }
/api/systhema/ai/seo	POST	SEO meta title/description generation from whole-page content — returns { value } (counts as one text generation)
/api/systhema/ai/alt	POST	Vision-based image alt-text generation — returns { value } (counts as one text gen)
/api/systhema/ai/settings	GET	Safe client settings — enabled/canGenerate, text/image provider+model, selectable model lists (with locked teasers), default model ids, languages, button-variant hydration options, creditMode, and credit-preview estimates. Never exposes apiKey/baseURL.
/api/systhema/ai/usage	GET	Per-period usage counters for the dashboard widget (used/limit/reset; no costs)

How generation stays safeLink to this section

Models never produce raw lexical editor state. Text actions generate a compact, schema-constrained fragment format that is hydrated into fully-shaped lexical nodes (with all internal fields filled); layout generation uses a curated block vocabulary hydrated server-side with defaults read from the real block definitions and design tokens. Anything outside the schema or the editor's registered node types is dropped, never inserted. The _tier field is never generated — Systhema's own hooks inject it.

Per-use settingsLink to this section

The voice settings are a sub-page inside every text panel (open it from the Personalize link; a Back action returns to the main view — exactly like the Translate picker). The image panel uses the same sub-page pattern for its aspect/resolution Settings. They hold the user's AI-writing voice: a Base style and tone preset (Default/Neutral, Professional, Friendly, Candid, Quirky, Efficient, Cynical), four More/Default/Less dials — Warmth, Enthusiasm, Headers and lists, Emoji — and a free-text Custom instructions box. The very same controls are also available on the user's profile/account page (a ui field on the users collection), so a user can tune their voice from any AI panel or from their profile — one source of truth.

These are saved as a single per-user Payload preference: set them once and they follow the user across every AI surface on the site; they're never shared between users and never reset. They shape every generative/rewrite action (compose, rephrase, expand, summarize, simplify, layout, page generation) — but grammar-check and translate ignore them so those stay faithful to the source. Output length isn't a setting either; the explicit Summarize / Expand / Simplify actions cover it. (Image settings — aspect ratio, target resolution — remain per-field in localStorage.) All AI panels — field, image, SEO/alt and the floating lexical editor panel — share one consistent chrome and padding, and every sub-view (Translate, Settings) lines up with the root panel.

Enabling ai.text also injects a systhemaAiSettings group onto the users collection — a per-user AI writing voice (style, warmth, enthusiasm, formatting, emoji, free-form instructions) editable from the user's own profile, gated by the ai.generate capability.