QR Code Generator API

Base URL

https://qrcode.plz.ac

Local dev: http://localhost:8787

GET /api/health

Health check endpoint

Response:

{
  "ok": true
}

GET /api/generate

Generate a QR code as SVG. Returns an SVG image with Content-Type: image/svg+xml.

快速开始

最简单的文本二维码：

GET /api/generate?dataType=text&text=Hello

Common Parameters (All Data Types)

Parameter	Required	Type	Description	Default
dataType	❌	string	QR code type: text, url, wifi, email, sms, geo, contact	text
size	❌	integer	Output size in pixels (64-2048)	256
margin	❌	integer	Margin around QR in cells (0-16)	2
ecLevel	❌	string	Error correction level: L (7%), M (15%), Q (25%), H (30%)	M

Data Type: text / url

Parameter	Required	Type	Description
text	✅	string	Plain text or URL. For URLs, must start with http:// or https://

Examples:

# Text QR code
GET /api/generate?dataType=text&text=Hello%20World

# URL QR code
GET /api/generate?dataType=url&text=https://qrcode.plz.ac

# Using curl
curl "https://qrcode.plz.ac/api/generate?dataType=url&text=https://example.com" -o qr.svg

Data Type: wifi

Parameter	Required	Type	Description	Default
ssid	✅	string	WiFi network name	-
password	❌	string	WiFi password (omit for open networks)	-
auth	❌	string	Auth type: WEP, WPA, nopass	WPA
hidden	❌	boolean	Hidden SSID: true or false	false

Example:

GET /api/generate?dataType=wifi&ssid=MyNetwork&password=MyPassword123&auth=WPA

Data Type: email

Parameter	Required	Type	Description
to	✅	string	Recipient email address
subject	❌	string	Email subject
body	❌	string	Email body text

Example:

GET /api/generate?dataType=email&to=hello@qrcode.plz.ac&subject=Hello&body=Message%20text

Data Type: sms

Parameter	Required	Type	Description
to	✅	string	Phone number (with country code, e.g., +1234567890)
body	❌	string	SMS message text

Example:

GET /api/generate?dataType=sms&to=%2B1234567890&body=Hello%20from%20QR

Data Type: geo

Parameter	Required	Type	Description
lat	✅	number	Latitude (-90 to 90)
lon	✅	number	Longitude (-180 to 180)

Example:

GET /api/generate?dataType=geo&lat=37.7749&lon=-122.4194

Data Type: contact

Parameter	Required	Type	Description
name	❌	string	Contact name
tel	❌	string	Phone number
email	❌	string	Email address
adr	❌	string	Physical address

Example:

GET /api/generate?dataType=contact&name=John%20Doe&tel=%2B1234567890&email=john@example.com

Response Format

✅ Success (200 OK): Returns SVG image

• Content-Type: image/svg+xml
• SVG dimensions vary based on QR code version (typically 236-256px)
• Can be embedded directly in HTML: <img src="/api/generate?dataType=text&text=Hello">

❌ Error (400 Bad Request): Returns JSON error

{
  "error": "text is required"
}

Important Notes

• 📝 URL Encoding: Use %20 for spaces, %2B for +, etc.
• 🔗 URLs: Must include protocol (http:// or https://)
• 📱 Phone Numbers: Include country code with + (encode as %2B)
• 📏 Size Limits: QR code size 64-2048px, margin 0-16 cells
• 🔒 WiFi Auth: Use nopass for open networks
• ⚡ Error Correction: Higher levels (Q, H) = more redundancy but larger codes

Quick Reference

Minimal examples for each type:

# Text
/api/generate?dataType=text&text=Hello

# URL
/api/generate?dataType=url&text=https://example.com

# WiFi
/api/generate?dataType=wifi&ssid=MyWiFi&password=secret

# Email
/api/generate?dataType=email&to=user@example.com

# SMS
/api/generate?dataType=sms&to=%2B1234567890

# Location
/api/generate?dataType=geo&lat=37.7749&lon=-122.4194

# Contact
/api/generate?dataType=contact&name=John&tel=%2B1234567890

Troubleshooting

❌ "text is required"

For text and url types, you must provide the text parameter:

✅ /api/generate?dataType=text&text=Hello
❌ /api/generate?dataType=text

❌ "ssid is required"

WiFi QR codes require at least the ssid parameter:

✅ /api/generate?dataType=wifi&ssid=MyNetwork
❌ /api/generate?dataType=wifi

❌ URL not working when scanned

URLs must include the protocol:

✅ https://example.com
❌ example.com

📱 QR Code too dense / hard to scan

Try these solutions:

• Reduce data: Shorten URLs, use less text
• Lower error correction: Use ecLevel=L
• Increase margin: Use margin=4
• Increase size: Use size=512

🔧 Testing with curl

# Save SVG to file
curl "https://qrcode.plz.ac/api/generate?dataType=text&text=Test" -o qr.svg

# View headers
curl -I "https://qrcode.plz.ac/api/generate?dataType=text&text=Test"

# Check for errors
curl "https://qrcode.plz.ac/api/generate?dataType=text" # Missing text parameter

Error Correction Levels

Level	Recovery	Use Case
L	~7% recovery	Clean environments, short data
M	~15% recovery	Default, balanced option
Q	~25% recovery	Printed materials, logos
H	~30% recovery	Damaged/dirty surfaces, logo embedding

Note: Higher error correction = larger QR codes. Use H when embedding logos or expecting damage.