The body you POST to /api/qr/generate (and that templates and the AI endpoint
override). Anything left unset falls back to the engine default — there is no
required field beyond content.
Source of truth: Models/QrModels.cs in the .NET backend. The list below covers
every public field; for a full schema dump including types and nullability run
pnpm docs:schema in the frontend repo, which regenerates this page from the
C# models.
| Field | Type | Default | Notes |
|---|
content | string | required | URL or text to encode. Max 4296 chars. |
eccLevel | enum | M | Error correction. L 7% · M 15% · Q 25% · H 30%. Bump to H when adding a logo. |
| Field | Type | Default | Notes |
|---|
fileFormat | enum | png | png, jpg, svg, pdf, webp. |
responseType | enum | base64 | base64 returns JSON; binary returns the raw file. |
outputWidth | int | 800 | Pixels. Up to 4096. |
outputHeight | int | — | Defaults to outputWidth. Override only if you need non-square. |
pixelsPerModule | int | 10 | Resolution per QR module. Bumps outputWidth if not set. |
quality | int | 90 | JPG/WebP quality 1–100. |
transparentBackground | bool | false | PNG/SVG/WebP only. |
| Field | Type | Default | Notes |
|---|
primaryColor | hex | #000000 | Module color. #RGB, #RRGGBB, #RRGGBBAA. |
secondaryColor | hex | — | Used by gradients and connected modules. |
backgroundColor | hex | #FFFFFF | Quiet zone color. |
foregroundStyle | enum | solid | solid, linearGradient, radialGradient, sweepGradient. |
gradientType | enum | linear | Same as foregroundStyle shorthand. |
gradientDirection | enum | vertical | vertical, horizontal, diagonal, diagonal-reverse. |
gradientColors | hex[] | — | 2–6 stops. |
gradientStops | float[] | even | 0–1 positions. Must match gradientColors.length. |
gradientAngle | int | 0 | Degrees, overrides gradientDirection if set. |
| Field | Type | Default | Notes |
|---|
qrShape | enum | square | Outer canvas: square, roundedsquare, circle. |
qrShapeRadius | int | 0 | Corner radius when qrShape: roundedsquare. |
moduleShape | enum | square | One of 27. See Patterns. |
moduleScale | float | 1.0 | 0.5–1.0. Shrinks each module for airier looks. |
moduleRotation | float | 0 | Degrees. |
moduleStyle | enum | solid | solid, outline, striped. |
modulePattern | enum | standard | standard, checker, alternating. |
moduleSizeVariation | float | 0 | 0–0.3 adds organic variation per module. |
connectedStyle | enum | none | none, fluid, sharp, round. Joins adjacent modules. |
| Field | Type | Default | Notes |
|---|
finderOuterShape | enum | square | square, roundedsquare, circle, diamond, octagon, target, double. |
finderInnerShape | enum | square | square, roundedsquare, circle, diamond, star, dot. |
finderOuterColor | hex | — | Defaults to primaryColor. |
finderInnerColor | hex | — | Defaults to primaryColor. |
finderStyle | enum | standard | standard, flat, embossed. |
| Field | Type | Default | Notes |
|---|
logoUrl | url | — | Public URL fetched server-side. PNG/JPG/GIF/BMP/WebP, ≤ 10 MB. |
logoBase64 | string | — | Inline data URI alternative. |
logoFile | multipart | — | Binary part if using multipart/form-data. |
logoShape | enum | square | square, circle, rounded. |
logoSizePercent | float | 18 | 5–30. Always raise eccLevel to H when ≥ 20. |
logoBorderWidth | int | 0 | Border thickness in pixels. |
logoBorderColor | hex | #FFFFFF | |
logoShadow | bool | false | Drop shadow under the logo. |
logoBackground | enum | none | none, solid, match-bg. |
cleanBehindLogo | bool | true | Erases modules under the logo so it doesn't fight the QR. |
| Field | Type | Notes |
|---|
centerText | object | Banner across the center: { text, color?, backgroundColor?, height?, fontSize?, bold?, fontFamily? }. |
circularText | object | Text bent around the QR: { text, color?, fontSize?, position? }. |
ctaText | string | Caption underneath the QR (e.g. "SCAN ME"). |
ctaTextStyle | object | { color?, fontSize?, fontFamily?, bold?, italic? }. |
| Field | Type | Notes |
|---|
frame | object | { enabled, shape, color, width, padding, cornerRadius, fillColor? }. Shapes: rectangle, speech-bubble, badge, shield, circle. |
| Field | Type | Notes |
|---|
backgroundImageUrl / backgroundImageBase64 | url/string | Soft image rendered behind the QR. |
backgroundImageBlendMode | enum | normal, multiply, screen, overlay. |
backgroundImageOpacity | float | 0–1. |
backgroundImageBlur | int | Pixels. |
backgroundImageFit | enum | cover, contain, stretch. |
| Field | Type | Notes |
|---|
shadow | object | { color, blur, offsetX, offsetY }. |
glow | object | { color, blur, intensity }. |
emboss | object | { depth, lightAngle, lightColor?, shadowColor? }. |
noise | float | 0–0.3 adds film grain. |
blur | int | Pixels. |
edgeFade | float | 0–0.5 fades the canvas edge. |
colorFilter | enum | none, sepia, bw, cool, warm. |
| Field | Type | Notes |
|---|
prompt | string | Plain-language description. |
stylePreset | enum | minimal, artistic, corporate, playful, luxury, tech, nature. |
creativity | float | 0–1. Controls LLM temperature + boldness. |
strictScannability | bool | When true, engine auto-fixes ECC/contrast. |
llmProvider | enum | Marketplace only: openai, anthropic, google, mistral, cohere, groq. |
llmApiKey | string | Marketplace only. Forwarded once, never logged. |
llmModel | string | Optional; defaults to provider flagship cheap model. |
- JSON well-formed →
INVALID_JSON if not.
- Field types + bounds →
VALIDATION_ERROR with details[].
- Color contrast →
LOW_CONTRAST if < 4:1 and strictScannability: true.
- Logo size vs ECC →
LOGO_TOO_LARGE if too aggressive.
- ISO 18004 decode round-trip →
QR_GENERATION_FAILED if the rendered output can't be re-read.
See Errors for the full error code matrix.
cd frontend
pnpm docs:schema # reads ../Models/QrModels.cs and rewrites this file
The script is tools/gen-docs-schema.ts. Any field added to the C# model with
a [Description] attribute shows up here automatically.