Labelisk API

Render a Paxar PCL label format as a PNG image at print size.

Labelisk interprets the label format language of Paxar SNAP 500 and SNAP 700 printers, delimited by ~XA and ~ZZ. The commands are listed in the command reference. The service returns the label as the printer would produce it, including text, lines, barcodes, resident logos and images embedded in the print job.

The base URL is https://labelisk.com. The API is stateless HTTP; no SDK or session is required.

Authentication

Send your API key in the Authorization header. Create keys on your profile page; each key is shown once.

Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxx

The header X-API-Key: lk_… is also accepted. Requests without a key are served under a reduced daily allowance per IP address, intended for evaluation.

Keep the key on your server. Anyone holding it can spend your quota. Do not ship it inside a web page or a mobile app.

Render a label

POST/v1/render

The request body is the label format itself — plain text, or the raw bytes of a print job that carries PCX images. No JSON wrapper, no multipart.

Query parameters

Name	Default	What it does
`station`	first station	Which station to draw: `F` (front), `B` (back) or a number such as `2`.
`barcode`	`code39`	Symbology used for `~FB` barcode fields: `code39`, `code128`, `ean13`, `ean8`, `upca` or `itf`. See Barcodes.
`output`	`png`	`png` returns the image. `json` returns the image in base64 plus size, dpi and the warnings.

Response

With saida=png the body is the PNG. The size comes from the format: the label is drawn at the resolution declared in ~XD, so a 3 × 1 inch label at 300 dpi comes back as 900 × 300 pixels.

These headers come with every answer:

Header	Example	Meaning
`X-Labelisk-Station`	`F`	Station that was drawn.
`X-Labelisk-Stations`	`F,B`	All stations in this format.
`X-Labelisk-Warnings`	`2`	How many fields have warnings.
`X-Labelisk-Used-Today`	`12`	Renders used today.
`X-Labelisk-Limit-Day`	`200`	Daily allowance of your plan.
`X-Labelisk-Used-Month`	`340`	Renders used this month.
`X-Labelisk-Limit-Month`	`2000`	Monthly allowance of your plan.

Examples

# label as a PNG file
curl -X POST https://labelisk.com/v1/render \
  -H "Authorization: Bearer lk_xxx" \
  --data-binary @label.pcl \
  -o label.png

# back of the label, with the warnings
curl -X POST "https://labelisk.com/v1/render?station=B&saida=json" \
  -H "Authorization: Bearer lk_xxx" \
  --data-binary @label.pcl

The JSON answer looks like this:

{
  "station": "B",
  "stations": ["F", "B"],
  "width": 900,
  "height": 600,
  "dpi": 300,
  "warnings": [
    { "field": 7, "data": "ABC-123", "warnings": ["text is wider than ~AW"] }
  ],
  "png": "iVBORw0KGgoAAAANSUhEUgAA…"
}

Stations

A tag can carry more than one printed face. Fields marked ~FDF belong to the front, ~FDB to the back, and a number selects one of the extra stations. One request draws one station; ask for the others by changing station. The header X-Labelisk-Stations tells you which ones exist, so a first call is enough to discover them.

Warnings

Warnings do not stop the render: the label is drawn and the problems are reported alongside it.

text is wider than ~AW — the text overflows the width the field declares.
outside the label — part of the field falls off the tag.
data has N characters; the field takes M — the printer would cut the text.
no logo with that number — the ~FG field points to a logo that is not in your account.

Barcodes

Barcode fields (~FB) are drawn with the symbology you choose in the barcode parameter, or in the selector above the label in the viewer. Supported: Code 39 (default), Code 128, EAN-13, EAN-8, UPC-A and ITF. Check digits are calculated when the data is one digit short, and a mismatch is reported as a warning instead of drawing wrong bars.

Which symbology the printer uses is not detected yet. The command parameter that selects it has not been identified, so the choice is yours. If you have a real format with a barcode and a photo of the printed tag, send them over: that is what it takes to make the detection automatic.

Your logos and fonts

Upload BMP logos and TTF/OTF fonts on your profile. They are used automatically on every render made with your key, the same way the printer uses what is stored in its memory.

Logos: ~FG finds a logo by the number at the end of the file name, so LOGO00015.BMP answers the data 015.
Fonts: ~AL5 uses the file named FNT00005.TTF.

Without your own files, the render falls back to free lookalike fonts, and missing logos are drawn as a dashed box.

Plans and limits

Plan	Per day	Per month	Logos / fonts
No account	20	200	—
Free	200	2,000	30 / 10
Pro · US$ 19/month	5,000	20,000	1,000 / 200

Counters reset at midnight UTC and on the 1st of each month. For volumes above the Pro plan, write to support for a dedicated plan.

Errors

Every error comes back as JSON with a single erro field describing what happened.

Code	When
`400`	Empty body, or nothing that looks like a label format.
`401`	Invalid or revoked key.
`422`	The format was read but could not be drawn — for example a station that does not exist.
`429`	Daily or monthly allowance reached.
`503`	The renderer is restarting. Wait a few seconds and try again.

JavaScript

One file, no dependencies, works in Node 18+ and in Deno and Bun.

import { Labelisk } from './labelisk.js';

const labelisk = new Labelisk({ key: process.env.LABELISK_KEY });

const png = await labelisk.render(format);           // Uint8Array
await labelisk.renderToFile(format, 'label.png');    // writes the file

const r = await labelisk.renderJson(format, { station: 'B' });
console.log(r.stations, r.warnings);

Python

Standard library only, Python 3.9+.

from labelisk import Labelisk

labelisk = Labelisk(key="lk_xxx")

png = labelisk.render(fmt)                     # bytes
labelisk.render_to_file(fmt, "label.png")

r = labelisk.render_json(fmt, station="B")
print(r["stations"], r["warnings"])

Both libraries consist of a single file with no dependencies, available in the sdk/ folder of the project.