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

  • logo and logo_url together → 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=svg in bulk is impossible — QrBulkRequest.format is Literal["png"] only.
  • data over 4296 chars → 422. That is the practical ceiling of QR version 40 at EC level L; at level H the real cap is nearer 1200 chars.
  • logo_url is 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