API Reference (Gemini Edition)

API Endpoint: POST /api/v3/labelFormat: JSON Auth: Bearer Token

This reference documentation details the data structures used to generate PDFs with xPdf.

🧭 Request Structure

The API accepts a List of LabelRequest objects. This allows for batch generation of multiple PDFs in a single HTTP call.

[
  { "Request 1" },
  { "Request 2" }
]

---

🏗️ Core Objects

1. LabelRequest

The root object for a single PDF generation task.

Field	Type	Required	Description
tracking_number	String	No	Unique identifier for tracking this request in logs.
pdf_params	PdfParams	No	Global settings for the PDF (size, metadata, profile).
items	List<Item>	Yes	The content layers (text, barcodes, images) to draw.

2. PdfParams (Document Settings)

Controls the output file properties and PDF metadata.

Field	Type	Default	Description
Page Layout
width	Float	100.0	Page width in millimeters (mm).
height	Float	150.0	Page height in millimeters (mm).
Output Control
save_file	Bool	false	If true, saves the generated PDF to the server's disk.
output_dir	String	-	Directory path for saved files (if save_file is true).
file_name	String	-	Filename for the saved PDF.
global_font	String	-	Default font family for the document.
PDF/A Compliance
pdf_profile	String	""	See Supported Profiles.
Metadata
metadata_title	String	-	Required for PDF/UA-1. Title of the document.
metadata_language	String	Auto	ISO 639-1 code (e.g., en, zh). Auto-detected if missing.
metadata_authors	String	-	Author name(s).
metadata_subject	String	-	Subject or keywords.

Supported PDF Profiles

Value	Standard	Use Case
"" (Empty)	Standard PDF	General purpose, smallest size.
pdfa-1b	PDF/A-1b	Basic archiving.
pdfa-ua1	PDF/UA-1	Accessibility (Strict). Requires metadata_title.

3. Item (Content Layer)

A grouping of visual elements. All fields are optional lists.

Field	JSON Key	Type	Description
one_d_params	1d_params	List<OneDParams>	Linear barcodes (Code128, EAN).
two_d_params	2d_params	List<TwoDParams>	Matrix codes (QR, DataMatrix).
text_elements	text_elements	List<TextElement>	Absolute text labels.
lines	lines	List<Line>	Vector lines.
rectangles	rectangles	List<Rectangle>	Shapes and borders.
images	images	List<ImageElement>	Bitmaps (JPG, PNG).

---

🎨 Visual Elements

4. OneDParams (Linear Barcodes)

Standard linear barcodes like logistics labels.

Field	Type	Unit	Description
1d_content	String	-	(Required) The data to encode.
format	String	-	Code128, Code39, EAN13, UPCA, ITF, Codabar.
position	Position	mm	{ "x": 10, "y": 10 } origin point.
size	BarcodeSize	mm	{ "height": 15, "module_width": 0.3 }.
human_readable_text	HumanReadableText	-	Text shown near the barcode.
orientation	Int	deg	Rotation: 0, 90, 180, 270.
quiet_zone	Int	mods	Safe margin around barcode (default: 10).

5. TwoDParams (Matrix Codes)

2D codes like QR Codes.

Field	JSON Key	Type	Description
two_d_content	2d_content	String	(Required) The data/URL to encode.
format	format	String	QRCode, DataMatrix, PDF417, Aztec.
module_size	module_size	Float	Pixel size in mm (e.g., 0.5).
x	x	Float	X coordinate (mm).
y	y	Float	Y coordinate (mm).

6. TextElement

Independent text labels.

Field	Type	Description
content	String	Text string to display.
x, y	Float	coordinates (mm).
font_size	Float	Size in points (pt).
font_name	String	Font family (must be loaded).
bold	Bool	true for bold weight.
align	String	Left, Center, Right.
color	String	Hex color (e.g., #FF0000).

7. Line

Vector lines.

Field	Type	Description
x1, y1	Float	Start point (mm).
x2, y2	Float	End point (mm).
thickness	Float	Line width (mm).
color	String	Stroke color (Hex).

8. Rectangle

Boxes and borders.

Field	Type	Description
x, y	Float	Top-left corner (mm).
width, height	Float	Dimensions (mm).
thickness	Float	Border width (mm).
radius	Float	Corner radius (mm).
fill	Bool	true to fill, false for stroke only.
color	String	Color (Hex).

9. ImageElement

Raster images.

Field	Type	Description
x, y	Float	Position (mm).
width, height	Float	Display size (mm).
base64	String	Priority 1: Raw image data.
image_path	String	Priority 2: Local server path.
image_name	String	Priority 3: Pre-loaded asset name.

---

🧩 Helper Types

10. Helper Types

Position

{ "x": 10.0, "y": 20.0 }

BarcodeSize

{
  "height": 15.0,        // Bar height
  "module_width": 0.3,   // Width of narrowest bar
  "width": 50.0          // Optional total width override
}

11. HumanReadableText

Attached to 1D Barcodes.

Field	Type	Description
enabled	Bool	Show text?
content	String	Override text (defaults to barcode data).
side	Int	0 = Bottom, 1 = Top.
align	String	Center, Left, Right.

---

⚠️ Error Codes

Code	Meaning	Solution
E002	Invalid Profile	pdf_profile must be one of the supported strings or empty.
E003	Missing Metadata	For pdfa-ua1, metadata_title is required.

---

Generated by Gemini - 2026-01-03