POST /api/v1/generate/

Render a QR code and return its PNG or SVG bytes.

Endpoint

POST /api/v1/generate/
Host: api.qrstudio.agency
X-Api-Key: smk_...
Content-Type: application/json

For logo or background-image uploads, use multipart instead:

POST /api/v1/generate/
Host: api.qrstudio.agency
X-Api-Key: smk_...
Content-Type: multipart/form-data

Body parameters

Payload (what to encode)

For url and text, just pass data. For all others, build a payload object. See Data types.

Output format and dimensions

Pixel size = size_inches x dpi. So 4 inches at 300 DPI = 1 200 x 1 200 px.

Style

Eye styling

Frame

Logo (optional, Starter+ only)

You can supply either logo_file or logo_url, not both. Custom logos require Starter plan or higher.

Background image (optional, Starter+ only)

Caption (optional)

A human-readable identifier rendered as a centered text band BELOW the QR matrix. Sits outside the QR's quiet zone, so scannability is unaffected. Use case: print shops generating sticker batches need to match each printed QR to its order without scanning - the caption ("USER-2401", "SKU-A14", "ORDER-9821") sits visibly under the QR.

The text scales with the QR's printed width, so a 1" sticker, a 3" flyer, and a 15" poster all get a caption that occupies the same visual fraction of the printed image (~9% with the default 0.05). Adjust caption_size_ratio for the look you want:

The output PNG is no longer a perfect square when caption is set: the height grows to fit the text band. The width still matches size_inches * dpi.

{
  "data": "https://app.example.com/u/2401",
  "caption": "USER-2401",
  "caption_size_ratio": 0.05,
  "size_inches": 3,
  "dpi": 300,
  "color": "black",
  "background": "white"
}

Pair with pattern: "halftone" for the photo-revealed-through-dots effect.

Response

Success: 200 OK

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 59143
X-QR-Cache: MISS
X-QR-Duration-Ms: 318
X-QR-Plan: starter
X-QR-Quota-Remaining: 487
X-Request-Id: 01HZ8X...

<binary PNG bytes>

The body is the raw image. Save it directly, stream it, or pipe to S3.

For dynamic items (data_type: "dynamic") the response also adds:

X-QR-Dynamic-Short-Id: aBc12dEf
X-QR-Dynamic-Public-Url: https://q.qrstudio.agency/q/aBc12dEf/

400 Bad Request

Validation failure. Body is JSON describing the bad fields:

{
  "size_inches": ["Ensure this value is less than or equal to 15."],
  "logo_url": "refusing to fetch evil.com: resolves to private/internal IP 10.0.0.5"
}

401 Unauthorized

Missing or invalid X-Api-Key.

{ "detail": "Invalid or revoked API key." }

403 Forbidden

Your plan does not allow what you asked for.

{ "detail": "Plan 'free' allows up to 3\". Upgrade for larger sizes." }

429 Too Many Requests

Monthly quota exhausted (Free / Enterprise) or rate limit exceeded.

{ "detail": "Monthly quota of 5 exceeded for plan 'free'." }

500 Internal Server Error

Render engine failed. Rare, retry once with backoff. If it persists, include X-Request-Id in your support ticket.

Validate

Same body schema as /generate/, but it only validates and returns the parsed payload. No image is rendered, no quota is spent.

POST /api/v1/validate/
X-Api-Key: smk_...
Content-Type: application/json

{
  "data": "https://example.com",
  "size_inches": 4,
  "color": "rouge"
}

Response (validation failure):

{
  "color": "Invalid color 'rouge'. Use 'black', 'white', or hex like #RRGGBB / #RRGGBBAA."
}

Useful for client-side form validation before charging quota.

Examples

curl -X POST https://api.qrstudio.agency/api/v1/generate/ \
  -H "X-Api-Key: smk_..." \
  -H "Content-Type: application/json" \
  -d '{"data": "https://example.com", "size_inches": 4}' \
  --output qr.png

{
  "data": "https://yourbrand.com",
  "size_inches": 8,
  "color": "white",
  "background": "transparent",
  "pattern": "rounded",
  "logo_url": "https://cdn.yourbrand.com/logo.png",
  "logo_neon_alpha": true,
  "logo_clear_zone": true,
  "format": "png"
}

{
  "data_type": "wifi",
  "payload": {
    "ssid": "Cafe Plein Soleil",
    "password": "BienvenueChezNous2026",
    "auth": "WPA"
  },
  "size_inches": 8,
  "color": "#0d0820",
  "background": "white",
  "format": "svg"
}

{
  "data_type": "vcard",
  "payload": {
    "name": "Alex Tremblay",
    "org": "Acme Co",
    "phone": "+15145551234",
    "email": "alex@yourcompany.com",
    "url": "https://yourcompany.com"
  },
  "size_inches": 2,
  "color": "black"
}

{
  "data_type": "dynamic",
  "payload": {
    "name": "Spring 2026 menu",
    "destination_url": "https://example.com/menus/spring-2026"
  },
  "size_inches": 6
}

{
  "data": "https://yourbrand.com",
  "size_inches": 6,
  "background": "white",
  "pattern": "rounded",
  "gradient_from": "#6c48e8",
  "gradient_to": "#1a0d3a",
  "eye_color": "#1a0d3a",
  "frame_style": "scan-me-bottom",
  "frame_color": "#6c48e8",
  "frame_label": "Scan to view menu"
}

{
  "data": "https://yourbrand.com",
  "size_inches": 6,
  "background": "white",
  "color": "#0d0820",
  "pattern": "halftone",
  "bg_image_url": "https://cdn.yourbrand.com/coffee.jpg",
  "bg_image_opacity": 0.45
}

Notes

• All requests must use HTTPS in production. HTTP is allowed only on localhost.
• Maximum request body: 5 MB (covers logo and background uploads).
• The data string is encoded as UTF-8 before being passed to the QR generator.
• ERROR_CORRECT_H is hardcoded and not tunable. This gives you a 30% obstruction tolerance, which the logo never exceeds.

See also

• Data types
• Styling
• Logos
• Bulk endpoint
• Errors