コンテンツに移動

APIドキュメント

1つのエンドポイントが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出力では省略すると、すべてのラベルが1ページごとに取得されます。
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とMarkdown

同じ契約がOpenAPI 3.1およびMarkdownとして公開されます。コードジェネレーターやコーディングアシスタント用です。

ステップバイステップのガイド：Python、Node.js、PHP、C#。Labelaryからの移行：migration guide。