QR Code Generation¶
Three endpoints under /v1/qr cover everything from a single styled QR to 20 in one call to a straight image stream. All of them require an API key — the raw-image variants included, unlike the catch-style public endpoints elsewhere in the platform.
For 1D symbologies (Code128, EAN, UPC) use /v1/barcode. For picking a symbology, see Symbology Selection.
Base URL¶
https://barcode.toolkitapi.io
Endpoints¶
| Method | Endpoint | Returns |
|---|---|---|
POST |
/v1/qr/generate |
JSON with base64 PNG or SVG markup |
GET |
/v1/qr/generate |
Raw image bytes (image/png or image/svg+xml) |
POST |
/v1/qr/bulk |
JSON array of up to 20 base64 PNGs |
POST |
/v1/qr/decode |
Decoded payloads from a base64 image |
GET |
/v1/qr/decode |
Decoded payloads from an image URL |
Authentication is via the X-API-Key header (or Authorization: Bearer).
Tip
Use GET /v1/qr/generate when you want to drop the QR straight into an <img src> or a PDF/HTML pipeline without a base64 round-trip. Use POST when you need the JSON fields (or SVG markup as text).
Parameters¶
Identical across POST /v1/qr/generate and each item in POST /v1/qr/bulk (bulk omits the logo fields):
| Parameter | Type | Default | Constraints |
|---|---|---|---|
data |
string | — | Required. 1–4296 chars |
size |
integer | 400 |
100–2000 px (square) |
error_correction |
enum | M |
L (7%), M (15%), Q (25%), H (30%) |
format |
enum | png |
png or svg |
fg_color |
string | #000000 |
Hex, up to 9 chars (#RRGGBB or #RRGGBBAA) |
bg_color |
string | #ffffff |
Hex, up to 9 chars |
module_shape |
enum | square |
square, rounded, circle, gapped |
logo |
string | null |
Base64 image, max 5 MB — POST only |
logo_url |
string | null |
URL to a logo image, max 2048 chars — POST only |
logo_size |
float | 0.25 |
0.05–0.40, fraction of QR width |
Validation rules that actually reject requests¶
logoandlogo_urltogether →422(Provide either 'logo' (base64) or 'logo_url', not both).- Any logo with
format=svg→422(Logo embedding is only supported with PNG output). format=svgin bulk is impossible —QrBulkRequest.formatisLiteral["png"]only.dataover 4296 chars →422. That is the practical ceiling of QR version 40 at EC level L; at levelHthe real cap is nearer 1200 chars.logo_urlis fetched server-side. Private/internal targets are refused by the SSRF guard.
Choosing an error-correction level¶
| Level | Recovery | Use when |
|---|---|---|
L |
7% | Maximum data density, clean digital display |
M |
15% | Default — good balance |
Q |
25% | Print, expected smudges |
H |
30% | Required in practice for logos — the logo occludes modules |
If you embed a logo at logo_size=0.25, use H, or scan reliability drops noticeably at small print sizes.
POST /v1/qr/generate¶
curl -X POST "https://barcode.toolkitapi.io/v1/qr/generate" \
-H "X-API-Key: $BARCODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"data": "https://toolkitapi.io/pricing?utm_source=poster",
"size": 800,
"error_correction": "H",
"format": "png",
"fg_color": "#101828",
"bg_color": "#ffffff",
"module_shape": "rounded",
"logo_url": "https://toolkitapi.io/logo.png",
"logo_size": 0.22
}'
{
"image": "iVBORw0KGgoAAAANSUhEUgAA...",
"svg": null,
"format": "png",
"data": "https://toolkitapi.io/pricing?utm_source=poster",
"size": 800,
"error_correction": "H",
"module_shape": "rounded",
"has_logo": true
}
Response fields:
| Field | Type | Notes |
|---|---|---|
image |
string | null | Base64 PNG (no data-URI prefix); null when format=svg |
svg |
string | null | SVG markup; null when format=png |
format |
string | Format actually used |
data |
string | Echo of the encoded payload |
size |
integer | Pixel size requested |
error_correction |
string | Level used |
module_shape |
string | Shape used |
has_logo |
boolean | Whether a logo was embedded |
import base64, httpx
resp = httpx.post(
"https://barcode.toolkitapi.io/v1/qr/generate",
headers={"X-API-Key": BARCODE_API_KEY},
json={
"data": "https://toolkitapi.io/pricing?utm_source=poster",
"size": 800,
"error_correction": "H",
"module_shape": "rounded",
"logo_url": "https://toolkitapi.io/logo.png",
"logo_size": 0.22,
},
timeout=30,
)
resp.raise_for_status()
body = resp.json()
with open("qr.png", "wb") as fh:
fh.write(base64.b64decode(body["image"]))
print(body["size"], body["has_logo"])
const res = await fetch("https://barcode.toolkitapi.io/v1/qr/generate", {
method: "POST",
headers: { "X-API-Key": process.env.BARCODE_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
data: "https://toolkitapi.io/pricing?utm_source=poster",
size: 800,
error_correction: "H",
module_shape: "rounded",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const body = await res.json();
// Browser: render straight into an <img>
const img = document.querySelector("#qr");
img.src = `data:image/png;base64,${body.image}`;
// Node: write to disk
// await writeFile("qr.png", Buffer.from(body.image, "base64"));
SVG output¶
Set format: "svg" and read body.svg — vector output for print, infinitely scalable, no logo support:
curl -s -X POST "https://barcode.toolkitapi.io/v1/qr/generate" \
-H "X-API-Key: $BARCODE_API_KEY" -H "Content-Type: application/json" \
-d '{"data":"https://toolkitapi.io","format":"svg","module_shape":"circle","fg_color":"#1d4ed8"}' \
| jq -r '.svg' > qr.svg
GET /v1/qr/generate¶
Same parameters as query strings, but the response is the image — no JSON envelope, no base64. Ideal for <img src> and email templates.
curl "https://barcode.toolkitapi.io/v1/qr/generate?data=https%3A%2F%2Ftoolkitapi.io&size=600&module_shape=circle&fg_color=%231d4ed8" \
-H "X-API-Key: $BARCODE_API_KEY" \
-o qr.png
img = httpx.get(
"https://barcode.toolkitapi.io/v1/qr/generate",
headers={"X-API-Key": BARCODE_API_KEY},
params={"data": "https://toolkitapi.io", "size": 600, "module_shape": "circle"},
timeout=30,
)
img.raise_for_status()
open("qr.png", "wb").write(img.content)
print(img.headers["content-type"]) # image/png
const u = new URL("https://barcode.toolkitapi.io/v1/qr/generate");
u.searchParams.set("data", "https://toolkitapi.io");
u.searchParams.set("size", "600");
const res = await fetch(u, { headers: { "X-API-Key": process.env.BARCODE_API_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
await writeFile("qr.png", Buffer.from(await res.arrayBuffer()));
Warning
The API key travels in a header, so you cannot use this endpoint directly as an <img src> in a public page — the browser won't attach your key, and putting it in the URL is not supported. Proxy it server-side (or use the POST variant and inline the base64).
POST /v1/qr/bulk¶
Up to 20 QR codes, PNG only, no logos.
curl -X POST "https://barcode.toolkitapi.io/v1/qr/bulk" \
-H "X-API-Key: $BARCODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"data": "https://example.com/table/1", "size": 300, "module_shape": "square"},
{"data": "https://example.com/table/2", "size": 300, "module_shape": "square"}
]
}'
{
"total": 2,
"format": "png",
"results": [
{"data": "https://example.com/table/1", "image": "iVBORw0...", "size": 300, "error_correction": "M", "module_shape": "square"},
{"data": "https://example.com/table/2", "image": "iVBORw0...", "size": 300, "error_correction": "M", "module_shape": "square"}
]
}
items = [{"data": f"https://example.com/table/{n}", "size": 300} for n in range(1, 21)]
r = httpx.post(
"https://barcode.toolkitapi.io/v1/qr/bulk",
headers={"X-API-Key": BARCODE_API_KEY},
json={"items": items},
timeout=60,
)
r.raise_for_status()
for n, item in enumerate(r.json()["results"], start=1):
with open(f"table-{n}.png", "wb") as fh:
fh.write(base64.b64decode(item["image"]))
Note
Bulk is not partial-success: one failed item aborts the whole call with 400 and a message naming the offending payload. Validate data lengths locally before sending (≤ 4296, and much lower at EC level H) rather than retrying blind.
Errors¶
| Status | Meaning |
|---|---|
400 |
Generation failed (e.g. data too long for the chosen EC level, unreadable logo) |
401 |
Missing or invalid API key |
422 |
Schema violation — missing data, size out of range, logo + logo_url together, logo with format=svg |
500 |
Unexpected generator failure; retry, then reduce size |
Related¶
- Barcodes — 1D generation, decode, types
- Barcode Types Reference — symbology constraints
- Bulk & Decode — batching strategies and decoding pipelines