QR Code API

Appearance

Logo Overlay Guide ​

Add your brand logo to the center of QR codes for professional branding.

Pro Feature

Logo overlay is available on Pro and Enterprise plans.

Basic Usage ​

bash
curl "https://www.qrcodeapi.io/api/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  --data-urlencode "data=https://example.com" \
  --data-urlencode "logo=https://example.com/logo.png" \
  --data "logoSize=25" \
  --data "errorCorrection=H" \
  -o branded-qr.png

Parameters ​

ParameterTypeDefaultDescription
logostring-URL to logo image
logoSizenumber20Logo size as % of QR code (10-40)

How It Works ​

  1. Your QR code is generated normally
  2. The logo image is fetched from the URL
  3. Logo is resized to fit within the center
  4. Logo is composited over the QR code
  5. Error correction ensures scannability

Logo Requirements ​

Supported Formats ​

  • PNG (recommended)
  • JPEG/JPG
  • SVG
  • WebP
  • GIF (first frame only)
  • Size: At least 200×200 pixels
  • Format: PNG with transparency
  • Aspect ratio: Square (1:1) works best
  • Background: Transparent or white
  • Colors: High contrast

Maximum Logo URL Length ​

Logo URLs must be under 2000 characters.

Error Correction ​

Logo overlay covers part of the QR code data. To ensure the code remains scannable, always use high error correction:

bash
# ✅ Correct: High error correction
curl "...&logo=...&errorCorrection=H"

# ❌ Wrong: May not scan reliably
curl "...&logo=...&errorCorrection=L"
Error CorrectionRecoveryWith Logo
L (7%)❌Not recommended
M (15%)⚠️Small logos only
Q (25%)✅Most logos
H (30%)✅✅Recommended

Logo Size Guidelines ​

Logo SizeResult
10-15%Subtle branding
20-25%Balanced (recommended)
30-35%Prominent branding
40%Maximum size

Scannability

Larger logos = more QR data covered = higher chance of scan failures. Test thoroughly when using sizes above 25%.

JavaScript Example ​

javascript
async function generateBrandedQR(data, logoUrl, options = {}) {
  const {
    size = 500,
    logoSize = 25,
    color = '000000',
    background = 'ffffff'
  } = options;

  const params = new URLSearchParams({
    data,
    size: size.toString(),
    color,
    background,
    errorCorrection: 'H', // Always use H with logos
    logo: logoUrl,
    logoSize: logoSize.toString()
  });

  const response = await fetch(
    `https://www.qrcodeapi.io/api/generate?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  return response.blob();
}

// Usage
const qr = await generateBrandedQR(
  'https://company.com',
  'https://company.com/logo.png',
  {
    size: 600,
    logoSize: 25,
    color: '1e40af'
  }
);

Python Example ​

python
import requests

def generate_branded_qr(data, logo_url, **options):
    params = {
        'data': data,
        'size': options.get('size', 500),
        'color': options.get('color', '000000'),
        'background': options.get('background', 'ffffff'),
        'errorCorrection': 'H',  # Always use H with logos
        'logo': logo_url,
        'logoSize': options.get('logo_size', 25)
    }
    
    response = requests.get(
        'https://www.qrcodeapi.io/api/generate',
        params=params,
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    
    response.raise_for_status()
    return response.content

# Usage
qr_image = generate_branded_qr(
    'https://company.com',
    'https://company.com/logo.png',
    size=600,
    logo_size=25
)

with open('branded-qr.png', 'wb') as f:
    f.write(qr_image)

Logo Design Best Practices ​

1. Use Simple Shapes ​

✅ Good: Simple icon, geometric shapes
❌ Bad: Complex illustrations, fine details

Simple logos are more recognizable at small sizes.

2. High Contrast Colors ​

✅ Good: Dark logo on white background
✅ Good: White logo with dark QR code
❌ Bad: Gray logo on gray background

3. Transparent Backgrounds ​

PNG with transparency works best:

  • Logo sits naturally on QR pattern
  • No awkward white box around logo
  • Professional appearance

4. Square Aspect Ratio ​

✅ Good: 200×200px square
⚠️ OK: 200×180px (slight crop)
❌ Bad: 400×100px wide banner

Non-square logos will be scaled to fit a square area.

5. Add White Border ​

If your logo is dark, add a small white/light border:

  • Ensures visibility on dark QR patterns
  • Creates visual separation
  • Improves scannability

Troubleshooting ​

QR Code Won't Scan ​

  1. Increase error correction to H
  2. Reduce logo size to 20% or less
  3. Test with different scanning apps
  4. Ensure logo has enough contrast

Logo Appears Blurry ​

  1. Use a larger source image (min 200×200px)
  2. Use PNG instead of JPEG
  3. Increase QR code size parameter

Logo Not Appearing ​

  1. Verify logo URL is publicly accessible
  2. Check URL isn't blocked by CORS
  3. Ensure URL is properly encoded
  4. Confirm you're on Pro plan or higher

Logo Colors Wrong ​

  1. Use sRGB color space
  2. Avoid CMYK images
  3. Check for color profile issues

Tech Company ​

bash
curl "...&color=4f46e5&background=f5f3ff&logo=...&logoSize=25"

E-commerce ​

bash
curl "...&color=000000&background=ffffff&logo=...&logoSize=20"

Restaurant ​

bash
curl "...&color=b91c1c&background=fef2f2&logo=...&logoSize=30"

Healthcare ​

bash
curl "...&color=059669&background=ecfdf5&logo=...&logoSize=22"