API Documentation

Quickstart

Generate your first image in under a minute. Sign up, buy tokens, grab your API key, and make your first request.

curl -X POST https://www.agent-gen.com/api/v1/generate/image \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1 style=\"font-family:sans-serif;color:#4f46e5\">Hello!</h1>",
    "viewport_width": 1200,
    "format": "png"
  }'

{
  "url": "https://cdn.agent-gen.com/output/abc123.png",
  "width": 1200,
  "height": 84,
  "format": "png",
  "tokens_used": 1,
  "request_id": "v7k9x2..."
}

Free Tier

The generate/image and generate/pdf endpoints work without an API key — no sign-up required. This lets you demo generation to your users or admins instantly.

# No API key required — a watermark is added automatically
curl -X POST https://www.agent-gen.com/api/v1/generate/image \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1 style=\"font-family:sans-serif;color:#4f46e5\">Hello!</h1>",
    "viewport_width": 1200,
    "format": "png"
  }'

{
  "url": "https://cdn.agent-gen.com/output/abc123.png",
  "watermarked": true,
  "format": "png",
  "width": 1200,
  "height": 84,
  "request_id": "v7k9x2..."
}

To remove the watermark and get higher throughput, create an API key.

Authentication

Authenticated requests use an X-API-Key header. This is required for /v1/balance, /v1/upload/temp, and multi-page PDFs. For generate endpoints it is optional — omitting it uses the free tier (watermarked, rate-limited). Generate keys from the dashboard.

X-API-Key: YOUR_API_KEY

Generate Image

POST /v1/generate/image — costs 1 token

Render any HTML string to PNG, JPEG, or WebP using headless Chrome. AgentGen infers output dimensions from the rendered HTML. Use viewport hints to control layout, or pass a selector to capture a specific element.

curl -X POST https://www.agent-gen.com/api/v1/generate/image \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1 style=\"font-family:sans-serif;color:#4f46e5\">Hello!</h1>",
    "viewport_width": 1200,
    "format": "png"
  }'

Generate PDF

POST /v1/generate/pdf — costs 2 tokens per page

Generate pixel-perfect PDFs from HTML. By default AgentGen prefers CSS @page size from the document and falls back to a named format when CSS does not define one.

curl -X POST https://www.agent-gen.com/api/v1/generate/pdf \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Invoice #001</h1><p>Amount due: $99.00</p>",
    "page_size_source": "css",
    "format": "A4",
    "margin": { "top": "20mm", "bottom": "20mm", "left": "15mm", "right": "15mm" },
    "optimize": true
  }'

Upload Temp File

POST /v1/upload/temp — free

Upload images or assets to use inside your HTML templates. Files are stored on Cloudflare R2 and auto-expire after 24 hours. Max 10 MB.

curl -X POST https://www.agent-gen.com/api/v1/upload/temp \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]"

Compress Image

POST /v1/compress/image — costs 1 token

Compress an uploaded image using Sharp. Accepts JPEG, PNG, WebP, AVIF, GIF, or TIFF. Choose an output format and a quality preset — the response includes the CDN URL plus before/after size stats. Requires an API key; no free tier.

curl -X POST https://www.agent-gen.com/api/v1/compress/image \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "format=webp" \
  -F "mode=balanced"

{
  "url": "https://cdn.agent-gen.com/out/abc123.webp",
  "format": "webp",
  "mode": "balanced",
  "original_size": 450000,
  "compressed_size": 87000,
  "savings_percent": 80.7,
  "width": 1920,
  "height": 1080,
  "tokens_used": 1
}

Check Balance

GET /v1/balance — free

Returns your current token balance.

curl https://www.agent-gen.com/api/v1/balance \
  -H "X-API-Key: YOUR_API_KEY"

{ "tokens": 499 }

Origin Hosting

POST /v1/origin and POST /v1/origin/{id}/public-key — free

Provision a dedicated public subdomain (<id>.agent-gen.com) for hosting files. Use this to get a stable origin URL for third-party integrations that require a specific allowed origin — for example, uploading a Tesla virtual key.

# 1. Provision a new origin subdomain
curl -X POST https://www.agent-gen.com/api/v1/origin \
  -H "X-API-Key: YOUR_API_KEY"
# → { "id": "abc123xyz", "origin": "https://abc123xyz.agent-gen.com" }

# 2. Upload your EC public key (PEM) to the origin
curl -X POST https://www.agent-gen.com/api/v1/origin/abc123xyz/public-key \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @public-key.pem

MCP Server

POST https://www.agent-gen.com/api/mcp — JSON-RPC 2.0

AgentGen has a built-in Model Context Protocol (MCP) server. Add it to Claude once and your AI can generate PDFs and images without any code — just describe what you need.

# Claude Code — add AgentGen as an MCP server (one-time setup)
claude mcp add --transport http agentgen https://www.agent-gen.com/api/mcp \
  --header "x-api-key: YOUR_API_KEY"

# Verify it was added
claude mcp list

Available tools

Tool parameters

CLI

The agentgen CLI lets you generate PDFs and images from your terminal, shell scripts, and CI pipelines — no code required. See the full CLI guide →

Install

# One-liner (Linux & macOS)
curl -fsSL https://raw.githubusercontent.com/Agent-Gen-com/agent-gen-lib/main/install.sh | sh

# Homebrew
brew tap Agent-Gen-com/agentgen && brew install agentgen

# Cargo
cargo install agentgen-cli

Quick start

export AGENTGEN_API_KEY="agk_..."

# Generate an image
agentgen image --html "<h1>Hello!</h1>" --output hello.png

# Generate a PDF
agentgen pdf --html "<h1>Invoice #42</h1>" --output invoice.pdf

# Upload a file for 24h CDN access
agentgen upload ./logo.png

# Check token balance
agentgen balance

# Provision a public origin subdomain
agentgen origin

# Upload a public key to an origin
agentgen public-key <origin-id> public-key.pem

Key flags

Full CLI reference with all flags and CI examples →

Errors

All errors return JSON with a error field.

{
  "error": "Insufficient tokens.",
  "balance": 0,
  "required": 2,
  "buy_more_url": "https://www.agent-gen.com/dashboard/billing"
}