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

What's new in 0.6.1

E-signature is now a first-class method. Send any rendered PDF to a signer and collect a stamped copy:

from kamy import Kamy

kamy = Kamy(api_key="kamy_pk_...")

pdf = kamy.render(template="contract", data={...})

sig = kamy.create_signature(
    render_id=pdf.id,
    signer_email="alice@example.com",
    signer_name="Alice Example",
    # optional — defaults to bottom-right of last page sized 220×64 pt
    position={"page": 3, "x": 360, "y": 80, "w": 220, "h": 64},
    message="Please review and sign by Friday.",
)
print(sig["sign_url"])
print(sig["sign_token"])

# List recent requests.
result = kamy.list_signatures(limit=25)
for s in result["signatures"]:
    print(s["id"], s["status"], s["signer_email"])

Both methods are mirrored on AsyncKamy for asyncio / FastAPI use. Status flows pending → signed | voided | expired; tokens auto-expire after 30 days.

What's new in 0.6.0

26 system templates across 10 packs and 5 new endpoints. Every endpoint is HTTP-callable today — pass template="<slug>" plus data=<dict> to kamy.render() for any of the new templates.

# MENA
kamy.render(template="bh-vat-invoice",        data={...})  # Bahrain NBR, VAT 10%
kamy.render(template="om-vat-invoice",        data={...})  # Oman OTA, VAT 5%
kamy.render(template="eg-vat-invoice",        data={...})  # Egypt ETA, VAT 14%
kamy.render(template="qa-commercial-invoice", data={...})
kamy.render(template="kw-commercial-invoice", data={...})

# Global compliance
kamy.render(template="uk-vat-invoice",  data={...})  # HMRC
kamy.render(template="eu-vat-invoice",  data={...})  # Directive 2006/112/EC
kamy.render(template="us-w9",           data={...})  # IRS W-9 Rev. Mar 2024
kamy.render(template="us-1099-nec",     data={...})  # IRS 1099-NEC TY 2025
kamy.render(template="in-gst-invoice",  data={...})  # CGST/SGST + IGST
kamy.render(template="au-tax-invoice",  data={...})  # ATO GSTR 2013/1

# UAE verticals + legal
kamy.render(template="uae-tenancy-contract", data={...})
kamy.render(template="uae-noc-letter",       data={...})
kamy.render(template="uae-offer-letter",     data={...})
kamy.render(template="salary-certificate",   data={...})
kamy.render(template="mutual-nda",           data={...})

New endpoints (HTTP-callable today; typed methods land in 0.6.x patches):

POST /v1/render/bulk    # 1 template × N rows → ZIP of N PDFs (cap 25)
POST /v1/render-html    # rendered HTML for email pipelines
POST /v1/render-xlsx    # spec-based XLSX
POST /v1/render-pptx    # spec-based PowerPoint
POST /v1/schedules      # recurring renders on a cron + email/whatsapp/download

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