Conversions

Synchronous conversion endpoints. Request body is raw binary (PDF or ZPL text), not JSON.

Contents: PDF to ZPL · ZPL to PDF · Common Parameters · Estimate Cost

POST /v1/convert/pdf-to-zpl

Idempotent: yes (requires Idempotency-Key header)
Content-Type: application/pdf
Max body size: 5 MB

Query Parameters

Pricing (per page)

PDF→ZPL uses flat cost-based pricing: the same token cost regardless of output quality (maxKB).
You choose the quality you need without worrying about token budget.

Note: maxKB still affects output size budget. The allow_degrade parameter controls whether the system reduces quality to fit the budget.

Response

{
  "request_id": "sync:pdf2zpl:abc123",
  "pages": [
    {
      "index": 0,
      "zpl_base64": "XlpB..."
    }
  ],
  "tokens_charged": 2,
  "over_budget_tokens": 0
}

Example

curl -X POST "https://api.zplflow/v1/convert/pdf-to-zpl?dpi=203&max_kb=64" \
  -H "Authorization: Bearer lb_live_xxxx" \
  -H "Content-Type: application/pdf" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @label.pdf

import requests

with open("label.pdf", "rb") as f:
    resp = requests.post(
        "https://api.zplflow/v1/convert/pdf-to-zpl?dpi=203&max_kb=64",
        headers={
            "Authorization": "Bearer lb_live_xxxx",
            "Content-Type": "application/pdf",
            "Idempotency-Key": "pdf-conv-001",
        },
        data=f
    )
data = resp.json()
for page in data["pages"]:
    print(f"Page {page['index']}: {page['zpl_base64'][:40]}...")

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    pdf, _ := os.ReadFile("label.pdf")
    req, _ := http.NewRequest("POST",
        "https://api.zplflow/v1/convert/pdf-to-zpl?dpi=203&max_kb=64",
        io.NopCloser(bytes.NewReader(pdf)))
    req.Header.Set("Authorization", "Bearer lb_live_xxxx")
    req.Header.Set("Content-Type", "application/pdf")
    req.Header.Set("Idempotency-Key", "pdf-conv-001")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var data struct {
        Pages []struct {
            Index     int    `json:"index"`
            ZPLBase64 string `json:"zpl_base64"`
        } `json:"pages"`
    }
    json.NewDecoder(resp.Body).Decode(&data)
    for _, p := range data.Pages {
        fmt.Printf("Page %d: %s...\n", p.Index, p.ZPLBase64[:40])
    }
}

<?php
$pdf = file_get_contents("label.pdf");
$ch = curl_init("https://api.zplflow/v1/convert/pdf-to-zpl?dpi=203&max_kb=64");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $pdf);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer lb_live_xxxx",
    "Content-Type: application/pdf",
    "Idempotency-Key: pdf-conv-001"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
foreach ($data['pages'] as $page) {
    echo "Page {$page['index']}: " . substr($page['zpl_base64'], 0, 40) . "...\n";
}

AS400 / SQL Native (IBM i)

SELECT SYSTOOLS.HTTPPOSTCLOB(
    'https://api.zplflow/v1/convert/pdf-to-zpl?dpi=203&max_kb=64',
    SYSTOOLS.IFS_READ('/tmp/label.pdf'),
    '{"Authorization":"Bearer lb_live_xxxx","Content-Type":"application/pdf","Idempotency-Key":"pdf-conv-001"}'
) AS response
FROM SYSIBM.SYSDUMMY1;

AS400 / HTTPAPI (RPG)

dcl-s response varchar(65000);
dcl-s rc int(10);

rc = http_put_raw(
    'https://api.zplflow/v1/convert/pdf-to-zpl?dpi=203&max_kb=64'
    : '/tmp/label.pdf'
    : 'application/pdf'
    : %trim(response)
    : 'Authorization: Bearer lb_live_xxxx'
    : 'Idempotency-Key: pdf-conv-001'
    : 30000);

POST /v1/convert/zpl-to-pdf

Idempotent: yes (requires Idempotency-Key header)
Content-Type: text/plain
Max body size: 512 KB
Cost: 1 token (fixed)

Query Parameters

Response

{
  "request_id": "sync:zpl2pdf:abc123",
  "pages": [
    {
      "index": 0,
      "pdf_base64": "JVBERi0..."
    }
  ],
  "tokens_charged": 1,
  "over_budget_tokens": 0
}

Example

curl -X POST "https://api.zplflow/v1/convert/zpl-to-pdf" \
  -H "Authorization: Bearer lb_live_xxxx" \
  -H "Content-Type: text/plain" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary '^XA^FO50,50^A0N,30,30^FDHello World^FS^XZ'

import base64
import requests

zpl = "^XA^FO50,50^A0N,30,30^FDHello World^FS^XZ"
resp = requests.post(
    "https://api.zplflow/v1/convert/zpl-to-pdf",
    headers={
        "Authorization": "Bearer lb_live_xxxx",
        "Content-Type": "text/plain",
        "Idempotency-Key": "zpl-conv-001",
    },
    data=zpl
)
data = resp.json()
pdf = base64.b64decode(data["pages"][0]["pdf_base64"])
with open("output.pdf", "wb") as f:
    f.write(pdf)

package main

import (
    "encoding/base64"
    "encoding/json"
    "io"
    "net/http"
    "os"
    "strings"
)

func main() {
    zpl := "^XA^FO50,50^A0N,30,30^FDHello World^FS^XZ"
    req, _ := http.NewRequest("POST",
        "https://api.zplflow/v1/convert/zpl-to-pdf",
        strings.NewReader(zpl))
    req.Header.Set("Authorization", "Bearer lb_live_xxxx")
    req.Header.Set("Content-Type", "text/plain")
    req.Header.Set("Idempotency-Key", "zpl-conv-001")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var data struct {
        Pages []struct {
            PDFBase64 string `json:"pdf_base64"`
        } `json:"pages"`
    }
    json.NewDecoder(resp.Body).Decode(&data)
    pdf, _ := base64.StdEncoding.DecodeString(data.Pages[0].PDFBase64)
    os.WriteFile("output.pdf", pdf, 0644)
}

<?php
$zpl = '^XA^FO50,50^A0N,30,30^FDHello World^FS^XZ';
$ch = curl_init("https://api.zplflow/v1/convert/zpl-to-pdf");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $zpl);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer lb_live_xxxx",
    "Content-Type: text/plain",
    "Idempotency-Key: zpl-conv-001"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
file_put_contents('output.pdf', base64_decode($data['pages'][0]['pdf_base64']));

AS400 / SQL Native (IBM i)

SELECT SYSTOOLS.HTTPPOSTCLOB(
    'https://api.zplflow/v1/convert/zpl-to-pdf',
    '^XA^FO50,50^A0N,30,30^FDHello World^FS^XZ',
    '{"Authorization":"Bearer lb_live_xxxx","Content-Type":"text/plain","Idempotency-Key":"zpl-conv-001"}'
) AS response
FROM SYSIBM.SYSDUMMY1;

AS400 / HTTPAPI (RPG)

dcl-s zpl varchar(200);
dcl-s response varchar(32000);
dcl-s rc int(10);

zpl = '^XA^FO50,50^A0N,30,30^FDHello World^FS^XZ';

rc = http_req('POST'
    : 'https://api.zplflow/v1/convert/zpl-to-pdf'
    : *null
    : %trim(response)
    : 'Authorization: Bearer lb_live_xxxx'
    : 'Content-Type: text/plain'
    : 'Idempotency-Key: zpl-conv-001'
    : 30000
    : %trim(zpl));

Common Parameters

These params are used by both sync conversions and async jobs:

POST /v1/estimate — Pre-Calculate Cost

Estimate token cost without executing the operation or spending tokens.

Idempotent: no (no token charge)
Content-Type: application/json

Request

{
  "operation": "pdf_to_zpl",
  "params": {
    "dpi": 203,
    "max_kb": 64
  },
  "document_count": 3
}

Response

{
  "operation": "pdf_to_zpl",
  "tokens_per_unit": 2,
  "units": 3,
  "total_tokens": 6
}

Next Steps

• Jobs API — Async workflow for batch processing and large files
• Pipelines — Transform ZPL with reusable step sequences
• Best Practices — Idempotency, error handling, rate limits
• Code Examples — Multi-language snippets