AI Generation API
How the AI endpoint works and how to shape prompts.
The AI generation endpoint (/api/ai/generate) turns a plain-text prompt into a working Roblox GUI. This guide explains how the endpoint works, how to shape prompts for the best results, and how credits and errors are handled.
How it works: you send a prompt describing the UI you want, and the endpoint returns a stream of generated elements that load straight into the editor canvas. The AI understands Roblox-specific terms, so you can mention ScreenGui, Frame, UIGridLayout, UDim2, and Scale/Offset by name and it will use them correctly.
Prompt structure: the endpoint accepts a prompt plus three parameters - guiType (menu, shop, hud, inventory, settings, or custom), style (bright, dark, clean, or cartoon), and device (desktop or mobile). The guiType tells the AI the general layout pattern to start from; the style controls the color palette; the device sets the default proportions. A well-shaped prompt names the UI type, lists the key elements, and mentions any constraints. For example: "a pet shop GUI with a 3x3 egg grid, a green Buy button, and a coin balance header, dark style, mobile" is far better than "make a shop".
Model fallback: the endpoint tries a chain of models through OpenRouter (deepseek/deepseek-chat, then qwen/qwen-2.5-72b-instruct, then meta-llama/llama-3.3-70b-instruct). If all models fail, it refunds your credit and falls back to a Mock stream that generates a reasonable layout locally, so you are never charged for a failed generation.
Credits: Free plan users get 50 AI generation credits per month, and each generation costs one credit. Pro plan users have unlimited generations. The endpoint checks your credit balance before generating. If you are logged in and out of credits, it returns a 402 error with an upgrade URL. Anonymous (not logged in) users get a free Mock stream with OpenRouter disabled, so you can try the AI before signing up - the Mock output is a sample layout, not a real AI generation.
Errors: the endpoint streams Server-Sent Events. On success you get a stream of element chunks ending with [DONE]. On failure you get either a 402 (out of credits) or a refund plus Mock fallback. The refund happens automatically when all OpenRouter models fail, so your credit is only consumed on a successful generation.
Best practices: keep prompts specific about layout and elements, not about implementation details. The AI decides the Luau for you. If the first result is not quite right, refine it on the canvas instead of regenerating - editing on the canvas costs no credits.