QR Generate

Generate a QR code from any text or URL and return it directly as a raw image. The endpoint supports PNG and SVG output, four error-correction levels, custom foreground/background colours, four module-drawing styles (square, rounded, circle, gapped), and an optional centre logo.

This endpoint previously lived on the devtools toolkit (/v1/qr-generate) and now lives under the barcode service as GET /v1/qr/generate. It returns the image bytes directly — no base64 envelope — so it is directly embeddable via <img src="...">.

Endpoint

GET /v1/qr/generate

Base URL: https://dev.toolkitapi.io

Query Parameters

Parameter Type Required Default Constraints Description
data string Yes — 1–4296 chars Text or URL to encode.
size integer No 400 100–2000 Output image size in pixels (PNG only).
error_correction string No "M" L/M/Q/H QR error-correction level. Forced to H when a logo is embedded.
format string No "png" png/svg Output format.
fg_color string No "#000000" ≤ 9 chars Foreground (module) hex colour. Accepts #rgb, #rrggbb, #rrggbbaa.
bg_color string No "#ffffff" ≤ 9 chars Background hex colour.
module_shape string No "square" square/rounded/circle/gapped Module drawing style (PNG only).
logo_url string No null ≤ 2048 chars Public URL of a logo to embed in the centre (PNG only).
logo_size number No 0.25 0.05–0.40 Logo size as a fraction of the QR image.

data holds up to 4296 characters (the practical QR capacity at EC level L). Longer input is rejected at validation.

Response

  • PNG (format=png, default): Content-Type: image/png with the image bytes.
  • SVG (format=svg): Content-Type: image/svg+xml with an SVG document.

SVG output only honours data, error_correction, fg_color, and bg_color. size, module_shape, and logo_* are PNG-only and are ignored for SVG.

Examples

PNG (default)

curl "https://dev.toolkitapi.io/v1/qr/generate?data=https://example.com&size=400" \
  -H "X-API-Key: YOUR_KEY" --output qr.png
from toolkitapi import Barcode

with Barcode(api_key="YOUR_KEY") as barcode:
    with open("qr.png", "wb") as f:
        f.write(barcode.qr_generate(data="https://example.com", size=400))
const resp = await fetch(
  "https://dev.toolkitapi.io/v1/qr/generate?data=https://example.com&size=400",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const blob = await resp.blob();
const url = URL.createObjectURL(blob); // e.g. <img src={url} />
curl "https://dev.toolkitapi.io/v1/qr/generate?data=https://toolkitapi.io&size=600&module_shape=rounded&fg_color=%230a2540&logo_url=https%3A%2F%2Fexample.com%2Flogo.png&logo_size=0.22" \
  -H "X-API-Key: YOUR_KEY" --output qr-logo.png
Response
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 18944

<binary PNG data>

SVG output

curl "https://dev.toolkitapi.io/v1/qr/generate?data=hello%20world&format=svg&fg_color=%23111111" \
  -H "X-API-Key: YOUR_KEY"
Response (truncated)
<?xml version="1.0" encoding="utf-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="330" height="330" viewBox="0 0 33 33">
  <path fill="#111111" d="M4 4h1v1h-1z ..."/>
</svg>

Error Handling

  • 400 — Invalid input: bad hex colour (e.g. #12), malformed data, or a logo_url that fails SSRF validation / fetch. Body carries a human-readable detail.
  • 400 — Logo too large: logo image exceeds the 5 MB limit.
  • 401 — Missing/invalid API key.
  • 422 — data missing or too long: required, 1–4296 characters.
  • 422 — size out of range: must be 100–2000.
  • 422 — error_correction invalid: must be L, M, Q, or H.
  • 422 — format invalid: must be png or svg.
  • 422 — module_shape invalid: must be square, rounded, circle, or gapped.
  • 422 — logo_size out of range: must be 0.05–0.40.
  • 500 — Generation failure: unexpected error while rendering; detail explains.

Logo SSRF protection

logo_url is validated by the same SSRF guard used elsewhere in the platform: private/internal addresses are rejected before fetch, redirects are followed, and the response is capped at 5 MB. Host your logo on a public URL.

Tips

  • Size is a PNG concern. For SVGs, scale with CSS or the viewer — size is ignored.
  • A logo forces error correction to H. Even if you pass M, embedding a logo upgrades to H (~30% recoverable). Keep logo_size ≤ 0.25 so the QR stays scannable.
  • Contrast wins over aesthetics. Keep a large luminance gap between fg_color and bg_color; low-contrast palettes scan poorly in dim light.
  • Round the data up, not the modules. rounded/circle/gapped styles are decorative; scannability depends primarily on size and contrast.
  • URL-encode data. curl needs %20, %23, etc. for spaces and reserved characters inside query values.
  • Use SVG for crisp print. Vector output stays sharp at any physical size, ideal for packaging and signage.
  • data capacity shrinks as EC rises. At H, fewer characters fit than at L; the 4296-char cap assumes the most permissive level.