Generate Barcode¶
/v1/barcode/generate renders a single 1D barcode from up to 256 characters of data. It exists in two flavours that share the same eight parameters and differ only in how the result comes back:
| Method | Endpoint | Returns |
|---|---|---|
GET |
/v1/barcode/generate |
Raw image bytes (image/png or image/svg+xml) |
POST |
/v1/barcode/generate |
JSON with base64 image or SVG markup |
POST |
/v1/barcode/bulk |
JSON with one base64 PNG per item (up to 20) — see Bulk Generate |
To read a barcode back out of an image, use Decode. For symbology choice and check-digit rules see Symbology Selection & Validation.
Base URL¶
https://barcode.toolkitapi.io
Authentication is via the X-API-Key header (or Authorization: Bearer).
Tip
Use GET when you want bytes you can write straight to disk, pipe into an <img> (server-side) or hand to a file API. Use POST when you want a self-contained JSON payload — e.g. a base64 string you can inline as a data: URI in a browser.
Parameters¶
GET and POST accept the same fields. On GET they are query parameters; on POST they form the JSON body and are all optional except data.
| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
data |
string | yes | — | ≤ 256 chars | The payload to encode |
barcode_type |
string | no | code128 |
one of 11 symbologies (below) | Symbology to encode with |
format |
string | no | png |
png | svg |
Output format |
include_text |
boolean | no | true |
— | Render the human-readable value beneath the bars |
fg_color |
string | no | #000000 |
≤ 9 chars, hex | Bar colour |
bg_color |
string | no | #ffffff |
≤ 9 chars, hex | Background colour |
module_height |
float | no | 15.0 |
5.0 – 50.0 | Bar height in millimetres |
quiet_zone |
float | no | 6.5 |
0.0 – 20.0 | Quiet-zone width in millimetres |
Supported barcode_type values¶
| Value | Symbology | Expected data | Max length |
|---|---|---|---|
code128 |
Code 128 | Any ASCII characters | unbounded |
code39 |
Code 39 | A-Z, 0-9, space, - . $ / + % |
unbounded |
ean13 |
EAN-13 | 12 or 13 digits (checksum auto-calculated) | 13 |
ean8 |
EAN-8 | 7 or 8 digits (checksum auto-calculated) | 8 |
ean14 |
EAN-14 | 13 or 14 digits (checksum auto-calculated) | 14 |
upca |
UPC-A | 11 or 12 digits (checksum auto-calculated) | 12 |
isbn13 |
ISBN-13 | 12 or 13 digits starting 978 / 979 |
13 |
isbn10 |
ISBN-10 | 9 or 10 chars (digits + optional X check) |
10 |
issn |
ISSN | 7 or 8 digits | 8 |
pzn |
PZN (pharma) | 6 or 7 digits | 7 |
itf |
ITF (Interleaved 2 of 5) | Even number of digits | unbounded |
GET /v1/barcode/types returns this same table live from the service, so you can discover constraints at runtime.
Checksums are added for you
Retail symbologies (ean13, ean8, ean14, upca, isbn13, isbn10, issn, pzn) accept the short form without the check digit and append it automatically. Send 13 digits to ean13 and the value is used verbatim (a wrong check digit will fail — validate locally first).
Colour handling¶
fg_color and bg_color are normalised minimally:
- a leading
#is stripped, then re-added, - 3-character shorthand is expanded (
#f00→#ff0000), - the string is passed to the renderer, which parses hex itself.
So #ff0000, ff0000, #f00 and #FF0000 are all red. Named colours (red) fail with 400, and 8-digit RGBA values are accepted by validation but not reliably honoured by the renderers — don't depend on alpha.
GET /v1/barcode/generate¶
Streams the barcode as raw bytes.
Example — PNG to disk¶
curl "https://barcode.toolkitapi.io/v1/barcode/generate?data=5901234123457&barcode_type=ean13&format=png&include_text=true" \
-H "X-API-Key: YOUR_KEY" \
-o barcode.png
Example — SVG markup¶
curl "https://barcode.toolkitapi.io/v1/barcode/generate?data=ABC-123&barcode_type=code128&format=svg&fg_color=%23003366" \
-H "X-API-Key: YOUR_KEY" \
-o barcode.svg
import requests
resp = requests.get(
"https://barcode.toolkitapi.io/v1/barcode/generate",
headers={"X-API-Key": "YOUR_KEY"},
params={
"data": "5901234123457",
"barcode_type": "ean13",
"format": "png",
"include_text": True,
},
timeout=30,
)
resp.raise_for_status()
with open("barcode.png", "wb") as fh:
fh.write(resp.content)
print(resp.headers["content-type"], len(resp.content), "bytes")
const url = new URL("https://barcode.toolkitapi.io/v1/barcode/generate");
url.search = new URLSearchParams({
data: "5901234123457",
barcode_type: "ean13",
format: "png",
include_text: "true",
});
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
if (!resp.ok) throw new Error(`barcode failed: ${resp.status}`);
// Server-side (Node 18+): write bytes to disk
const buf = Buffer.from(await resp.arrayBuffer());
await require("node:fs/promises").writeFile("barcode.png", buf);
Response: 200 with Content-Type: image/png or image/svg+xml and the raw file body. Errors: 400 when the data does not fit the symbology, the colour is unparseable, or rendering fails.
Why <img src> doesn't work from the browser
The API key travels in a header, and <img> cannot send headers. The GET route is meant for server-side fetches, curl -o, and proxies. To embed a barcode in a web page, use the POST route and build a data: URI, or proxy through your backend (the site's demo blueprint does exactly this).
POST /v1/barcode/generate¶
Returns JSON containing the encoded image.
Example — JSON with base64 PNG¶
curl -X POST "https://barcode.toolkitapi.io/v1/barcode/generate" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"data": "5901234123457",
"barcode_type": "ean13",
"format": "png",
"include_text": true,
"fg_color": "#0b3d91",
"module_height": 20.0,
"quiet_zone": 8.0
}'
import base64
import requests
resp = requests.post(
"https://barcode.toolkitapi.io/v1/barcode/generate",
headers={"X-API-Key": "YOUR_KEY", "Content-Type": "application/json"},
json={
"data": "5901234123457",
"barcode_type": "ean13",
"format": "png",
"fg_color": "#0b3d91",
},
timeout=30,
)
resp.raise_for_status()
payload = resp.json()
raw = base64.b64decode(payload["image"])
with open("barcode.png", "wb") as fh:
fh.write(raw)
const resp = await fetch("https://barcode.toolkitapi.io/v1/barcode/generate", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
data: "5901234123457",
barcode_type: "ean13",
format: "png",
}),
});
const { image } = await resp.json();
// Embed straight into the page
const img = document.createElement("img");
img.src = `data:image/png;base64,${image}`;
document.body.append(img);
Response fields¶
| Field | Type | Description |
|---|---|---|
image |
string | null | Base64-encoded PNG (present when format=png) |
svg |
string | null | SVG markup (present when format=svg) |
format |
string | Output format used |
barcode_type |
string | Symbology used |
data |
string | Encoded data, echoed back |
include_text |
boolean | Whether the text label was rendered |
{
"image": "iVBORw0KGgoAAAANSUhEUgAA...",
"svg": null,
"format": "png",
"barcode_type": "ean13",
"data": "5901234123457",
"include_text": true
}
Exactly one of image / svg is populated
Only the field matching format is filled; the other is null. Branch on format rather than probing both.
Choosing module_height and quiet_zone¶
Both are in millimetres, which matters when you print.
module_heightsets bar height.15.0(the default) is roughly a standard retail strip; go to20–30for warehouse shelf labels read at distance.quiet_zoneis the blank margin each side. Scanners need it — shrinking it below ~5 mm causes intermittent read failures at the edges. The default6.5is the retail EAN recommendation.
The rendered width is determined by the symbology and data length, so a long Code 128 with 20 mm bars will be a wide image. Trim your data before shrinking the bars.
Errors¶
| Status | When | Example body |
|---|---|---|
400 |
Data invalid for the symbology, unparseable colour, render failure | {"detail": "Barcode generation failed: ..."} |
401 |
Missing or invalid API key | {"detail": "Unauthorized"} |
422 |
Parameter out of range (e.g. module_height=100, unknown barcode_type) |
Standard FastAPI validation payload |
429 |
Rate limit exceeded | {"detail": "Rate limit exceeded"} |
Related¶
- Bulk Generate — up to 20 barcodes per request, all-or-nothing
- Decode — read barcodes back from an image
- Symbology Selection & Validation
- Barcode Type Reference — live symbology metadata from
/v1/barcode/types - QR Codes — the 2D sibling endpoints