QrConfig 参考

这是你 POST 到 /api/qr/generate 的请求体（模板和 AI 端点会在其基础上覆盖）。未设置的字段都会回退到引擎默认值，除 content 外没有其他必填字段。

权威来源：.NET 后端中的 Models/QrModels.cs。下面的列表涵盖了所有公开字段；如需包含类型和可空性的完整 schema，请在前端仓库中运行 pnpm docs:schema，它会根据 C# 模型重新生成本页。

内容

字段	类型	默认值	说明
`content`	string	必填	要编码的 URL 或文本。最多 4296 个字符。
`eccLevel`	enum	`M`	纠错。`L 7%` · `M 15%` · `Q 25%` · `H 30%`。添加 logo 时请提高到 `H`。

字段	类型	默认值	说明
`fileFormat`	enum	`png`	`png`、`jpg`、`svg`、`pdf`、`webp`。
`responseType`	enum	`base64`	`base64` 返回 JSON；`binary` 返回原始文件。
`outputWidth`	int	`800`	像素。最大 `4096`。
`outputHeight`	int	—	默认等于 `outputWidth`。仅在需要非正方形时覆盖。
`pixelsPerModule`	int	`10`	每个二维码模块的分辨率。未设置时会相应提高 `outputWidth`。
`quality`	int	`90`	JPG/WebP 质量，1–100。
`transparentBackground`	bool	`false`	仅限 PNG/SVG/WebP。

字段	类型	默认值	说明
`primaryColor`	hex	`#000000`	模块颜色。`#RGB`、`#RRGGBB`、`#RRGGBBAA`。
`secondaryColor`	hex	—	用于渐变和连接模块。
`backgroundColor`	hex	`#FFFFFF`	静区颜色。
`foregroundStyle`	enum	`solid`	`solid`、`linearGradient`、`radialGradient`、`sweepGradient`。
`gradientType`	enum	`linear`	等同于 `foregroundStyle` 的简写。
`gradientDirection`	enum	`vertical`	`vertical`、`horizontal`、`diagonal`、`diagonal-reverse`。
`gradientColors`	hex[]	—	2–6 个色标。
`gradientStops`	float[]	均匀分布	0–1 的位置。必须与 `gradientColors.length` 一致。
`gradientAngle`	int	`0`	角度（度）。设置后会覆盖 `gradientDirection`。

字段	类型	默认值	说明
`qrShape`	enum	`square`	画布外形：`square`、`roundedsquare`、`circle`。
`qrShapeRadius`	int	`0`	`qrShape: roundedsquare` 时的圆角半径。
`moduleShape`	enum	`square`	27 种之一。参见模式。
`moduleScale`	float	`1.0`	`0.5–1.0`。缩小每个模块，让外观更通透。
`moduleRotation`	float	`0`	角度（度）。
`moduleStyle`	enum	`solid`	`solid`、`outline`、`striped`。
`modulePattern`	enum	`standard`	`standard`、`checker`、`alternating`。
`moduleSizeVariation`	float	`0`	`0–0.3`，为每个模块加入自然的大小变化。
`connectedStyle`	enum	`none`	`none`、`fluid`、`sharp`、`round`。连接相邻模块。

字段	类型	默认值	说明
`finderOuterShape`	enum	`square`	`square`、`roundedsquare`、`circle`、`diamond`、`octagon`、`target`、`double`。
`finderInnerShape`	enum	`square`	`square`、`roundedsquare`、`circle`、`diamond`、`star`、`dot`。
`finderOuterColor`	hex	—	默认为 `primaryColor`。
`finderInnerColor`	hex	—	默认为 `primaryColor`。
`finderStyle`	enum	`standard`	`standard`、`flat`、`embossed`。

字段	类型	默认值	说明
`logoUrl`	url	—	由服务器端获取的公开 URL。PNG/JPG/GIF/BMP/WebP，≤ 10 MB。
`logoBase64`	string	—	替代方案：内联 data URI。
`logoFile`	multipart	—	使用 `multipart/form-data` 时的二进制部分。
`logoShape`	enum	`square`	`square`、`circle`、`rounded`。
`logoSizePercent`	float	`18`	`5–30`。≥ 20 时务必将 `eccLevel` 提高到 `H`。
`logoBorderWidth`	int	`0`	边框粗细（像素）。
`logoBorderColor`	hex	`#FFFFFF`
`logoShadow`	bool	`false`	logo 下方的投影。
`logoBackground`	enum	`none`	`none`、`solid`、`match-bg`。
`cleanBehindLogo`	bool	`true`	清除 logo 下方的模块，避免与二维码相互干扰。

字段	类型	说明
`centerText`	object	横跨中心的横幅：`{ text, color?, backgroundColor?, height?, fontSize?, bold?, fontFamily? }`。
`circularText`	object	环绕二维码的弧形文字：`{ text, color?, fontSize?, position? }`。
`ctaText`	string	二维码下方的说明文字（例如“SCAN ME”）。
`ctaTextStyle`	object	`{ color?, fontSize?, fontFamily?, bold?, italic? }`。

字段	类型	说明
`frame`	object	`{ enabled, shape, color, width, padding, cornerRadius, fillColor? }`。形状：`rectangle`、`speech-bubble`、`badge`、`shield`、`circle`。

字段	类型	说明
`backgroundImageUrl` / `backgroundImageBase64`	url/string	渲染在二维码背后的柔和图片。
`backgroundImageBlendMode`	enum	`normal`、`multiply`、`screen`、`overlay`。
`backgroundImageOpacity`	float	`0–1`。
`backgroundImageBlur`	int	像素。
`backgroundImageFit`	enum	`cover`、`contain`、`stretch`。

字段	类型	说明
`shadow`	object	`{ color, blur, offsetX, offsetY }`。
`glow`	object	`{ color, blur, intensity }`。
`emboss`	object	`{ depth, lightAngle, lightColor?, shadowColor? }`。
`noise`	float	`0–0.3`，添加胶片颗粒感。
`blur`	int	像素。
`edgeFade`	float	`0–0.5`，让画布边缘渐隐。
`colorFilter`	enum	`none`、`sepia`、`bw`、`cool`、`warm`。

字段	类型	说明
`prompt`	string	自然语言描述。
`stylePreset`	enum	`minimal`、`artistic`、`corporate`、`playful`、`luxury`、`tech`、`nature`。
`creativity`	float	`0–1`。控制 LLM 的 temperature 和大胆程度。
`strictScannability`	bool	为 `true` 时，引擎会自动修正 ECC/对比度。
`llmProvider`	enum	仅限市场：`openai`、`anthropic`、`google`、`mistral`、`cohere`、`groq`。
`llmApiKey`	string	仅限市场。只转发一次，从不记录日志。
`llmModel`	string	可选；默认使用该提供商的低价旗舰模型。

完整的错误代码列表请参阅错误。

cd frontend
pnpm docs:schema   # reads ../Models/QrModels.cs and rewrites this file

脚本是 tools/gen-docs-schema.ts。在 C# 模型中添加并带有 [Description] 特性的字段会自动出现在这里。