kamy-sdk 0.1.1

Kamy PDF generation API — Python SDK

Kamy — Python SDK

Official Python SDK for the Kamy PDF generation API.

pip install kamy-sdk

Distribution name on PyPI is kamy-sdk (the kamy name was unavailable). The import path is still from kamy import Kamy — the directory under site-packages/ is named kamy/, so module imports look the way you'd expect.

Quick start

from kamy import Kamy

kamy = Kamy(api_key="kamy_pk_...")  # or set KAMY_API_KEY in the env

pdf = kamy.render(
    template="invoice",
    data={
        "invoiceNumber": "INV-001",
        "from": {"name": "Acme Inc."},
        "to": {"name": "Globex Corp."},
        "lineItems": [
            {"description": "Consulting", "quantity": 10, "unitPrice": 150, "amount": 1500},
        ],
        "subtotal": 1500,
        "total": 1500,
        "currency": "USD",
    },
)

print(pdf.url)  # signed URL valid for 1 hour

Async (FastAPI / asyncio)

from kamy import AsyncKamy

async with AsyncKamy(api_key="kamy_pk_...") as kamy:
    pdf = await kamy.render(template="invoice", data={...})

Other modes

# Inline HTML
kamy.render(html="<h1>Hello {{name}}</h1>", data={"name": "world"})

# URL mode (paid plans only — fetches the URL server-side)
kamy.render(url="https://example.com/invoice/123")

# Word (.docx) output instead of PDF
kamy.render_docx(template="invoice", data={...})

# Batch — up to 100 items, partial failures don't abort
results = kamy.render_batch([
    {"template": "receipt", "data": order1},
    {"template": "receipt", "data": order2},
])

Render options

from kamy import Kamy, RenderOptions, FormFieldSpec

kamy = Kamy()

pdf = kamy.render(
    template="invoice",
    data={...},
    options=RenderOptions(
        format="a4",
        orientation="portrait",
        page_numbers=True,
        pdf_a="2b",  # archival output
        form_fields=[  # fillable AcroForm widgets
            FormFieldSpec(
                name="signature",
                type="signature",
                page=1,
                x=100, y=100,
                width=200, height=40,
            ),
        ],
    ),
)

Error handling

from kamy import Kamy
from kamy import RateLimitError, QuotaExceededError, ValidationError

kamy = Kamy()
try:
    pdf = kamy.render(template="invoice", data={...})
except ValidationError as e:
    print("Bad payload:", e.details)  # {"field.name": ["reason"]}
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after_seconds}s")
except QuotaExceededError:
    print("Monthly quota hit. Upgrade or wait until next billing cycle.")

Documentation

• API reference: https://kamy.dev/api-reference
• Docs: https://kamy.dev/docs
• OpenAPI spec: https://kamy.dev/openapi.json
• TypeScript SDK: https://www.npmjs.com/package/@kamydev/sdk
• MCP server: https://kamy.dev/docs/mcp

License

MIT