Render a label preview as PNG

POST

/api/v1/render/preview

curl --request POST \
  --url https://example.com/api/v1/render/preview \
  --header 'Content-Type: application/json' \
  --header 'X-Label-Hub-Key: <X-Label-Hub-Key>' \
  --data '{ "content_type": "qr_only", "data": { "items": [], "primary_id": "example", "qr_payload": "example", "secondary": [], "title": "example" }, "layout_preset": "compact", "orientation": "across", "tape_mm": 12 }'

Render a label using the LayoutEngine and return the result as a PNG image (no printer interaction, no job created). Useful for UI preview and debugging. Renders through the same engine call as a print job, so orientation and layout_preset give the exact image the job would print (an along image is the landscape band before the printer backend rotates it). Returns 422 when data is missing fields required by content_type or the QR payload does not fit the fixed QR code (qr_payload_too_long). Returns 409 when tape_mm is not a supported tape width or the orientation is not available for it.

Authorizations

• APIKeyHeader

Request Body^required

Media typeapplication/json

_PreviewRequest

Request body for POST /render/preview.

Phase 1k.1a (Task 25): render-only endpoint — no printer, no queue, no DB.

object

content_type

required

ContentType

Tape-independent semantic content types for label rendering.

string

Allowed values: qr_only qr_one_line qr_two_lines qr_three_lines text_one_line text_two_lines qr_with_listing

data

required

RawLabelData

Raw label payload accepted when the client supplies data directly.

Mirrors LabelData minus source_app (set server-side to ‘manual’). All content fields are optional — ContentType-specific validation happens in LayoutEngine._validate_data.

Every free text is bounded at the request (the same caps as sheet items): 512 characters per text and QR payload, at most 10 secondary lines and 100 items. A label shows far less; the renderer shortens what does not fit (#258 security review).

object

items

Items

Array<object>

default: <= 100 items

RawListingItem

One listing row of raw label data, with bounded text.

object

item

required

Item

string

<= 512 characters

qr_payload

Qr Payload

Any of:

string

string

<= 512 characters

null

null

primary_id

Primary Id

Any of:

string

string

<= 512 characters

null

null

qr_payload

Qr Payload

Any of:

string

string

<= 512 characters

null

null

secondary

Secondary

Array<string>

default: <= 10 items

title

Title

Any of:

string

string

<= 512 characters

null

null

layout_preset

Any of:

QlLayoutPreset

QlLayoutPreset

The built-in QL 62 mm across-width layouts (docs/design/ql-layout-presets).

string

Allowed values: compact small_qr standard

null

null

orientation

Any of:

LabelOrientation

LabelOrientation

How the label content runs on endless tape.

string

Allowed values: across along

null

null

tape_mm

Tape Mm

integer

default: 12

Responses

200

PNG label bitmap

Media typeimage/png

409

Unsupported tape width or orientation

422

Data missing required fields, or QR payload too long