Zum Inhalt springen

QR Branding API

Die anpassbarste QR-Code-API, die es gibt. Erzeuge eindrucksvolle, gebrandete QR-Codes nach ISO 18004 mit 37 Modulformen, 118 Vorlagen, KI-gestütztem Design und 5 Ausgabeformaten.

Auf RapidAPI abonnieren: rapidapi.com/quartzondev/api/qr-branding. Pläne und Kontingente stehen auf der RapidAPI-Seite.


Schnellstart

1. Einen individuellen QR-Code erzeugen

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"
  }'

Antwort:

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

2. Aus einer Vorlage erzeugen

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. KI-gestalteter QR-Code

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"
  }'

Antwort:

{
  "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"
}

Codebeispiele

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`);
}

Funktionen im Überblick

KategorieDetails
Modulformen37: square, circle, diamond, star, heart, hexagon, leaf, cross, dot, mosaic, clipped, edgecut, pointed, pill, rounded, japanese, octagon, shield, arrow, drop + eigenes SVG
Vorlagen118 vorgestaltete in 28 Kategorien
KI-Anbieter9 LLM-Anbieter plus jeder OpenAI-kompatible Endpunkt (eigener Schlüssel) oder verwaltete KI ohne Schlüssel
AusgabeformatePNG, JPEG, SVG, PDF, WebP
Maximale Auflösung4.096 × 4.096 Pixel
FarbverläufeLinear, radial, konisch, mit beliebig vielen Farbstopps
Visuelle EffekteSchatten, Leuchten/Neon, Prägung/3D, Rauschen, Unschärfe, Randausblendung, Farbfilter
LogoURL oder Base64, Formen rund/quadratisch/abgerundet, Schatten, frei wählbare Größe
TextüberlagerungenKreistext, Band in der Mitte, CTA-Banner
RahmenRechteck, Sprechblase, Abzeichen, Schild, Kreis
FehlerkorrekturL (7%), M (15%), Q (25%), H (30%) – ISO 18004
InhaltshelferString-Generatoren für WLAN, vCard und Geostandort
HintergrundbilderURL/Base64, Mischmodi, Einpassungsmodi, Unschärfe
Verbundene ModuleFließende, kantige und runde Verbindungen für künstlerische Designs

Vorlagenkategorien (28)

Technology, Corporate, Social, Luxury, Nature, Artistic, Marketing, Events, Music, Fun, Background, Culture, Industry, Restaurant, Retail, Education, Travel, Automotive, Healthcare, Social Media, Art & Design, Business, Food & Drink, Finance, Health, Legal, Non-Profit, Real Estate.

Nutze GET /api/qr/templates?category=luxury, um nach Kategorie zu filtern.


KI-Anbieter & Modelle

AnbieterModelle
OpenAIgpt-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
Anthropicclaude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-4-5
Googlegemini-3.1-pro-preview, gemini-3.8-flash, gemini-3.5-flash-lite, gemini-3.5-flash
Mistralmistral-large-latest, mistral-medium-latest, mistral-small-latest
Coherecommand-a-plus-05-2026, command-a-03-2025, command-a-reasoning-08-2025, command-r7b-12-2024
Groqopenai/gpt-oss-120b, openai/gpt-oss-20b, llama-3.3-70b-versatile
xAIgrok-4.7, grok-4.3, grok-4.20-0309-non-reasoning
DeepSeekdeepseek-v4-pro, deepseek-flash
Qwenqwen3.8-max, qwen3.7-plus, qwen3.8-flash
LocalJeder OpenAI-kompatible Endpunkt (Ollama, LM Studio, vLLM); setze llmProvider: "local" und übergib localEndpoint

Jede Modell-ID, die dein Anbieter anbietet, funktioniert; diese Liste zeigt die empfohlenen.

Hinweis: Bei /api/qr/ai/generate bringst du deinen eigenen API-Schlüssel für den gewählten LLM-Anbieter mit, und der Anbieter rechnet direkt mit dir ab; QR Branding schlägt nichts auf. Bei /api/qr/ai/generate-managed ist kein LLM-Schlüssel nötig: Wir betreiben die Modelle, und diese Aufrufe zählen auf das separate Kontingent für verwaltete KI deines Plans.


Endpunkte

POST /api/qr/generate – individuellen QR-Code erzeugen

Erzeugt einen vollständig anpassbaren QR-Code mit über 100 Parametern, darunter Modulformen, Farbverläufe, Effekte, Logos, Textüberlagerungen, Rahmen und mehr. Unterstützt einen JSON-Body oder multipart/form-data für den Upload einer Logodatei.

Request-Body:

{
  "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"
}

Antwort 200:

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

Antwort 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 – QR-Code mit KI erzeugen

Beschreib deinen idealen QR-Code in natürlicher Sprache und lass die KI ihn für dich gestalten. Unterstützt 9 LLM-Anbieter und jeden OpenAI-kompatiblen Endpunkt (local); jede Modell-ID, die dein Anbieter anbietet, wird akzeptiert. Hier bringst du deinen eigenen LLM-API-Schlüssel mit; wenn du lieber keinen verwenden möchtest, nutze POST /api/qr/ai/generate-managed (unten).

Request-Body:

{
  "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"
}

Antwort 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 – Verwaltete KI (ohne LLM-Schlüssel)

Gleiches Anfrageformat wie /api/qr/ai/generate, aber llmProvider, llmApiKey und llmModel werden ignoriert: Du brauchst keinen LLM-Schlüssel. Die Engine nutzt eigene Modelle mit einer Ausweichkette (Groq → Gemini). Die Aufrufe zählen auf das Kontingent für verwaltete KI deines Plans.

{
  "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
}

Die Antwort hat dasselbe Format wie /api/qr/ai/generate, zusätzlich mit dem Feld "managed": true.


GET /api/qr/ai/providers – KI-Anbieter abrufen

Listet alle unterstützten LLM-Anbieter und ihre verfügbaren Modelle für die KI-gestützte QR-Erzeugung auf.

Antwort 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 – Vorlagen auflisten

Durchsuche 118 professionell gestaltete QR-Code-Vorlagen in 28 Kategorien.

Query-Parameter:

ParameterTypPflichtBeschreibung
categorystringNeinNach Kategorie filtern (z. B. luxury, corporate, social)

Antwort 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} – aus einer Vorlage erzeugen

Erzeugt einen QR-Code mit einer vorgestalteten Vorlage. Das visuelle Design der Vorlage bleibt erhalten; die Ausgabeeinstellungen kannst du optional überschreiben.

Pfadparameter:

ParameterTypPflichtBeschreibung
templateIdstringJaVorlagen-ID aus dem Endpunkt „Vorlagen auflisten“ (z. B. cyber-neon)

Request-Body:

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

Antwort 200:

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

POST /api/qr/content/wifi – WLAN-String erzeugen

Erzeugt einen WLAN-Verbindungsstring zum Codieren im QR-Code. Wer den QR-Code scannt, wird automatisch gefragt, ob er sich mit dem Netzwerk verbinden will.

Request-Body:

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

Antwort 200:

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

POST /api/qr/content/vcard – vCard-String erzeugen

Erzeugt einen vCard-Kontaktstring zum Codieren im QR-Code. Beim Scannen fordert der QR-Code dazu auf, den Kontakt im Telefon zu speichern.

Request-Body:

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

Antwort 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 – Geostandort-String erzeugen

Erzeugt eine Geostandort-URI zum Codieren im QR-Code. Beim Scannen öffnet der QR-Code den Ort in der Standard-Karten-App des Nutzers.

Request-Body:

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

Antwort 200:

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

POST /api/qr/scan-check – prüfen, ob ein Design scannt

Simuliere, wie ein gedruckter Code gelesen wird, bevor er in die Druckerei geht. Sende denselben QrConfig wie an /api/qr/generate (content ist das einzige Pflichtfeld): Die Engine rendert genau dieses Design und dekodiert es unter 13 simulierten Bedingungen (baseline, small-print, far-away, slight-blur, strong-blur, dim-light, low-contrast, uneven-light, glare, noise, rotated, angle-30 und angle-40). Das ist eine Simulation, keine Garantie: Sie zeigt, was das Rendering unter diesen Bedingungen zurückliest, nicht, dass jedes Telefon den Code scannt. Ausgabeeinstellungen (fileFormat, responseType, outputWidth, outputHeight, pixelsPerModule) werden ignoriert, weil die Prüfung ihr eigenes PNG rendert.

Request-Body:

{
  "content": "https://example.com/menu",
  "eccLevel": "H",
  "primaryColor": "#1a1a2e",
  "backgroundColor": "#FFFFFF",
  "moduleShape": "circle",
  "finderOuterShape": "roundedsquare"
}

Antwort 200:

{
  "success": true,
  "grade": "good",
  "symbolModules": 33,
  "version": 4,
  "smallestModulePx": 1.5,
  "conditions": [
    { "id": "baseline", "core": true, "passed": true, "adaptiveReader": true, "globalReader": true },
    { "id": "small-print", "core": true, "passed": true, "adaptiveReader": true, "globalReader": true },
    { "id": "glare", "core": false, "passed": true, "adaptiveReader": true, "globalReader": false },
    { "id": "angle-40", "core": false, "passed": false, "adaptiveReader": false, "globalReader": false }
  ],
  "sizes": [
    { "id": "table", "distanceCm": 40, "minSideMm": 55 },
    { "id": "wall", "distanceCm": 150, "minSideMm": 200 },
    { "id": "street", "distanceCm": 400, "minSideMm": 530 }
  ],
  "designScore": 96,
  "designWarnings": [],
  "elapsedMs": 812
}

grade ist excellent, good, fair oder poor. Jede Bedingung nennt passed, core (für die Note good erforderlich) und welcher der beiden Decoder der Engine sie gelesen hat (adaptiveReader, globalReader; zusammen ergeben sie die Zahl der Leser, 0–2). sizes gibt die minimale Druckkante in Millimetern für das Lesen am Tisch (40 cm), an der Wand (1,5 m) und auf der Straße (4 m); minSideMm ist null, wenn das Design in keiner geprüften Auflösung gelesen wurde. designScore ist die statische ISO-18004-Designbewertung der Engine (0–100) und designWarnings listet die QrConfig-Felder, die diese Regeln beanstandet haben.

Fehler: 400 Validierung (VALIDATION_ERROR, INVALID_JSON, MISSING_REQUIRED_FIELD) · 401 UNAUTHORIZED · 500 QR_GENERATION_FAILED.


GET /api/qr/templates/{templateId}/config – Design einer Vorlage auslesen

Lies das Design einer Vorlage, ohne einen QR-Code zu rendern. config ist der vollständige QrConfig der Vorlage: Übernimm beliebige Felder, setze deinen eigenen content und schicke das Ergebnis an /api/qr/generate, um eine angepasste Version zu rendern.

Pfadparameter:

ParameterTypPflichtBeschreibung
templateIdstringJaVorlagen-ID aus dem Endpunkt zum Auflisten der Vorlagen (z. B. cyber-neon)

Antwort 200:

{
  "success": true,
  "id": "cyber-neon",
  "name": "Cyber Neon",
  "category": "Technology",
  "description": "Futuristic glowing neon style with diamond modules and vibrant cyan-pink gradient",
  "config": {
    "eccLevel": "H",
    "primaryColor": "#00f2ea",
    "secondaryColor": "#FF7AA4",
    "backgroundColor": "#0a0a12",
    "foregroundStyle": "linearGradient",
    "gradientDirection": "diagonal",
    "moduleShape": "diamond",
    "finderOuterShape": "roundedsquare",
    "finderInnerShape": "diamond",
    "logoSizePercent": 22
  }
}

Fehler: 404 TEMPLATE_NOT_FOUND, wenn die id nicht existiert.


POST /api/qr/poster – druckfertiges Poster erzeugen

Bette ein QR-Design in ein druckfertiges Poster ein: A4, A5, A6 (Hochformat) oder US Letter, mit optionaler Überschrift, Hinweiszeile und Fußzeile, dem Logo des Designs, 3 mm Beschnittzugabe und Schnittmarken. qr übernimmt genau den Body von /api/qr/generate; fileFormat und responseType werden hier ignoriert, weil das Poster die Datei bestimmt. PDF ist vektoriell und behält dieselbe Scan-Garantie wie /api/qr/generate; PNG ist für Vorschauen gedacht.

Request-Body:

{
  "qr": {
    "content": "https://example.com/menu",
    "eccLevel": "H",
    "primaryColor": "#1a1a2e",
    "backgroundColor": "#FFFFFF",
    "moduleShape": "circle"
  },
  "poster": {
    "format": "a4",
    "layout": "band",
    "headline": "Scan the menu",
    "instruction": "Point your camera at the code",
    "footer": "example.com",
    "showLogo": true,
    "bleed": true,
    "cropMarks": true,
    "fileFormat": "pdf",
    "responseType": "base64"
  }
}

Poster-Optionen:

ParameterTypStandardBeschreibung
formatstringa4Endformat: a4, a5, a6 (Hochformat) oder letter (US Letter, Hochformat)
layoutstringminimalminimal, band (Kopfbalken in der Akzentfarbe), card (Karte mit Rahmen) oder tent (faltbarer Tischaufsteller)
headlinestring—Große Überschrift über dem QR
instructionstring—Kurze Zeile unter dem QR (z. B. „Kamera auf den Code richten“)
footerstring—Kleine Fußzeile, z. B. eine Website oder eine Kurz-URL
showLogobooleantrueZeichnet das Logo des Designs oben auf dem Poster
bleedbooleanfalseFügt 3 mm Beschnitt um das Endformat hinzu; Hintergründe und Balken laufen hinein
cropMarksbooleanfalseZeichnet Schnittmarken außerhalb des Endformats
accentColorstringCTA- oder ModulfarbeMarkenfarbe für Überschrift, Balken und Kartenrahmen; standardmäßig die Farbe des CTA-Rahmens, sonst die Modulfarbe
fileFormatstringpdfpdf (vektoriell, Druck) oder png (Raster, Vorschauen)
dpiinteger150Auflösung eines PNG-Posters, 36–300 dpi (bei PDF ignoriert)
responseTypestringbase64base64 (JSON, wie /api/qr/generate) oder binary (die Datei selbst)

Antwort 200:

{
  "success": true,
  "qrBase64": "JVBERi0xLjQKJcfsj6IK...",
  "format": "pdf",
  "contentType": "application/pdf",
  "sizeBytes": 184320
}

Mit "responseType": "binary" ist die Antwort die Datei selbst (application/pdf oder image/png).

Fehler: 400 Validierung · 401 UNAUTHORIZED · 422 QR_UNSCANNABLE, wenn der Code nicht zurückgelesen werden kann · 422 OUTPUT_TOO_COMPLEX, wenn das PDF 20 MB überschreiten würde · 500 QR_GENERATION_FAILED.


GET /api/ping – Verfügbarkeitsprüfung

Prüft, ob die API erreichbar ist, ohne eine Generierung zu verbrauchen.

Antwort 200:

{
  "status": "ok"
}

Fehler: 429, wenn das Limit pro IP überschritten wird (10 Prüfungen pro Minute).


Fehlerbehandlung

Alle Fehler folgen einem einheitlichen Format:

{
  "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"
      }
    ]
  }
}

Fehlercodes

Validierung (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

Authentifizierung (401) UNAUTHORIZED · INVALID_API_KEY · MISSING_API_KEY

Nicht gefunden (404) RESOURCE_NOT_FOUND · TEMPLATE_NOT_FOUND

KI-/LLM-Fehler (400/500) INVALID_LLM_PROVIDER · INVALID_LLM_MODEL · LLM_API_KEY_INVALID · AI_GENERATION_FAILED · AI_CONFIG_INVALID · AI_REQUEST_TIMEOUT

Ausgabebudget (422) OUTPUT_TOO_COMPLEX — das Design würde ein SVG oder PDF über 20 MB oder eine Leinwand über 5120 px pro Seite erzeugen. Als PNG exportieren, den Inhalt kürzen oder einfachere Modulformen verwenden

Kapazität (503) SERVER_BUSY · AI_QUOTA_EXCEEDED (die verwaltete KI hat bei keinem Anbieter mehr Kontingent; später erneut versuchen)

Serverfehler (500) INTERNAL_ERROR · QR_GENERATION_FAILED · LOGO_LOAD_FAILED · BACKGROUND_LOAD_FAILED