API Schema Reference

The canonical API route is POST /api/v1/label.

The request body is a single DocumentRequest JSON object.

Root: DocumentRequest

Field	Type	Required
settings	Settings	No
pages	Page[]	Yes
header	Section	No
footer	Section	No

Page Sizing

Each page must define its physical size in exactly one of these ways:

• Explicit millimeters: width + height
• Preset size: size

Rules:

• size and width / height are mutually exclusive
• width and height must be provided together
• Preset matching is case-insensitive

Supported preset values:

• a4
• a6
• letter
• legal
• label_100_100
• label_100_150
• label_4_6_in

Section (header / footer)

header and footer share the same shape:

• height: number in mm
• elements: Element[]

Behavior:

• header is repeated on every page
• footer is repeated on every page
• header elements render in absolute page coordinates
• footer elements render with a bottom offset of page.height - footer.height
• footer.height reduces the available body height for pagination
• header does not automatically push body elements down
• optional settings.page_margin / pages[].margin define a body content box
• when page margins are configured, body x/y become relative to the content box
• body elements outside the content box fail validation

Settings

Field	Type
defaults	Defaults
metadata	Metadata
output	OutputSettings
profile	string
page_margin	PageMargin

Defaults uses unified style objects:

• text: TextStyle
• stroke: StrokeStyle
• fill: FillStyle
• shape: ShapeDefaults

OutputSettings

• mode: binary or file
• file_name: optional custom file name used when mode = "file"
• default behavior is binary
• missing file_name falls back to gPdf-MMDDHHmmssSSS.pdf

Element Types

elements[] is a tagged union by type:

• text
• barcode
• line
• rect
• circle
• ellipse
• polygon
• link
• image
• table
• stack

Image payloads currently support:

• Raster: jpg / jpeg / png / webp
• Vector image payloads: svg

stack

• body-only flow element for table followed by one or more blocks
• children[0] must be table
• later children must be block
• gap is the vertical distance between the table's final bottom and the next block's start

block

• follow-up content group used inside stack
• no own x/y/width/height
• child x keeps current body semantics
• child y is relative to the block start
• cannot nest table / stack / block

x_anchor

• supported by text, barcode, rect, image, and link
• mutually exclusive with x
• supports page_* and content_* references everywhere
• supports table_left / table_right only inside stack -> block
• text requires style.width when x_anchor is used

Unified Vector Styling

Vector elements use the same schema:

• stroke: StrokeStyle
• fill: FillStyle

This is shared by line / rect / circle / ellipse / polygon. Table borders also use the same StrokeStyle model for grid.frame, grid.horizontal, grid.vertical, and cell.borders.

StrokeStyle includes optional compound for compound strokes. The currently supported kind is double.

Hyperlink Model

• Attached links: text / barcode / line / rect / circle / ellipse / polygon / image support optional link: LinkSpec
• Independent hotspots: type: "link" supports area-based click targets without visible graphics
• LinkSpec.target supports:
  • URL: { "type": "url", "url": "https://..." }
  • Page destination: { "type": "page", "page": 2, "x": 10, "y": 20 }
• URL schemes are restricted to http, https, mailto, tel
• Invalid link fields fail validation instead of being silently ignored

Table Schema

The only supported public table schema is centered on:

• columns
• rows
• cell
• header
• row_header
• body
• grid
• pagination

Key rules:

• row headers are modeled as columns[].role = "row_header"
• grid.frame, grid.horizontal, and grid.vertical accept StrokeStyle
• columns[].width is always a width object: fixed, percent, or auto
• percent and auto require table.width
• grouped headers live in header.rows; leaf headers still use columns[].header
• TableCellStyle supports content_offset_x / content_offset_y
• row objects may only contain keys declared in columns[].key
• legacy lightweight payloads such as data/layout/theme/row_headers/corner/style_overrides are no longer part of the public API

Notes

• Deprecated payloads (LabelRequest[], pdf_params, items, 1d_params, 2d_params) are not part of the current public schema.
• Runtime defaults are distributed through GET /v1/xpdf/runtime-config; worker and server use the same runtime source of truth.
• See JSON 数据结构 for complete field-level details.