Python client for the AgentGen API — HTML to PDF and Image

These details have not been verified by PyPI

Project links

Project description

agentgen · Python SDK

Python client for the AgentGen API — HTML → PDF and HTML → Image generation.

Sync + async — AgentGenClient for regular code, AsyncAgentGenClient for asyncio / async/await
Typed — dataclass-based request/response types with full type annotations
Lightweight — single dependency: httpx

Installation

pip install agentgen

Requires Python 3.9+ and httpx >= 0.25.

Quick start

from agentgen import AgentGenClient, GenerateImageOptions, PdfPage

client = AgentGenClient(api_key="agk_...")

# Render HTML to a PNG image
image = client.generate_image(GenerateImageOptions(
    html="<h1 style='font-family:sans-serif'>Hello, world!</h1>",
    viewport_width=1200,
))
print(image.url)  # https://…/output.png

# Render HTML to a PDF
pdf = client.generate_pdf(PdfPage(
    html="<h1>Invoice #42</h1><p>Amount due: $99.00</p>",
    format="A4",
))
print(pdf.url)   # https://…/output.pdf

# Check token balance
balance = client.get_balance()
print(f"Remaining tokens: {balance.tokens}")

Client classes

`AgentGenClient` (synchronous)

from agentgen import AgentGenClient

client = AgentGenClient(
    api_key="agk_...",                        # required
    base_url="https://www.agent-gen.com/api", # optional — default shown
)

`AsyncAgentGenClient` (async / await)

from agentgen import AsyncAgentGenClient

client = AsyncAgentGenClient(api_key="agk_...")

async def main():
    image = await client.generate_image(...)

Both classes expose exactly the same methods with the same signatures. The only difference is that AsyncAgentGenClient returns coroutines that must be awaited.

Methods

`generate_image(options)` → `GenerateImageResult`

Renders an HTML string to a screenshot image. Costs 1 token.

from agentgen import GenerateImageOptions

result = client.generate_image(GenerateImageOptions(
    html="<div style='background:#6366f1;color:#fff;padding:40px'>Hello</div>",
    viewport_width=1200,    # px, default 1200
    viewport_height=800,    # px, default 800
    selector="#card",       # optional CSS selector to capture
    format="png",           # "png" | "jpeg" | "webp", default "png"
    device_scale_factor=2,  # 1–3, default 2 (retina-quality)
))

print(result.url)          # public URL, valid for 24 h
print(result.width)        # actual rendered width
print(result.height)       # actual rendered height
print(result.format)       # "png" | "jpeg" | "webp"
print(result.tokens_used)  # always 1
print(result.request_id)   # unique request identifier

Only html is required — all other fields default to None (server applies defaults).

`generate_pdf(options)` → `GeneratePdfResult`

Renders HTML to a PDF document. Costs 2 tokens per page.

Pass a single PdfPage object for a one-page PDF, or a list of PdfPage objects for a multi-page PDF. Set optimize=False to preserve the original Chromium output instead of the smaller post-processed PDF.

Single-page PDF

from agentgen import PdfPage, PdfMargin

result = client.generate_pdf(PdfPage(
    html="""
    <html>
      <body style="font-family:sans-serif;padding:40px">
        <h1>Invoice #42</h1>
        <p>Amount due: $99.00</p>
      </body>
    </html>
    """,
    page_size_source="css", # prefer CSS @page size, fallback to format
    format="A4",            # "A4" | "Letter" | "A3" | "Legal"
    landscape=False,        # default False
    print_background=True,  # default True
    margin=PdfMargin(
        top="20mm",
        bottom="20mm",
        left="15mm",
        right="15mm",
    ),
), optimize=True)

print(result.url)          # public URL pointing to the PDF
print(result.pages)        # number of pages generated
print(result.tokens_used)  # pages × 2
print(result.request_id)

Multi-page PDF

Pass a list of PdfPage objects — each entry is an independent page with its own HTML and settings.

result = client.generate_pdf([
    PdfPage(
        html="<h1 style='padding:40px'>Page 1 — Cover</h1>",
        page_size_source="css",
        format="A4",
    ),
    PdfPage(
        html="<h1 style='padding:40px'>Page 2 — Content</h1>",
        page_size_source="css",
        format="A4",
        landscape=True,
    ),
    PdfPage(
        html="<h1 style='padding:40px'>Page 3 — Appendix</h1>",
        format="A4",
        margin=PdfMargin(top="10mm", bottom="10mm", left="10mm", right="10mm"),
    ),
], optimize=True)

print(f"Generated {result.pages} pages, used {result.tokens_used} tokens")

Up to 100 pages per request.

`upload_temp(file, filename=None)` → `UploadTempResult`

Uploads a file to temporary storage so you can embed it by URL inside your HTML before calling generate_image or generate_pdf. Free — no tokens consumed. Files are auto-deleted after 24 hours.

# Upload from a file path (str or pathlib.Path)
upload = client.upload_temp("./logo.png")

print(upload.url)         # public URL, valid for 24 h
print(upload.key)         # storage key
print(upload.size)        # file size in bytes
print(upload.expires_at)  # ISO 8601 expiry timestamp

# Now embed the URL in your HTML
result = client.generate_image(GenerateImageOptions(
    html=f'<img src="{upload.url}" style="width:200px" />',
    viewport_width=400,
))

# Upload from an open file object
with open("./chart.svg", "rb") as f:
    upload = client.upload_temp(f, filename="chart.svg")

Accepted types: image/png, image/jpeg, image/webp, image/gif, image/svg+xml. Max size: 10 MB.

`get_balance()` → `BalanceResult`

Returns the current token balance.

balance = client.get_balance()
print(f"You have {balance.tokens} tokens remaining.")

`create_origin()` → `CreateOriginResult`

Provisions a new public subdomain (<id>.agent-gen.com) for hosting files. Use this to obtain a stable origin URL for third-party integrations that require a specific allowed origin (e.g. Tesla virtual key setup).

result = client.create_origin()
print(result.id)      # "abc123xyz"
print(result.origin)  # "https://abc123xyz.agent-gen.com"

`upload_origin_public_key(origin_id, pem)` → `UploadOriginPublicKeyResult`

Uploads an EC public key (PEM format) to an origin subdomain. The key is stored at the standard Tesla virtual key path /.well-known/appspecific/com.tesla.3p.public-key.pem.

result = client.create_origin()

with open("public-key.pem") as f:
    pem = f.read()

key_result = client.upload_origin_public_key(result.id, pem)
print(key_result.url)
# https://abc123xyz.agent-gen.com/.well-known/appspecific/com.tesla.3p.public-key.pem

Async usage

Every method above works identically with AsyncAgentGenClient. Just await each call:

import asyncio
from agentgen import AsyncAgentGenClient, GenerateImageOptions, PdfPage

async def main():
    client = AsyncAgentGenClient(api_key="agk_...")

    # Run both requests concurrently
    image_coro = client.generate_image(GenerateImageOptions(
        html="<h1>OG Image</h1>",
        viewport_width=1200,
    ))
    pdf_coro = client.generate_pdf(PdfPage(
        html="<h1>Report</h1>",
        format="A4",
    ))

    image, pdf = await asyncio.gather(image_coro, pdf_coro)
    print(image.url, pdf.url)

asyncio.run(main())

Error handling

from agentgen import AgentGenClient, AgentGenError, InsufficientTokensError, GenerateImageOptions

client = AgentGenClient(api_key="agk_...")

try:
    result = client.generate_image(GenerateImageOptions(html="<h1>Hello</h1>"))
    print(result.url)

except InsufficientTokensError as e:
    print(f"Not enough tokens. Have {e.balance}, need {e.required}.")
    print(f"Buy more at: {e.buy_more_url}")

except AgentGenError as e:
    print(f"API error {e.status}: {e}")
    if e.detail:
        print(f"Detail: {e.detail}")

Exception classes

`AgentGenError(Exception)`

Raised for all API errors (4xx / 5xx) except HTTP 402.

Attribute	Type	Description
`args[0]` / `str(e)`	`str`	Human-readable error message
`status`	`int`	HTTP status code
`detail`	`str \| None`	Optional additional detail from the API
`details`	`dict \| None`	Validation field errors (present on HTTP 422)

`InsufficientTokensError(AgentGenError)`

Raised when the account has too few tokens (HTTP 402).

Attribute	Type	Description
`balance`	`int`	Current token balance
`required`	`int`	Tokens needed for this request
`buy_more_url`	`str`	Direct link to purchase more tokens

Type reference

from agentgen import (
    # Clients
    AgentGenClient,
    AsyncAgentGenClient,

    # Request types
    GenerateImageOptions,
    PdfPage,
    PdfMargin,

    # Response types
    GenerateImageResult,
    GeneratePdfResult,
    UploadTempResult,
    BalanceResult,
    CreateOriginResult,
    UploadOriginPublicKeyResult,

    # Literal type aliases
    ImageFormat,   # Literal["png", "jpeg", "webp"]
    PdfFormat,     # Literal["A4", "Letter", "A3", "Legal"]

    # Exceptions
    AgentGenError,
    InsufficientTokensError,
)

`GenerateImageOptions` fields

Field	Type	Default	Description
`html`	`str`	required	HTML to render (max 500 KB)
`viewport_width`	`int \| None`	1200	Viewport width in px used for layout before capture (1–5000)
`viewport_height`	`int \| None`	800	Viewport height in px used for layout before capture (1–5000)
`selector`	`str \| None`	—	Optional CSS selector to capture instead of the full rendered document
`format`	`ImageFormat \| None`	`"png"`	Output format
`device_scale_factor`	`float \| None`	2.0	Device pixel ratio (1–3)

`PdfPage` fields

Field	Type	Default	Description
`html`	`str`	required	HTML to render (max 500 KB)
`page_size_source`	`"css" \| "format" \| None`	`"css"`	Prefer CSS `@page` size or fallback format
`format`	`PdfFormat \| None`	`"A4"`	Fallback paper size
`landscape`	`bool \| None`	`False`	Landscape orientation
`margin`	`PdfMargin \| None`	—	Page margins
`print_background`	`bool \| None`	`True`	Render CSS backgrounds

`PdfMargin` fields

All fields are str | None and accept any CSS length value (e.g. "20mm", "1in", "72pt").

Token pricing

Operation	Cost
Generate image	1 token
Generate PDF (per page)	2 tokens
Upload temp file	Free
Check balance	Free
Create origin	Free
Upload origin public key	Free

Purchase tokens at agent-gen.com.

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

0.1.5

Mar 12, 2026

0.1.3

Mar 5, 2026

0.1.2

Mar 2, 2026

0.1.1

Mar 2, 2026

0.1.0

Mar 2, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

agentgen-0.1.5.tar.gz (7.6 kB view details)

Uploaded Mar 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

agentgen-0.1.5-py3-none-any.whl (9.6 kB view details)

Uploaded Mar 12, 2026 Python 3

File details

Details for the file agentgen-0.1.5.tar.gz.

File metadata

Download URL: agentgen-0.1.5.tar.gz
Upload date: Mar 12, 2026
Size: 7.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.9.6

File hashes

Hashes for agentgen-0.1.5.tar.gz
Algorithm	Hash digest
SHA256	`c055966b53daf8e93e2f305ed91ee512e677595d7aa7e987fc908befece5dd10`
MD5	`b614376750474a104c1867305dedc1a1`
BLAKE2b-256	`4e39d7755716baad48a85fab7aae6dba44132a86ae34692e6dbea84614c413fc`

See more details on using hashes here.

File details

Details for the file agentgen-0.1.5-py3-none-any.whl.

File metadata

Download URL: agentgen-0.1.5-py3-none-any.whl
Upload date: Mar 12, 2026
Size: 9.6 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.9.6

File hashes

Hashes for agentgen-0.1.5-py3-none-any.whl
Algorithm	Hash digest
SHA256	`083cf53618cd9723f694b09f29943666896ce353c85cbe4ce5c1b46d5afeb1f2`
MD5	`4c8ef4027c427a5c306e1e143ebf8b11`
BLAKE2b-256	`ee76fefe182786e4e59c5c30a4e12688e3ae5517922d1d2e35de4ab27749e6b1`

See more details on using hashes here.

agentgen 0.1.5

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Project description

agentgen · Python SDK

Installation

Quick start

Client classes

AgentGenClient (synchronous)

AsyncAgentGenClient (async / await)

Methods

generate_image(options) → GenerateImageResult

generate_pdf(options) → GeneratePdfResult

Single-page PDF

Multi-page PDF

upload_temp(file, filename=None) → UploadTempResult

get_balance() → BalanceResult

create_origin() → CreateOriginResult

upload_origin_public_key(origin_id, pem) → UploadOriginPublicKeyResult

Async usage

Error handling

Exception classes

AgentGenError(Exception)

InsufficientTokensError(AgentGenError)

Type reference

GenerateImageOptions fields

PdfPage fields

PdfMargin fields

Token pricing

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

`AgentGenClient` (synchronous)

`AsyncAgentGenClient` (async / await)

`generate_image(options)` → `GenerateImageResult`

`generate_pdf(options)` → `GeneratePdfResult`

`upload_temp(file, filename=None)` → `UploadTempResult`

`get_balance()` → `BalanceResult`

`create_origin()` → `CreateOriginResult`

`upload_origin_public_key(origin_id, pem)` → `UploadOriginPublicKeyResult`

`AgentGenError(Exception)`

`InsufficientTokensError(AgentGenError)`

`GenerateImageOptions` fields

`PdfPage` fields

`PdfMargin` fields