Docs

Python SDK

Use pip install relaypdf in Python when you want the official client instead of raw urllib. Request JSON field names match REST; methods are snake_case. The PyPI README is the full method and error reference.

The official Python SDK uses the standard library (urllib) and mirrors the Node client. Field names in request bodies match REST. Methods are snake_case.

Installation

Install from PyPI.

Package: relaypdf on PyPI. Current published line is 0.1.x. The PyPI README is the full method and error reference.

pip
pip install relaypdf

Quick start

api_key is required. Load it from the environment written by relaypdf setup.

main.py
import os
from relaypdf import RelayPDF

client = RelayPDF(api_key=os.environ["RELAYPDF_API_KEY"])

pdf = client.pdf.from_html(
    "<h1>Invoice #1042</h1><p>Total: $1,200.00</p>",
    filename="invoice.pdf",
)
pdf.save("invoice.pdf")
print(pdf.id, pdf.size_bytes)

URL, Markdown, templates

Same sources as REST. from_template takes a published template id or slug plus a dict.

from_url / from_markdown / from_template
pdf = client.pdf.from_url(
    "https://example.com",
    filename="page.pdf",
    options={"format": "A4", "printBackground": True},
)

md = client.pdf.from_markdown("# Hello\n\nFrom **Markdown**.")

invoice = client.pdf.from_template(
    "invoice",
    {"number": "INV-1042", "total": 1458},
    filename="invoice.pdf",
    strict=True,
)

Binary, URL, and async results

Default is binary with a save() helper. response="url" returns a 24-hour link. response="async" returns a job; wait then download.

response modes
url_result = client.pdf.from_html("<h1>Hi</h1>", response="url")
print(url_result.url, url_result.expires_at)

job = client.convert.from_path("deck.pptx", to="pdf", response="async")
done = client.jobs.wait(job.id)
file = client.files.download(done["id"])
file.save("deck.pdf")

Images, convert, merge

file values may be bytes or base64. from_path reads a local Office file and sets sourceFilename.

images / convert / merge
shot = client.images.from_url("https://example.com", options={"fullPage": True})
from_word = client.convert.from_path("letter.docx", to="pdf")
pack = client.pdf.merge(
    files=[
        {"url": "https://example.com/cover.pdf"},
        {"file": from_word.bytes},
    ]
)
qr = client.barcodes.qr("https://relaypdf.com")

Account, health, webhooks

health() is unauthenticated. verify_webhook needs the raw body bytes/str and the RelayPDF-Signature header.

helpers
from relaypdf import verify_webhook

print(client.health())
print(client.account())

ok = verify_webhook(os.environ["RELAYPDF_WEBHOOK_SECRET"], raw_body, signature_header)

Errors

HTTP failures raise RelayPDFError with status, code, message, and optional retry_after.

RelayPDFError
from relaypdf import RelayPDF, RelayPDFError

try:
    client.pdf.from_url("https://example.com")
except RelayPDFError as err:
    print(err.status, err.code, err.message, err.retry_after)

SDK reference

JSON bodies keep REST camelCase (printBackground, sourceFilename, templateId). Methods are snake_case. The PyPI README lists the same table.

Result classes: BinaryResult (save), UrlResult, AsyncResult. RelayPDFError has status, code, message, retry_after.

MethodHTTPDescription
health()GET /healthLiveness; no API key
account()GET /v1/accountPlan, rate tier, millicents; not billed
pdf.from_html / from_url / from_markdown / from_template / createPOST /v1/pdfHTML, URL, Markdown, or template → PDF
pdf.merge / extract / protect / unlock / bookmarksPOST /v1/pdf/*Merge, extract, password, outline
pdf.raster / from_images / stamp / rotate / delete_pages / compressPOST /v1/pdf/*Raster, images→PDF, stamp, rotate, delete, compress
pdf.info / text / form_fields / form_fillPOST /v1/pdf/info · /text · /form/*Inspect and fill
images.from_html / from_urlPOST /v1/imagesScreenshot
convert.from_html / from_path / wkhtml / createPOST /v1/convertLibreOffice or wkhtmltopdf
templates.list / gallery / get / create / update / delete / publish/v1/templatesHandlebars drafts (Node has extra preview/generate helpers)
barcodes.create / qrPOST /v1/barcodesBarcode / QR
zip.createPOST /v1/zipZip files
jobs.get / waitGET /v1/jobs/:idPoll or wait
files.downloadGET /v1/files/:id24h download
webhooks.list / create / deleteGET/POST/DELETE /v1/webhooksSigned endpoint CRUD
verify_webhookRelayPDF-SignatureHMAC-SHA256