POST
POST /api/generate-icon/
Generate an icon from a text description. Returns a base64-encoded WebP image.
Request Body
subject required
Text description of the icon (e.g. "rocket ship").
style
Icon style slug. Can be a base style (line, glyph, outline, pixel, isometric) or a preset style (glassmorphism, neon, photorealistic, clay-3d, etc.). Base styles are monochrome and respect the color parameter. Preset styles have their own built-in prompt, palette, and output size. Default: line
flags
Array of flag strings that control generation behavior (e.g. ["color", "detail-high"]). See the Flags table below for all available flags. Flags that add features increase token cost.
template_id
UUID of a user-created custom prompt template. When set, the template's saved settings (color, detail level, thickness, smoothing, crop, background removal, flags) override the corresponding request parameters.
preset_id
Slug of a built-in preset template (e.g. glassmorphism, neon, clay-3d). Takes priority over style. Get available presets from GET /api/prompt-templates/.
color
Hex color code (e.g. #FF5733). Applies to base styles only — preset styles determine their own palette. Default: #000000
model
low or high. High uses a premium AI model for better results. Default: low
attached_image
Base64 image for AI refinement — send a previous icon back with new instructions. Requires a paid plan.
icon_id
UUID of a library icon to use as the attached image for refinement. Alternative to sending attached_image directly — the server fetches the image from your library.
iconify
Boolean. When true with attached_image, converts the attached image into an icon in the specified style. Requires a paid plan.
use_as_reference
Boolean. When true with attached_image, generates a new icon matching the reference's visual style. Requires a paid plan.
Flags
Pass flags in the flags array to control generation and post-processing behavior. Only one flag per group (detail, bias) can be active at a time — if multiple are provided, the last one wins.
color
Allow full color output instead of the default black/white. +2 tokens
detail-low
Extremely simple, minimal geometric shapes
detail-medium
Moderate detail on the subject. +1 token
detail-high
Very high detail on the subject. +2 tokens
allow-text
Allow text, letters, or words to appear in the icon (normally suppressed)
ai-bg
Generate a background scene or environment instead of a plain white background. Skips background removal.
keep-bg
Skip the automatic background removal post-processing step. The raw AI output is returned as-is (after recoloring and canvas sizing).
bias-{color}
Bias the output toward a color theme (e.g. bias-blue, bias-red)
{
"subject": "rocket ship",
"style": "line",
"flags": ["color", "detail-high", "ai-bg"]
}
Response
{
"image_data": "base64-encoded WebP image",
"remaining_tokens": 293,
"monthly_tokens": 280,
"bonus_tokens": 13,
"token_cap": 300
}
Token Cost
6–8 base tokens, plus modifiers for color, detail level, canvas size, and model tier. See Token System above.
Parameter Precedence
When multiple parameters target the same behavior, the following precedence rules apply:
Template Resolution
Only one template source is used per request, resolved in this order:
- preset_id — checked first. If a matching preset exists, it is used.
- style — if preset_id is not set, the style value is checked against presets. If it matches a preset slug (e.g. glassmorphism), that preset is used instead of the base style.
- template_id — only used if neither preset_id nor a preset-style match was found.
Template Overrides
When a template or preset is active, its saved settings override request parameters:
- Color mode (color flag) is replaced by the template's use_color setting
- Detail level flags (detail-low, detail-medium, detail-high) are replaced by the template's detail_level
- allow-text, ai-bg, keep-bg, and bias-{color} flags are replaced by the template's corresponding settings
- Post-processing (thickness, smoothing, crop, background removal) uses the template's saved values
Attached Image Modes
When attached_image (or icon_id) is provided, these modes are mutually exclusive and resolved in this order:
- iconify: true — converts the image into an icon. Wins over all other modes.
- use_as_reference: true — uses the image as a style reference. Only activates if iconify is not set.
- Otherwise — treated as a refinement (iterates on the attached icon using the prompt).
All three modes force the premium AI model regardless of the model parameter, and skip template post-processing (thickness, smoothing, crop).
Image Source
attached_image (raw base64) takes priority over icon_id. If both are provided, icon_id is ignored. The server only fetches the library icon when no attached_image is present.
Background Removal
Background removal is applied automatically unless any of these conditions are met:
- The ai-bg flag is set (keeps the AI-generated background)
- The keep-bg flag is set (skips removal entirely)
- A template with background removal set to none is active
Canvas Size
When using use_as_reference, the reference image's dimensions override the template's output_size setting.
Social Creatives
POST /api/generate-creative/Generate social media graphics with AI-written copy. Returns HTML creative(s) ready for rendering. Multi-format platforms (Facebook, Instagram) generate 3 size variants; single-size formats support 1–3 copies.
Request Body
Token Cost
Base cost per format/copy: 12 (fast) or 25 (thinking). Multi-format platforms (Facebook, Instagram) generate 3 sizes at 3× base cost. Single-size formats with multiple copies multiply accordingly. Range: 12–75 tokens.
Response
{ "id": "uuid", "creatives": ["<div class='creative'>...</div>"], "text_content": "Generated copy text", "ad_copy": {"headline": "...", "body": "...", "cta": "..."} }