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

These details have not been verified by PyPI

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>",
    width=1200,
    height=630,
))
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>",
    width=1200,             # px, default 1200
    height=630,             # px, default 630
    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.

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

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>",
        format="A4",
    ),
    PdfPage(
        html="<h1 style='padding:40px'>Page 2 — Content</h1>",
        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"),
    ),
])

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" />',
    width=400,
    height=200,
))

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

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>",
        width=1200,
        height=630,
    ))
    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,

    # 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)
`width`	`int \| None`	1200	Viewport width in px (1–5000)
`height`	`int \| None`	630	Viewport height in px (1–5000)
`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)
`format`	`PdfFormat \| None`	`"A4"`	Paper size
`width`	`str \| None`	—	Custom width, e.g. `"8.5in"`
`height`	`str \| None`	—	Custom height, e.g. `"11in"`
`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

Purchase tokens at agent-gen.com.

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.1.5

Mar 12, 2026

0.1.3

Mar 5, 2026

0.1.2

Mar 2, 2026

This version

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.1.tar.gz (6.3 kB view details)

Uploaded Mar 2, 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.1-py3-none-any.whl (8.2 kB view details)

Uploaded Mar 2, 2026 Python 3

File details

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

File metadata

Download URL: agentgen-0.1.1.tar.gz
Upload date: Mar 2, 2026
Size: 6.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.10.10

File hashes

Hashes for agentgen-0.1.1.tar.gz
Algorithm	Hash digest
SHA256	`76fd303cd7e0f421ab4e9940bf23a13e045dbeea0fb6c3697b20ae5c33f41901`
MD5	`88822f66018f8f675aa99f1b72f35ebe`
BLAKE2b-256	`cfcbce9317dbda48d0964e4a74dc4a2eaf933f59da8fc6cbb66341d39447d5f1`

See more details on using hashes here.

File details

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

File metadata

Download URL: agentgen-0.1.1-py3-none-any.whl
Upload date: Mar 2, 2026
Size: 8.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.10.10

File hashes

Hashes for agentgen-0.1.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`23fb84e61e18fc56ddcb46d386adb69a6c1d8780b6bf6213cf8b71aa17991d14`
MD5	`77c7784113fb8f84bcc65d21a646cd76`
BLAKE2b-256	`e1c97ef6e86e984f84a825fb05b7b0ea9ace86b0cce07022ec77335fa244356e`

See more details on using hashes here.

agentgen 0.1.1

Navigation

Verified details

Maintainers

Unverified details

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

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

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`

`AgentGenError(Exception)`

`InsufficientTokensError(AgentGenError)`

`GenerateImageOptions` fields

`PdfPage` fields

`PdfMargin` fields