내용으로 건너뛰기

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 출력 시 생략하면 모든 라벨을 페이지마다 하나씩 가져옵니다.
zplGET의 경우, 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본문이 1MB를 초과하거나 ZPL이 50개 이상의 레이블을 생성합니다.
429계획에 대한 요청이나 레이블이 너무 많습니다. Retry-After에 명시된 초를 기다리세요.
503레이블이 렌더링하는 데 10초 이상 걸리거나 서비스 용량이 초과되었습니다. 다시 시도하거나 밀도 또는 크기를 줄이세요.

OpenAPI 및 마크다운

같은 계약이 코드 생성기 및 코딩 도우미를 위한 OpenAPI 3.1 및 Markdown로 발행됩니다.

단계별 가이드: Python, Node.js, PHP, C#. Labelary에서 이동: migration guide.