Skip to main content
Unlayer Docs

FAQ & Troubleshooting

Paid Feature

This feature is only available in paid plans. Learn More

Missing something? Email support@unlayer.com or use the in-product chat in Console.

Pricing & credits​

How much does it cost?​

AI uses one workspace-level credit bucket. Small edits are usually in the tens of credits, image generation or editing is usually in the dozens to hundreds, and full-template, HTML, or website imports are usually in the hundreds to a couple thousand. Exact usage depends on the request, model, input, and output. Eligible workspaces see a one-time welcome offer in Billing. It appears only when the current plan, subscription status, and AI feature eligibility qualify; current Free and legacy plans do not qualify. Eligibility to buy a credit pack is separate. See Pricing.

Can I get a surprise bill if my users go heavy on AI?​

On a capped workspace, Unlayer stops new generations when the workspace reaches its available credit allowance. By default the controls remain visible and show an exhaustion message; a project can instead hide them. Grandfathered uncapped workspaces continue to meter usage without pausing AI or creating overage charges. Unlayer does not purchase another credit pack in response to an AI request. See When credits reach zero.

How do I track what my users ask the assistant?​

Subscribe to the AI lifecycle callbacks from your host app and forward the events to your analytics pipeline. ai:assistant:on:request carries the prompt and target scope; after it fires, the corresponding ai:assistant:on:success, :on:error, or :on:cancel callback carries the outcome. Success and error events may include durationMs; to cover every turn, measure elapsed time from the matching request event. Pre-request UI choices, such as declining Template Importer replacement confirmation, emit no lifecycle callback.

Each emitted event also carries the projectId, workspaceId, and identified end-user (from End-User Identification), so per-user analytics and support correlation can use the event payload. Callbacks are after-the-fact notifications and cannot authorize or prevent an AI request, so enforce free-tier limits and other access rules in your backend. Do not use callbacks as a billing ledger: production success callbacks omit per-turn credit usage. A structured exhaustion error can include the current limit state, but it is not a complete usage record. Use the AI Credits API and webhooks for billable usage. For a worked example, see Events & Callbacks → Common use case: logging prompts & per-user analytics.

Can I read credit usage and build my own billing on top of it?​

Yes. The server-side AI Credits API and webhooks provide workspace balances, project and end-user breakdowns, alert thresholds, and signed usage events.

Why does the chat say I'm out of credits in my dev project?​

Every project in a workspace shares the same usage bucket, so dev and production projects contribute to the same pool. There is no separate unmetered dev tier. If Billing offers the 5,000-credit welcome bonus, someone with billing access must claim it explicitly; the card shows when it expires. The grant does not unlock features that the plan excludes, and eligibility to claim it is separate from eligibility to buy a paid credit pack. Grandfathered uncapped workspaces are not paused by their metered AI usage. See Reset and expiration.

Is there a per-user rate limit?​

Unlayer enforces one workspace pool, not separate per-user allowances or reset cycles. Identify each end user, read their consumption from the usage API, and enforce your commercial limit in your backend. The builder's credits and setCredits APIs can display that backend state and block the UI, but they are not a security boundary. See In-Builder Credit Upsell.

Why might AI controls disappear when credits reach zero?​

The project is using exhaustion_behavior: "disable". Change it to "show_error" with PUT /v3/projects/:id/ai-credits/settings to keep the controls visible and show the out-of-credits message instead. The message can also be customized with the documented translation keys.

Why is full-template generation more expensive than a one-block edit?​

Full-template turns reason over the entire layout and emit a much larger payload — that's more work for the model, which translates to more credits per turn. For day-to-day iteration on a paragraph or single block, prefer per-element edits — they cost a small fraction of a full-template turn. See Full Template tradeoffs.

Setup & visibility​

How do I enable or disable the AI Assistant?​

The AI Assistant is on by default — you don't need a feature flag to turn it on. It becomes available in the editor's mode switcher when:

  1. features.ai.assistant is left at its default of true (you only set it to false to disable).
  2. The project belongs to a workspace whose plan includes the AI Assistant. Check the plan in Console → Project → Settings.
  3. The init identifies the end-user — a user object with an id is passed to unlayer.init. See End-User Identification.

To disable it on a specific embed (e.g. a free-tier user, an editor surface where you don't want AI), pass features.ai.assistant: false on that unlayer.init call. The assistant is hidden in that editor instance only.

If the AI Assistant is still missing, confirm that neither features.ai.enabled nor features.ai.assistant is false, the init includes user.id, and the workspace plan includes the AI Assistant. See Setup for the full reference and Disabling per init for the disable pattern.

Why did the legacy Smart tools disappear?​

Smart Text, Smart Paragraph, Smart Buttons, Smart Headings, and Smart Image Alt Text were retired on October 1, 2026. Changing legacy features.ai flags does not restore retired tools. Use the AI Assistant instead; it has its own plan and setup requirements.

The former Magic Image panel has been replaced by image generation and editing in the AI Assistant. AI editing in the standalone Image Editor also requires AI Assistant access; legacy Magic Image access alone no longer enables it. See Image generation and editing.

See the Setup guide for the Assistant's requirements.

Can I run the assistant offline / on-premise?​

No. The assistant requires a network call to Unlayer's AI service (and from there to the model providers). On-premise deployments are not currently supported.

Privacy & data​

Does the AI Assistant train on my data?​

No. Prompts and surrounding design context are sent to Unlayer's AI service and forwarded to the underlying model providers (OpenAI, Anthropic, and others Unlayer uses as subprocessors). Inputs are not used to train models. For data-handling specifics tied to your contract — data residency, retention, DPA — contact your account manager.

Can my end users opt out of having their prompts sent to a third-party AI?​

Yes — disable the assistant for that user by passing features.ai.assistant: false on the unlayer.init call that loads the editor for them. The editor doesn't ship a built-in "AI on/off" toggle for end users; that decision lives in your application's UI.

Does the assistant store my prompts?​

Unlayer logs prompts for short-term debugging and abuse prevention. The model providers may apply their own retention windows per their terms. For zero-retention agreements, contact your account manager.

Behavior & quality​

The assistant skipped my custom block. Why?​

Your custom tool likely uses custom widgets or its own property editors, which the assistant can't introspect on its own. Declare the tool's value shape by passing a schema field on the registration call. See Custom Tools.

How do I keep the Assistant from changing protected content?​

Set the appropriate template permission and load the end-user editor in designMode: 'live'. Locked preserves an element's values and descendants, including during whole-design rewrites. Use Draggable separately to pin its position. The other permissions independently control editing, deletion, duplication, and visibility. Custom tools can additionally use supportedByAI: false; that option is not a supported built-in tool override. See Protect content from AI changes.

Why doesn't the assistant know the values of my merge tags?​

Merge tags are preserved literally in the output — {{ first_name }} comes back as {{ first_name }}, not "John". The assistant doesn't see your data; it sees the tag and treats it as an opaque placeholder. If you want the assistant to reason about realistic data, pass a sample value through your application copy ("e.g. Hi John") instead of relying on the tag itself.

Why does the output look generic / not match my brand voice?​

Configure Brand Context to give the assistant your company identity, palette, exact fonts, voice, and guidelines. If Brand Context is not configured, you can still guide the result:

  • Ask explicitly in the prompt ("sound less salesy and more helpful", "match the tone of the heading above").
  • Give the assistant nearby context — having well-written body copy in the same section makes it easier for the assistant to match.

What languages does the assistant support?​

The assistant auto-detects the language the user typed and replies in that language. A translation target in the request applies to the design copy, not the surrounding chat response. Generation works in any language the underlying model handles — Spanish, French, German, Portuguese, Italian, Japanese, Korean, Chinese, Arabic, and so on. The editor UI itself is translated separately — see Localization.

Why is the assistant producing different results for the same prompt?​

LLM outputs are stochastic; identical prompts will produce slightly different results each turn. That's expected. The Ask for multiple options flow takes advantage of this: ask for 5 alternatives and pick the best one.

Why does the image picker or import action not appear?​

The + menu appears only when at least one attachment action is available. Image attachments require AI Assistant access and enabled image upload; they also work when image editing is disabled. Import from HTML or image is a separate feature, disabled by default, and is available only for full-template assistance. Registering ai:assistant:generate hides both attachment actions. See Configure image actions.

Will an image request always generate a new image?​

No. For ordinary photo requests, the Assistant prefers enabled stock libraries. Ask explicitly to generate a custom image when that is what you need, or select an existing image and describe an edit. A clear request proceeds directly; an unclear subject or instruction can require a short question. Failed stock search does not silently switch to paid generation.

Performance​

Is it fast?​

Yes. Per-block edits (text, button, heading, image alt text) typically finish in a few seconds, and the assistant uses real-time streaming to apply changes to the visual editor as the model generates them: text streams into chat bubbles and design operations land on the canvas one at a time. Longer full-design generations can also show a progress update. Routing helps too: simpler prompts are sent to a smaller, faster model (cheaper and quicker), while frontier models are reserved for prompts detected as complex. Full-template generation reasons over the entire layout and can take tens of seconds. Image generation and editing also wait for the image provider; editing several images takes longer than one edit. See Full Template tradeoffs.

Why is full-template generation taking 30+ seconds?​

Full-template turns are the heaviest work the assistant does — they reason over the entire layout and emit a much larger payload. Tens of seconds is the expected range for full-template work; sometimes longer for very large designs. See Full Template tradeoffs.

For faster iteration on a single block or paragraph, prefer per-element edits — those typically finish in a few seconds.

Debugging​

Reporting an assistant failure to Unlayer support​

The faster you give us context, the faster we can reproduce. When opening a ticket, include:

  • Your project ID — find it in Console → Project → Settings.
  • Editor version — run unlayer.version in the browser console (with the editor loaded on the page) and paste the value.
  • The prompt the user typed — exact text, ideally copied from the chat input.
  • When it happened — approximate timestamp in your local time zone or UTC. A 5-minute window is enough for us to find the request in our logs.
  • What you expected vs. what actually happened — "I asked the assistant to translate this row to Spanish; it rewrote the row in English instead" is much more useful than "AI broke".
  • A screenshot or short screen recording of the failure — especially anything visible in the chat (status text, partial output, error banner).
  • Browser console output, if any errors logged — especially anything prefixed with [unlayer].
  • Setup — gating, plan requirements, and the disable-per-init pattern.
  • Pricing — credit-based model and what to do when you run out.
  • Events & Callbacks — programmatic hooks for logging and analytics.
  • AI Credits API & Webhooks — read credit balance/usage and receive credit webhooks server-side.
  • Content Protection — lock content and control whole-design rewrites.
  • How it works — what the assistant does at each scope.