relaypdf

Official Python client for RelayPDF.

HTML to PDFs without the struggle. HTML to PDF API that converts HTML, Markdown, URLs, and Office files to production PDFs. One API for developers and coding agents.

Stdlib only (urllib). Covers the full public API: Chromium PDF and screenshots, Handlebars templates, LibreOffice / wkhtmltopdf convert, PDF tools, native document processing (OCR, PDF/A, crop, repair, email), barcodes, zip, async jobs, account, signed webhooks, and webhook verification.

• Docs: relaypdf.com/docs/sdks/python
• REST reference: relaypdf.com/docs
• OpenAPI: relaypdf.com/openapi.json
• Support: support@relaypdf.com

Requires Python 3.10+.

Introduction

RelayPDF is a commercial document API. You send HTML, Markdown, a public URL, Office bytes, or a published Handlebars template. You get a production PDF (or PNG/JPEG/WebP, Word, zip, …) over REST, this SDK, the CLI, or MCP.

JSON body field names match REST (camelCase): html, printBackground, sourceFilename, callbackUrl, templateId. Method names are snake_case: from_html, from_path, form_fill.

Failed operations are never billed.

Base URL

Default: https://api.relaypdf.com

Override with base_url for local (http://localhost:8787).

Definitions

Rate limiting

Trial: 20/min. Funded or auto-reload: 60/min. Burst: 5 / 10s. HTTP 429 includes Retry-After. Not billed.

Libraries and SDKs

Do not ask a human to paste an API key. Run npx @relaypdf/cli setup and approve in the browser.

Authentication

import os
from relaypdf import RelayPDF

client = RelayPDF(api_key=os.environ["RELAYPDF_API_KEY"])
# client = RelayPDF(api_key=..., base_url="http://localhost:8787")

Missing api_key raises TypeError. Invalid keys return HTTP 401 unauthorized.

User-Agent: relaypdf-python/0.1.5 (+https://relaypdf.com).

Error codes

The client raises RelayPDFError with status, code, message, and optional retry_after.

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)

Billing

New accounts: $5.00 trial (5000 millicents). Only successful jobs debit.

Installation

pip install relaypdf

uv add relaypdf

Getting started

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, pdf.content_type)

Response modes

response="binary" (default) | "url" | "async". Same as REST.

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")

files.download does not send the API key.

Client options

RelayPDF(api_key: str, base_url: str = "https://api.relaypdf.com", opener=None)

opener injects urlopen for tests. The SDK does not retry.

file= may be bytes or a base64 str.

Documentation for API methods

All URIs are relative to https://api.relaypdf.com. JSON bodies use REST camelCase field names.

Method examples

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

uploaded = client.files.upload(open("scan.pdf", "rb").read(), "scan.pdf")
job = client.process(
    "ocr",
    {"fileId": uploaded["id"], "response": "async", "options": {"language": "eng"}},
    idempotency_key="invoice-123",
    max_charge_microdollars=40000,
)

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,
)

shot = client.images.from_url("https://example.com", options={"fullPage": True})
from_word = client.convert.from_path("letter.docx", to="pdf")
docx = client.convert.from_html("<h1>Report</h1>", to="docx")

pack = client.pdf.merge(
    files=[
        {"url": "https://example.com/cover.pdf"},
        {"file": from_word.bytes},
    ]
)
client.pdf.stamp(file=pack.bytes, text="DRAFT", rotate=-24)
qr = client.barcodes.qr("https://relaypdf.com")

Result types

Exports: RelayPDF, RelayPDFError, DEFAULT_BASE_URL, verify_webhook, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER.

Webhooks

Use the raw request body. Create and list endpoints with client.webhooks. Secret is the dashboard webhook secret, not the API key.

created = client.webhooks.create("https://example.com/hooks", ["job.completed"])
# created["secret"] is shown once

from relaypdf import verify_webhook, WEBHOOK_SIGNATURE_HEADER

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

Header format: t=<unix>,v1=<hex>. HMAC-SHA256 of {t}.{raw_body}. Default skew 300s.

Authorization

HTTP Bearer. Not JWT.

Related docs

• Node.js SDK
• PHP SDK
• C# / .NET SDK
• Java SDK
• CLI
• MCP
• Errors
• Wallet

License

MIT. Strategic Products LLC, d/b/a RelayPDF.

PDF rasterization uses the native execution rate. Browser/native charges include one $0.0004 processing fee; AI includes one $0.002 processing fee. Millisecond and token charges are summed and rounded up once to $0.000001. Existing wallet balance fields remain compatible; exact amounts appear in billing receipts.