Developer API · V84

BLB Label Rendering API

Convert ZPL into PNG and PDF, generate barcodes, validate ZPL and turn uploaded logos into ZPL graphics. Built with our own engine, designed for Java, C#, Python, Node.js and other integrations.

Live backend · HTTPS

Public API service

BLB Developer API is deployed over HTTPS on Render. The backend runs independently of the original Wix website, using BLB's own ZPL renderer rather than Labelary. The rendering endpoints require a private API key; never put this credential in public HTML, Git repositories, or browser JavaScript.

Base URL: https://blb-zpl-render-api.onrender.com (health endpoint requires no key)

01 — Render ZPL

Send ZPL and receive PNG, PDF, SVG, structured JSON or original ZPL, using our authenticated endpoint.

02 — Barcodes & graphics

Generate common 1D/2D barcodes or convert uploaded images to uncompressed ^GFA ZPL.

03 — Secure developer access

API key, per-key usage quotas, input limits, local rendering and HTTPS-ready Node.js backend.

Quick start — Labelary-style URLs on your own BLB API

The familiar endpoint format below is implemented by our own server. The endpoint shown below is deployed on Render, connected to our original Wix website for permitted cross-origin browser requests. Supply your private API key in the X-API-Key request header; keep the key on a trusted server for public web applications.

POST https://blb-zpl-render-api.onrender.com/v1/printers/8dpmm/labels/4x6/0/

8dpmm (approximately 203 DPI), 4×6 inches, first label (index 0). The request body contains raw ZPL; no JSON wrapper is required for this endpoint.

curl -X POST 'https://blb-zpl-render-api.onrender.com/v1/printers/8dpmm/labels/4x6/0/' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Accept: image/png' \
  -H 'Content-Type: text/plain' \
  --data-binary '^XA^FO80,80^A0N,48,48^FDHello BLB^FS^XZ' \
  --output label.png

curl -X POST 'https://blb-zpl-render-api.onrender.com/v1/printers/8dpmm/labels/4x6/' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Accept: application/pdf' \
  -H 'Content-Type: text/plain' --data-binary '@labels.zpl' \
  --output all-labels.pdf

Omit the index for a multi-label PDF. Use 6dpmm, 8dpmm, 12dpmm or 24dpmm in the URL, for approximate 152/203/300/600 DPI. The existing JSON API routes remain supported.

Request/response details & advanced rendering headers

`Accept`	image/png, application/pdf, image/svg+xml, application/json, application/zpl
`X-Rotation`	0, 90, 180, 270 degrees (PNG/PDF)
`X-Quality`	Grayscale or thresholded Bitonal (PNG)
`X-Linter`	On; returns BLB warnings via X-Warnings
`X-Formatter`	On when Accept: application/zpl (command formatting)
`X-Page-Size / X-Page-Layout`	A4, A5, A6, Letter, Legal; e.g. 2x3 labels on each PDF page, at actual physical size
`X-Page-Orientation`	Portrait or Landscape
`X-Label-Border`	Solid, Dashed or None

The renderer rejects layouts when labels cannot physically fit the chosen PDF sheet. Advanced source-level ZPL rotation/density conversion and other printer languages are not supported. BLB lint warnings are not identical to Labelary's byte-offset format.

Java, C#, Python and PowerShell examples

Python

import requests
zpl = '^XA^FO50,50^A0N,40,40^FDHello BLB^FS^XZ'
r = requests.post('https://blb-zpl-render-api.onrender.com/v1/printers/8dpmm/labels/4x6/0/',
    data=zpl, headers={'X-API-Key':'YOUR_API_KEY','Accept':'image/png'}, timeout=20)
r.raise_for_status()
open('label.png','wb').write(r.content)

Java 11+

var request = java.net.http.HttpRequest.newBuilder(
    java.net.URI.create("https://blb-zpl-render-api.onrender.com/v1/printers/8dpmm/labels/4x6/0/"))
  .header("X-API-Key", "YOUR_API_KEY")
  .header("Accept", "application/pdf")
  .POST(java.net.http.HttpRequest.BodyPublishers.ofString("^XA^FO40,40^FDHello^FS^XZ"))
  .build();
var response = java.net.http.HttpClient.newHttpClient().send(request,
    java.net.http.HttpResponse.BodyHandlers.ofByteArray());
if (response.statusCode() != 200) throw new RuntimeException("API error " + response.statusCode());
java.nio.file.Files.write(java.nio.file.Path.of("label.pdf"), response.body());

C# (.NET 8)

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post,
  "https://blb-zpl-render-api.onrender.com/v1/printers/8dpmm/labels/4x6/0/");
request.Headers.Add("X-API-Key", "YOUR_API_KEY");
request.Headers.Accept.ParseAdd("application/pdf");
request.Content = new StringContent("^XA^FO40,40^FDHello BLB^FS^XZ");
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync("label.pdf", await response.Content.ReadAsByteArrayAsync());

PowerShell

$zpl = '^XA^FO40,40^FDHello BLB^FS^XZ'
Invoke-WebRequest -Method Post `
 -Uri 'https://blb-zpl-render-api.onrender.com/v1/printers/8dpmm/labels/4x6/0/' `
 -Headers @{ 'X-API-Key' = 'YOUR_API_KEY'; Accept = 'image/png' } `
 -ContentType 'text/plain' -Body $zpl -OutFile 'label.png'

Convert an uploaded PNG/JPEG/WebP to ZPL graphics

curl -X POST 'https://blb-zpl-render-api.onrender.com/v1/graphics' \
 -H 'X-API-Key: YOUR_API_KEY' -F 'file=@logo.png' \
 --output logo.zpl

The V82 graphics endpoint produces monochrome, uncompressed ^GFA. Max image dimensions: 512×512 and packed data 20 KB; oversize images return a validation error.

API limits, security and implementation scope

Default 60 requests/minute and 5,000 requests/day per key, 1 MiB POST body, 24 label blocks, up to 4 million output pixels. Limits are configurable and currently per Node process, not a shared multi-server quota. Every render request requires X-API-Key. Do not embed server API keys in public web pages. User-submitted ZPL is handled on our own server; use POST rather than GET for private labels. This implementation supports a documented subset of ZPL; it does not fully duplicate Labelary, Zebra firmware, Data Matrix/PDF417, EPL/DPL/SBPL/PCL or font conversion.

API endpoints

The original JSON API works alongside the new compact rendering endpoint. Every render endpoint uses X-API-Key authentication.

Method	Path	Response
POST	`/v1/zpl/render`	PNG / SVG / PDF
POST	`/v1/zpl/validate`	JSON warnings
POST	`/v1/barcodes/render`	PNG / SVG / PDF
GET	`/health`	JSON service status

ZPL accepts zpl, widthMm, heightMm, dpi (203/300/600), labelIndex (0-based) and format. PDF output includes all labels in a document; PNG and SVG output the selected label.

Render a ZPL label (cURL)

curl -X POST "https://blb-zpl-render-api.onrender.com/v1/zpl/render" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"zpl":"^XA^FO30,30^A0N,40,40^FDHello BLB^FS^XZ","widthMm":50,"heightMm":30,"dpi":203,"format":"png"}' \
  --output label.png

JavaScript fetch example

const response = await fetch('https://blb-zpl-render-api.onrender.com/v1/zpl/render', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': YOUR_API_KEY },
  body: JSON.stringify({ zpl: '^XA^FO10,10^FDHello^FS^XZ', widthMm: 50,
                         heightMm: 30, dpi: 203, format: 'png' })
});
if (!response.ok) throw Error(await response.text());
const pngBlob = await response.blob();

Python requests example

import requests
response = requests.post('https://blb-zpl-render-api.onrender.com/v1/zpl/render',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'zpl': '^XA^FO10,10^FDHello^FS^XZ',
          'widthMm': 50, 'heightMm': 30, 'dpi': 203, 'format': 'pdf'},
    timeout=15)
response.raise_for_status()
open('label.pdf', 'wb').write(response.content)

Generate a barcode

POST /v1/barcodes/render
{"type":"code128","value":"BLB-12345","format":"svg","width":520,"height":180}

Validate ZPL

POST /v1/zpl/validate
{"zpl":"^XA^FO10,10^A0N,28,28^FDTest^FS^XZ","widthMm":50,"heightMm":30,"dpi":203}

API test console

This console targets the live BLB API. Enter your private API key only when testing; it is not saved by this page. Never share or embed the key in public website code.

Your deployed API URL

API key

Endpoint

JSON body

BLB API host is configured. Paste your private API key and click Send test request.

Security and limits

Every POST requires an API key. The V82 service restricts the total request body to 1 MiB, defaults to 60 requests/minute per key and 5000/day, limits ZPL to 24 labels and limits rendered images to 4 million pixels. The Render service uses HTTPS and permits requests from the original Wix website. Rate limits are in-memory and per-process, not suitable for distributed deployment without a shared store.

This is an incremental ZPL implementation. Unsupported commands generate warnings. Do not assume Zebra firmware-level compatibility without printer tests.

Supported barcode formats

Code 128-B, Code 39, EAN-13, EAN-8, UPC-A, ITF-14 and QR Code. Data Matrix and PDF417 are not yet encoded in this release.

Supported ZPL subset

^XA, ^XZ, ^PW, ^LL, ^FO, ^FT, ^A0, ^CF, ^FD, ^FS, ^BY, ^BC, ^B3, ^BE, ^B8, ^BU, ^BQ, ^GB, ^GC, ^GD, ^LH, ^FH and select others.

Want to design visually?

The existing Smart Label Studio is still available for label design and printing. Try the viewer.