Bulk Barcode & QR Generation¶
The bulk endpoints generate many symbols in one round trip - ideal for label sheets, product catalogues, and print runs. Decoding works from any publicly reachable image URL.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/v1/barcode/bulk |
Generate up to 20 barcodes (PNG) |
POST |
/v1/qr/bulk |
Generate up to 20 QR codes (PNG) |
GET |
/v1/barcode/decode |
Decode barcode(s) from an image URL |
GET |
/v1/qr/decode |
Decode QR code(s) from an image URL |
GET |
/v1/barcode/types |
List supported 1D symbologies and their constraints |
Base URL¶
https://barcode.toolkitapi.io
All endpoints require an X-API-Key header.
1. Bulk barcodes¶
curl -X POST "https://barcode.toolkitapi.io/v1/barcode/bulk" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"data": "ABC-10023", "barcode_type": "code128"},
{"data": "400638133393", "barcode_type": "ean13", "include_text": true},
{"data": "SKU-77", "barcode_type": "code39", "fg_color": "#0b3d91"}
],
"format": "png"
}'
import base64
import pathlib
import requests
payload = {
"items": [
{"data": "ABC-10023", "barcode_type": "code128"},
{"data": "400638133393", "barcode_type": "ean13"},
]
}
resp = requests.post(
"https://barcode.toolkitapi.io/v1/barcode/bulk",
headers={"X-API-Key": "YOUR_KEY"},
json=payload,
timeout=60,
)
resp.raise_for_status()
data = resp.json()
for idx, item in enumerate(data["results"]):
pathlib.Path(f"label-{idx}.png").write_bytes(base64.b64decode(item["image"]))
print(item["barcode_type"], item["data"])
const resp = await fetch("https://barcode.toolkitapi.io/v1/barcode/bulk", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
items: [{ data: "ABC-10023", barcode_type: "code128" }],
format: "png",
}),
});
const { total, results } = await resp.json();
// Each result.image is a base64 PNG - drop straight into an <img> tag:
// `<img src="data:image/png;base64,${results[0].image}">`
Request¶
| Field | Type | Default | Description |
|---|---|---|---|
items |
object[] | required | 1-20 barcodes to generate |
items[].data |
string | required | Data to encode (max 256 chars) |
items[].barcode_type |
string | code128 |
See supported types |
items[].include_text |
boolean | true |
Print human-readable text under the bars |
items[].fg_color |
string | #000000 |
Bar colour (hex) |
items[].bg_color |
string | #ffffff |
Background colour (hex) |
format |
string | png |
PNG only for bulk |
module_height and quiet_zone are fixed at 15.0mm and 6.5mm in bulk mode. Use POST /v1/barcode/generate (single) if you need to tune them.
Response¶
{
"total": 2,
"format": "png",
"results": [
{"data": "ABC-10023", "image": "iVBORw0KGgoAAAANSUhEUg...", "barcode_type": "code128"},
{"data": "400638133393", "image": "iVBORw0KGgoAAAANSUhEUg...", "barcode_type": "ean13"}
]
}
Bulk generation is all-or-nothing: a single invalid item fails the whole request with 400 naming the offending data, so pre-validate retail symbologies (EAN-13 needs 12 or 13 digits, and the checksum is computed for you).
2. Bulk QR codes¶
curl -X POST "https://barcode.toolkitapi.io/v1/qr/bulk" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"data": "https://toolkitapi.io/docs", "size": 600, "error_correction": "H"},
{"data": "WIFI:T:WPA;S:guest;P:hunter2;;", "size": 400, "module_shape": "rounded"}
],
"format": "png"
}'
import requests
resp = requests.post(
"https://barcode.toolkitapi.io/v1/qr/bulk",
headers={"X-API-Key": "YOUR_KEY"},
json={
"items": [
{"data": "https://toolkitapi.io", "size": 600, "error_correction": "H"},
{"data": "https://toolkitapi.io/docs", "size": 400, "module_shape": "circle"},
]
},
timeout=60,
)
for row in resp.json()["results"]:
print(row["size"], row["error_correction"], row["module_shape"])
const resp = await fetch("https://barcode.toolkitapi.io/v1/qr/bulk", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
items: [{ data: "https://toolkitapi.io", size: 500, error_correction: "Q" }],
}),
});
const data = await resp.json();
Request¶
| Field | Type | Default | Constraints | Description |
|---|---|---|---|---|
items |
object[] | required | 1-20 | QR codes to generate |
items[].data |
string | required | 1-4296 chars | Text, URL, or structured payload |
items[].size |
integer | 400 |
100-2000 | Square image size in pixels |
items[].error_correction |
string | M |
L, M, Q, H |
7% / 15% / 25% / 30% recovery |
items[].fg_color |
string | #000000 |
hex | Module colour |
items[].bg_color |
string | #ffffff |
hex | Background colour |
items[].module_shape |
string | square |
square, rounded, circle, gapped |
Module rendering style |
format |
string | png |
PNG only | Output format |
Logo embedding is available on the single-shot POST /v1/qr/generate endpoint, not in bulk mode.
Response¶
{
"total": 1,
"format": "png",
"results": [
{
"data": "https://toolkitapi.io",
"image": "iVBORw0KGgoAAAANSUhEUg...",
"size": 500,
"error_correction": "Q",
"module_shape": "square"
}
]
}
3. Decode from a URL¶
curl "https://barcode.toolkitapi.io/v1/qr/decode?url=https://toolkitapi.io/static/samples/qr.png" \
-H "X-API-Key: YOUR_KEY"
import requests
resp = requests.get(
"https://barcode.toolkitapi.io/v1/barcode/decode",
headers={"X-API-Key": "YOUR_KEY"},
params={"url": "https://toolkitapi.io/static/samples/barcode.png"},
timeout=30,
)
for item in resp.json()["results"]:
print(item["type"], item["data"])
const params = new URLSearchParams({ url: "https://toolkitapi.io/static/samples/qr.png" });
const resp = await fetch(`https://barcode.toolkitapi.io/v1/qr/decode?${params}`, {
headers: { "X-API-Key": "YOUR_KEY" },
});
const { found, results } = await resp.json();
Both decoders accept ?url= (max 2048 chars) and scan for any symbol in the image - including symbols from the other family. GET /v1/barcode/decode and GET /v1/qr/decode share the same detection service, so a QR code submitted to the barcode endpoint still decodes.
Response¶
{
"found": 1,
"results": [
{
"data": "https://toolkitapi.io",
"type": "QRCODE",
"quality": "1",
"position": {"x": 32, "y": 32, "width": 256, "height": 256}
}
]
}
| Field | Description |
|---|---|
found |
Number of symbols detected |
results[].data |
Decoded payload |
results[].type |
Symbol type, e.g. QRCODE, CODE128, EAN13 |
results[].quality |
Decoder confidence indicator |
results[].position |
Bounding polygon of the symbol in the image |
4. List supported symbologies¶
curl "https://barcode.toolkitapi.io/v1/barcode/types" -H "X-API-Key: YOUR_KEY"
{
"total": 11,
"types": [
{
"name": "code128",
"description": "Code 128 - high-density alphanumeric barcode",
"data_format": "Any ASCII characters",
"max_length": null
}
]
}
Supported 1D symbologies¶
| Type | Data format | Max length |
|---|---|---|
code128 |
Any ASCII | - |
code39 |
A-Z, 0-9, space, -.$/+% |
- |
ean13 |
12 or 13 digits (checksum auto) | 13 |
ean8 |
7 or 8 digits (checksum auto) | 8 |
ean14 |
13 or 14 digits (checksum auto) | 14 |
upca |
11 or 12 digits (checksum auto) | 12 |
isbn13 |
12 or 13 digits | 13 |
isbn10 |
9 or 10 characters | 10 |
issn |
7 or 8 digits | 8 |
pzn |
6 or 7 digits | 7 |
itf |
Even number of digits | - |
Errors¶
| Status | Meaning |
|---|---|
400 |
Invalid data for the symbology (bad length, non-numeric EAN, unencodable characters), or a decode URL that cannot be fetched |
401 |
Missing or invalid X-API-Key |
422 |
Schema validation failure - more than 20 items, size out of range, unknown module_shape |
Related¶
- Barcodes - single barcode generation with full styling control
- QR Codes - single QR generation with logo embedding
- Rate Limits - bulk endpoints consume one request per call, not per item