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. |
dataholds up to 4296 characters (the practical QR capacity at EC levelL). Longer input is rejected at validation.
Response¶
- PNG (
format=png, default):Content-Type: image/pngwith the image bytes. - SVG (
format=svg):Content-Type: image/svg+xmlwith an SVG document.
SVG output only honours
data,error_correction,fg_color, andbg_color.size,module_shape, andlogo_*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} />
Styled PNG with a logo¶
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), malformeddata, or alogo_urlthat fails SSRF validation / fetch. Body carries a human-readabledetail.400— Logo too large: logo image exceeds the 5 MB limit.401— Missing/invalid API key.422—datamissing or too long: required, 1–4296 characters.422—sizeout of range: must be 100–2000.422—error_correctioninvalid: must beL,M,Q, orH.422—formatinvalid: must bepngorsvg.422—module_shapeinvalid: must besquare,rounded,circle, orgapped.422—logo_sizeout of range: must be 0.05–0.40.500— Generation failure: unexpected error while rendering;detailexplains.
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 —
sizeis ignored. - A logo forces error correction to
H. Even if you passM, embedding a logo upgrades toH(~30% recoverable). Keeplogo_size≤ 0.25 so the QR stays scannable. - Contrast wins over aesthetics. Keep a large luminance gap between
fg_colorandbg_color; low-contrast palettes scan poorly in dim light. - Round the data up, not the modules.
rounded/circle/gappedstyles are decorative; scannability depends primarily on size and contrast. - URL-encode
data.curlneeds%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.
datacapacity shrinks as EC rises. AtH, fewer characters fit than atL; the 4296-char cap assumes the most permissive level.
Related Endpoints¶
/v1/barcode/generate— generate 1D/2D barcodes/v1/qr/decode— decode QR/barcodes from an image URL/v1/qr/bulk— generate up to 20 QR codes in one request