QrConfigリファレンス

/api/qr/generate にPOSTするボディです（テンプレートとAIエンドポイントは、これを上書きします）。指定しなかった項目はエンジンのデフォルトが使われます。content 以外に必須のフィールドはありません。

情報源: .NETバックエンドの Models/QrModels.cs。以下の一覧はすべての公開フィールドを網羅しています。型やnull許容を含む完全なスキーマを出力するには、フロントエンドのリポジトリで pnpm docs:schema を実行してください。C#のモデルからこのページが再生成されます。

コンテンツ

フィールド	型	デフォルト	備考
`content`	string	必須	エンコードするURLまたはテキスト。最大4296文字。
`eccLevel`	enum	`M`	誤り訂正。`L 7%` · `M 15%` · `Q 25%` · `H 30%`。ロゴを追加するときは `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`	QRモジュール1つあたりの解像度。未設定の場合は `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`。隣接するモジュールをつなげます。

ファインダーパターン（3つの大きな目）

フィールド	型	デフォルト	備考
`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	—	代替としてのインラインのデータ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`	ロゴの下にドロップシャドウ。
`logoBackground`	enum	`none`	`none`、`solid`、`match-bg`。
`cleanBehindLogo`	bool	`true`	ロゴがQRと干渉しないよう、ロゴの下のモジュールを消去します。

テキストオーバーレイ

フィールド	型	備考
`centerText`	object	中央を横切るバナー: `{ text, color?, backgroundColor?, height?, fontSize?, bold?, fontFamily? }`。
`circularText`	object	QRの周囲に沿って曲がるテキスト: `{ text, color?, fontSize?, position? }`。
`ctaText`	string	QRの下のキャプション（例: 「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	QRの背後に描画する控えめな画像。
`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`。

AI専用（`/api/qr/ai/generate*` のみ）

フィールド	型	備考
`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	任意。デフォルトはそのプロバイダーの低価格な主力モデル。

検証の順序

JSONが整形式か → そうでなければ INVALID_JSON。
フィールドの型と範囲 → details[] 付きの VALIDATION_ERROR。
色のコントラスト → 4:1未満かつ strictScannability: true なら LOW_CONTRAST。
ECCに対するロゴのサイズ → 大きすぎる場合は LOGO_TOO_LARGE。
ISO 18004のデコード往復テスト → レンダリング結果を再度読み取れなければ QR_GENERATION_FAILED。

エラーコードの一覧はエラーをご覧ください。

このページの再生成

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

スクリプトは tools/gen-docs-schema.ts です。C#のモデルに [Description] 属性付きで追加したフィールドは、自動的にここに表示されます。