Hoppa till innehåll

API-dokumentation

En slutpunkt renderar ZPL till PNG eller PDF. Den är kompatibel med Labelarys v1 API: samma sökvägar, rubriker och fel.

Rendera en etikett

GET  https://api.openzpl.com/v1/printers/{dpmm}/labels/{width}x{height}/{index}/{zpl}
POST https://api.openzpl.com/v1/printers/{dpmm}/labels/{width}x{height}/{index}
POST https://api.openzpl.com/v1/printers/{dpmm}/labels/{width}x{height}/
dpmmSkriv densitet: 6dpmm, 8dpmm, 12dpmm, 24dpmm.
width, heightEtikettstorlek i tum, till exempel 4x6 eller 2.25x1.25. Upp till 15 tum vardera.
indexVilken etikett som ska renderas, med början från 0. Lämna den ur PDF-utdata för att få varje etikett, en per sida.
zplFör GET, den URL-enkodade ZPL. Koda # som %23. Använd POST för allt långt.

Med POST, skicka ZPL som den råa begäran kroppen, eller som en multipart formulärfält namngiven file.

API-nycklar

Utan en nyckel får du de fria gränserna per IP-adress. Med en nyckel från din instrumentpanel, skicka den i X-API-Key-huvudet och begränsningarna för din arbetsytas plan gäller.

curl https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/ \
  -H "X-API-Key: oz_live_…" --data-binary @label.zpl > label.png

Exempel

# PNG from a short ZPL string
curl --get https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/ \
  --data-urlencode "^xa^cfa,50^fo100,100^fdHello World^fs^xz" > label.png

# PDF with every label in a file
curl https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/ \
  -H "Accept: application/pdf" --form file=@labels.zpl > labels.pdf
import requests

zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz"
res = requests.post("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/", data=zpl)
res.raise_for_status()
open("label.png", "wb").write(res.content)
const zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz";
const res = await fetch("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/", {
  method: "POST",
  headers: { Accept: "application/pdf" },
  body: zpl,
});
await require("fs/promises").writeFile("label.pdf", Buffer.from(await res.arrayBuffer()));
$zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz";
$ch = curl_init("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $zpl, CURLOPT_RETURNTRANSFER => true]);
file_put_contents("label.png", curl_exec($ch));

Begärningshuvuden

RubrikVärdenStandard
Acceptimage/png, application/pdfPNG
X-QualityGrayscale (8-bit, släta kanter) eller Bitonal (1-bit, mindre filer)Grayscale
X-Rotation0, 90, 180, 270, medurs0
X-API-KeyDin arbetsytanyckel, valfri—

Gränser

  • Free, no sign-up and no key: 3 requests per second and 5,000 labels per UTC day, per IP address.
  • Labels, not requests, count against the daily allowance: every label rendered, ^PQ copies and PDF pages included. A 10-label PDF is 1 request and 10 labels.
  • Every request: up to 50 labels, a 1 MB body, 15 inches per side, and 10 seconds of render time.
  • Paid plans (Starter $9/month: 10 requests/s and 25,000 labels/day, Pro $29/month: 10 requests/s and 100,000 labels/day, Business $99/month: 20 requests/s and 500,000 labels/day) are announced but billing isn't live yet. API keys work today; a workspace stays on the Free plan until billing opens.
  • Over a limit the API answers 429 with Retry-After (seconds) and a body that names the limit, e.g. ERROR: Daily limit reached: 5000 labels per UTC day on this plan (^PQ copies and PDF pages count).

Svar och fel

Framgångsrika svar bär X-Total-Count, antalet etiketter som ZPL producerar, ^PQ kopior inkluderade. Fel är vanlig text som börjar med ERROR:.

StatusBetydelse
400En parameter är ogiltig, etiketten är för stor, eller indexet ligger utanför intervallet.
401API-nyckeln är okänd eller har återkallats.
406Den Accept rubriken begär ett utdataformat som ännu inte är tillgängligt.
413Kroppen är över 1 MB, eller ZPL:en producerar mer än 50 etiketter.
429För många förfrågningar eller etiketter för din plan. Vänta antalet sekunder i Retry-After.
503Etiketten tog längre tid än 10 sekunder att rendera, eller tjänsten är full. Försök igen, eller sänk densiteten eller storleken.

Vad motorn ritar, ignorerar eller ännu inte stöder finns på the compatibility page; hur snabbt den renderar, mätt på produktionsservern, på the benchmarks page.

OpenAPI och Markdown

Samma avtal publiceras som OpenAPI 3.1 och som Markdown, för kodgeneratorer och kodassistenter.

Steg-för-steg-guider: Python, Node.js, PHP, C#. Flytta från Labelary: migration guide.

Återkoppling