---
title: "Access, endpoints and safety"
description: "Capabilities, endpoints, safety and per-use settings."
requested_language: fr
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/fr/payload/ai/access-and-endpoints
version: unreleased (main)
docs_index: https://docs.systhema.app/fr/llms.txt
---
> This page isn't translated yet. Showing English.


## Access control

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).

## Endpoints

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 safe

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 settings

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.