跳到内容

API 文档

一个端点将 ZPL 渲染为 PNG 或 PDF。它与 Labelary 的 v1 API 兼容：相同的路径、头信息和错误。

渲染标签

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}/
dpmm打印密度: 6dpmm, 8dpmm, 12dpmm, 24dpmm。
width, height标签大小，以英寸为单位，例如 4x6 或 2.25x1.25。每个标签最大 15 英寸。
index要渲染哪个标签，从 0 开始。如果使用 PDF 输出，省略此项以获取每个标签，每页一个。
zpl对于 GET，URL 编码的 ZPL。将 # 编码为 %23。对于任何长内容使用 POST。

使用 POST，将 ZPL 作为原始请求体发送，或作为名为 file 的多部分表单字段发送。

API 密钥

没有密钥时，根据 IP 地址获得免费限制。使用来自仪表板的密钥，将其发送在 X-API-Key 头中，适用您工作区计划的限制。

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

示例

# 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));

请求头

页眉值默认
Acceptimage/png, application/pdfPNG
X-QualityGrayscale (8位，平滑边缘) 或 Bitonal (1位，更小文件)Grayscale
X-Rotation0, 90, 180, 270，顺时针0
X-API-Key您的工作区密钥，选填—

限制

  • 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).

响应和错误

成功的响应携带 X-Total-Count，ZPL 生成的标签数量，包括 ^PQ 份。错误为以 ERROR: 开头的纯文本。

状态含义
400参数无效，标签太大或索引超出范围。
401API 密钥未知或已被撤销。
406Accept 头部请求尚不可用的输出格式。
413主体超过 1 MB，或 ZPL 生成超过 50 个标签。
429对于您的计划，请求或标签过多。请等待 Retry-After 中的秒数。
503标签生成超过 10 秒，或服务已达到容量。重试，或降低密度或大小。

引擎绘制、忽略或尚未支持的内容在the compatibility page上；它渲染的速度在生产服务器上测量，在the benchmarks page上。

OpenAPI和Markdown

相同的合同以OpenAPI 3.1和Markdown发布，供代码生成器和编码助手使用。

逐步指南：Python，Node.js，PHP，C#。从Labelary迁移：migration guide。

反馈