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:

  1. a leading # is stripped, then re-added,
  2. 3-character shorthand is expanded (#f00 → #ff0000),
  3. 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_height sets bar height. 15.0 (the default) is roughly a standard retail strip; go to 20–30 for warehouse shelf labels read at distance.
  • quiet_zone is the blank margin each side. Scanners need it — shrinking it below ~5 mm causes intermittent read failures at the edges. The default 6.5 is 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"}