API QR Branding

L'API per codici QR più personalizzabile sul mercato. Genera codici QR d'impatto, con il tuo marchio e conformi alla norma ISO 18004, con 37 forme di moduli, 118 modelli, design con IA e 5 formati di output.

Abbonati su RapidAPI: rapidapi.com/quartzondev/api/qr-branding. I piani e le quote sono elencati nella pagina di RapidAPI.

---

Avvio rapido

1. Genera un codice QR personalizzato

curl -X POST "https://qr-branding.p.rapidapi.com/api/qr/generate" \
  -H "Content-Type: application/json" \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: qr-branding.p.rapidapi.com" \
  -d '{
    "content": "https://example.com",
    "primaryColor": "#1a1a2e",
    "backgroundColor": "#FFFFFF",
    "moduleShape": "circle",
    "fileFormat": "png",
    "outputWidth": 512,
    "eccLevel": "H"
  }'

Risposta:

{
  "success": true,
  "qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "format": "png",
  "contentType": "image/png",
  "sizeBytes": 15234
}

2. Genera da un modello

curl -X POST "https://qr-branding.p.rapidapi.com/api/qr/templates/cyber-neon" \
  -H "Content-Type: application/json" \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: qr-branding.p.rapidapi.com" \
  -d '{
    "content": "https://mywebsite.com",
    "outputWidth": 600
  }'

3. Codice QR progettato con l'IA

curl -X POST "https://qr-branding.p.rapidapi.com/api/qr/ai/generate" \
  -H "Content-Type: application/json" \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: qr-branding.p.rapidapi.com" \
  -d '{
    "prompt": "A luxurious gold and black QR code with rounded modules and a subtle glow effect, suitable for a premium brand",
    "content": "https://premium-brand.com",
    "llmProvider": "openai",
    "llmApiKey": "sk-your-openai-key",
    "creativity": 0.7,
    "strictScannability": true,
    "stylePreset": "luxury"
  }'

Risposta:

{
  "success": true,
  "qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "format": "png",
  "contentType": "image/png",
  "sizeBytes": 28456,
  "generatedConfig": { },
  "aiExplanation": "I designed a premium QR code with...",
  "llmProviderUsed": "openai",
  "llmModelUsed": "gpt-6-luna"
}

---

Esempi di codice

Python

import requests

url = "https://qr-branding.p.rapidapi.com/api/qr/generate"
headers = {
    "Content-Type": "application/json",
    "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
    "X-RapidAPI-Host": "qr-branding.p.rapidapi.com"
}
payload = {
    "content": "https://example.com",
    "primaryColor": "#FF6B35",
    "moduleShape": "star",
    "eccLevel": "H",
    "outputWidth": 800,
    "fileFormat": "png"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if data["success"]:
    import base64
    img_bytes = base64.b64decode(data["qrBase64"])
    with open("my_qr.png", "wb") as f:
        f.write(img_bytes)
    print(f"QR saved! Size: {data['sizeBytes']} bytes")

JavaScript (Node.js)

const response = await fetch(
  "https://qr-branding.p.rapidapi.com/api/qr/generate",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
      "X-RapidAPI-Host": "qr-branding.p.rapidapi.com",
    },
    body: JSON.stringify({
      content: "https://example.com",
      primaryColor: "#0066FF",
      moduleShape: "hexagon",
      eccLevel: "H",
      outputWidth: 600,
      fileFormat: "png",
    }),
  }
);

const data = await response.json();

if (data.success) {
  const buffer = Buffer.from(data.qrBase64, "base64");
  require("fs").writeFileSync("qr_code.png", buffer);
  console.log(`QR generated: ${data.sizeBytes} bytes`);
}

---

Panoramica delle funzionalità

---

Categorie di modelli (28)

Tecnologia, Aziendale, Social, Lusso, Natura, Artistico, Marketing, Eventi, Musica, Divertimento, Sfondo, Cultura, Industria, Ristorazione, Commercio al dettaglio, Istruzione, Viaggi, Automotive, Assistenza sanitaria, Social media, Arte e design, Business, Cibo e bevande, Finanza, Salute, Legale, Non profit, Immobiliare.

Usa GET /api/qr/templates?category=luxury per filtrare per categoria.

---

Fornitori e modelli di IA

Funziona qualsiasi ID di modello offerto dal tuo provider; questo elenco mostra quelli consigliati.

Nota: su /api/qr/ai/generate fornisci la tua chiave API per il fornitore di LLM scelto e il fornitore ti fattura direttamente; QR Branding non aggiunge alcun sovrapprezzo. Su /api/qr/ai/generate-managed non serve nessuna chiave di LLM: i modelli li eseguiamo noi, e queste chiamate contano per la quota separata di IA gestita del tuo piano.

---

Endpoint

POST /api/qr/generate — Genera un QR personalizzato

Genera un codice QR completamente personalizzabile con oltre 100 parametri, tra cui forme dei moduli, gradienti, effetti, loghi, testi sovrapposti, cornici e altro ancora. Accetta un corpo JSON oppure multipart/form-data per caricare il file del logo.

Corpo della richiesta:

{
  "content": "https://example.com",
  "eccLevel": "H",
  "pixelsPerModule": 20,
  "outputWidth": 512,
  "fileFormat": "png",
  "quality": 90,
  "responseType": "base64",
  "backgroundColor": "#FFFFFF",
  "transparentBackground": false,
  "primaryColor": "#000000",
  "secondaryColor": null,
  "foregroundStyle": "solid",
  "gradientType": "linear",
  "gradientDirection": "vertical",
  "gradientColors": ["#FF0000", "#0000FF"],
  "gradientStops": [0.0, 1.0],
  "gradientAngle": 0,
  "qrShape": "square",
  "moduleShape": "square",
  "moduleScale": 0.85,
  "moduleRotation": 0,
  "moduleStyle": "solid",
  "modulePattern": "standard",
  "connectedStyle": "none",
  "finderOuterShape": "square",
  "finderInnerShape": "square",
  "finderOuterColor": "#000000",
  "finderInnerColor": "#000000",
  "finderStyle": "standard",
  "logoUrl": "https://example.com/logo.png",
  "logoShape": "circle",
  "logoSizePercent": 18,
  "logoBorderWidth": 2,
  "logoBorderColor": "#FFFFFF",
  "logoShadow": true,
  "logoBackground": "solid",
  "ctaText": "SCAN ME"
}

Risposta 200:

{
  "success": true,
  "qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "format": "png",
  "contentType": "image/png",
  "sizeBytes": 15234
}

Risposta 400:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed with 1 error.",
    "details": [
      {
        "field": "moduleShape",
        "code": "INVALID_MODULE_SHAPE",
        "message": "Invalid module shape 'triangle'. Valid shapes: square, circle, diamond, star, heart, hexagon, leaf, cross, dot, mosaic, clipped, edgecut, pointed, pill, rounded, japanese, octagon, shield, arrow, drop."
      }
    ]
  }
}

---

POST /api/qr/ai/generate — Genera un QR con l'IA

Descrivi in linguaggio naturale il codice QR che hai in mente e lascia che l'IA lo progetti per te. Supporta 9 fornitori di LLM e qualsiasi endpoint compatibile con OpenAI (local); è accettato qualsiasi ID di modello offerto dal tuo fornitore. Qui fornisci la tua chiave API dell'LLM; se preferisci non usarne una, usa POST /api/qr/ai/generate-managed (più sotto).

Corpo della richiesta:

{
  "prompt": "A modern tech-style QR code with hexagonal modules, a blue-to-purple gradient, subtle glow effect, and rounded finder patterns",
  "content": "https://myapp.com",
  "llmProvider": "openai",
  "llmApiKey": "sk-your-api-key-here",
  "llmModel": "gpt-6-luna",
  "creativity": 0.7,
  "strictScannability": true,
  "stylePreset": "tech",
  "fileFormat": "png",
  "outputWidth": 800,
  "logoUrl": "https://example.com/logo.png",
  "ctaText": "Download App"
}

Risposta 200:

{
  "success": true,
  "qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "format": "png",
  "contentType": "image/png",
  "sizeBytes": 28456,
  "generatedConfig": {
    "content": "https://myapp.com",
    "moduleShape": "hexagon",
    "primaryColor": "#4A90D9",
    "gradientColors": ["#4A90D9", "#7B2FF7"],
    "gradientType": "linear",
    "gradientDirection": "vertical",
    "finderOuterShape": "roundedsquare",
    "finderInnerShape": "circle",
    "eccLevel": "H"
  },
  "aiExplanation": "I designed a tech-inspired QR code with hexagonal modules...",
  "llmProviderUsed": "openai",
  "llmModelUsed": "gpt-6-luna"
}

---

POST /api/qr/ai/generate-managed — IA gestita (senza chiave LLM)

Stesso formato di richiesta di /api/qr/ai/generate, ma llmProvider, llmApiKey e llmModel vengono ignorati: non serve nessuna chiave LLM. Il motore usa i propri modelli con una catena di riserva (Groq → Gemini → OpenAI). Le chiamate contano per la quota di IA gestita del tuo piano.

{
  "prompt": "A luxurious gold and black QR with rounded modules and a subtle glow effect",
  "content": "https://premium-brand.com",
  "creativity": 0.7,
  "strictScannability": true,
  "stylePreset": "luxury",
  "fileFormat": "png",
  "outputWidth": 800
}

La risposta ha lo stesso formato di /api/qr/ai/generate, con in più il campo "managed": true.

---

GET /api/qr/ai/providers — Ottieni i fornitori di IA

Elenca tutti i fornitori di LLM supportati e i modelli disponibili per la generazione di QR con l'IA.

Risposta 200:

{
  "success": true,
  "count": 10,
  "providers": [
    {
      "id": "openai",
      "name": "OpenAI",
      "defaultModel": "gpt-6-luna",
      "availableModels": ["gpt-6-astra", "gpt-6.1-sol", "gpt-6-luna", "gpt-6-sol", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-4.1-mini"]
    },
    {
      "id": "anthropic",
      "name": "Anthropic",
      "defaultModel": "claude-sonnet-5-5",
      "availableModels": ["claude-fable-5-1", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-4-5"]
    }
  ]
}

---

GET /api/qr/templates — Elenca i modelli

Sfoglia 118 modelli di codici QR progettati da professionisti in 28 categorie.

Parametri di query:

Risposta 200:

{
  "success": true,
  "count": 118,
  "categories": [
    "Technology", "Corporate", "Social", "Luxury", "Nature",
    "Artistic", "Marketing", "Events", "Music", "Fun"
  ],
  "templates": [
    {
      "id": "cyber-neon",
      "name": "Cyber Neon",
      "category": "Technology",
      "description": "Futuristic glowing neon style with diamond modules and vibrant cyan-pink gradient"
    },
    {
      "id": "professional-blue",
      "name": "Professional Blue",
      "category": "Corporate",
      "description": "Clean corporate style with blue gradient, ideal for business"
    }
  ]
}

---

POST /api/qr/templates/{templateId} — Genera da un modello

Genera un codice QR a partire da un modello già pronto. Il design visivo del modello viene mantenuto; puoi sovrascrivere facoltativamente le impostazioni di output.

Parametri di percorso:

Corpo della richiesta:

{
  "content": "https://mywebsite.com",
  "fileFormat": "png",
  "responseType": "base64",
  "outputWidth": 600,
  "logoUrl": "https://example.com/logo.png",
  "ctaText": "Visit Us"
}

Risposta 200:

{
  "success": true,
  "qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "format": "png",
  "contentType": "image/png",
  "sizeBytes": 22100
}

---

POST /api/qr/content/wifi — Genera una stringa WiFi

Genera una stringa di connessione WiFi da codificare nel QR. Chi scansiona il codice QR riceverà automaticamente la proposta di connettersi alla rete.

Corpo della richiesta:

{
  "ssid": "MyNetwork",
  "password": "MyP@ssw0rd!",
  "encryption": "WPA",
  "hidden": false
}

Risposta 200:

{
  "success": true,
  "text": "WIFI:T:WPA;S:MyNetwork;P:MyP@ssw0rd!;H:false;;"
}

---

POST /api/qr/content/vcard — Genera una stringa vCard

Genera una stringa di contatto vCard da codificare nel QR. Alla scansione, il codice QR proporrà di salvare il contatto sul telefono.

Corpo della richiesta:

{
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1-555-123-4567",
  "email": "john.doe@example.com",
  "org": "Acme Corp",
  "url": "https://johndoe.com"
}

Risposta 200:

{
  "success": true,
  "text": "BEGIN:VCARD\nVERSION:3.0\nN:Doe;John\nFN:John Doe\nTEL:+1-555-123-4567\nEMAIL:john.doe@example.com\nORG:Acme Corp\nURL:https://johndoe.com\nEND:VCARD"
}

---

POST /api/qr/content/geo — Genera una stringa di geolocalizzazione

Genera un URI di geolocalizzazione da codificare nel QR. Alla scansione, il codice QR aprirà la posizione nell'app di mappe predefinita dell'utente.

Corpo della richiesta:

{
  "lat": 40.7128,
  "lng": -74.0060
}

Risposta 200:

{
  "success": true,
  "text": "geo:40.7128,-74.006"
}

---

Gestione degli errori

Tutti gli errori seguono un formato coerente:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed with 2 errors.",
    "details": [
      {
        "field": "primaryColor",
        "code": "INVALID_COLOR_FORMAT",
        "message": "Invalid color format. Use hex (#RRGGBB or #RRGGBBAA).",
        "value": "not-a-color"
      }
    ]
  }
}

Codici di errore

Convalida (400) VALIDATION_ERROR · INVALID_JSON · MISSING_REQUIRED_FIELD · INVALID_FIELD_VALUE · INVALID_COLOR_FORMAT · INVALID_FILE_FORMAT · CONTENT_TOO_LONG · FILE_TOO_LARGE · INVALID_URL · INVALID_ECC_LEVEL · INVALID_MODULE_SHAPE · INVALID_GRADIENT_TYPE · INVALID_RESPONSE_TYPE · VALUE_OUT_OF_RANGE · MULTIPART_CONFIG_MISSING

Autenticazione (401) UNAUTHORIZED · INVALID_API_KEY · MISSING_API_KEY

Non trovato (404) RESOURCE_NOT_FOUND · TEMPLATE_NOT_FOUND

Errori IA/LLM (400/500) INVALID_LLM_PROVIDER · INVALID_LLM_MODEL · LLM_API_KEY_INVALID · AI_GENERATION_FAILED · AI_CONFIG_INVALID · AI_REQUEST_TIMEOUT

Budget di output (422) OUTPUT_TOO_COMPLEX — il design produrrebbe un SVG o PDF oltre i 20 MB o una tela oltre i 5120 px per lato. Esporta in PNG, accorcia il contenuto o usa forme di modulo più semplici

Capacità (503) SERVER_BUSY · AI_QUOTA_EXCEEDED (l'IA gestita ha esaurito la quota su tutti i provider; riprova più tardi)

Errori del server (500) INTERNAL_ERROR · QR_GENERATION_FAILED · LOGO_LOAD_FAILED · BACKGROUND_LOAD_FAILED