# Gotenberg alternative: hosted Gotenberg as an API

Gotenberg alternative with no servers to run. html-pdf.com is hosted Gotenberg Chromium as a JSON API, with field mapping and when to self-host.

Full disclosure first. html-pdf.com runs [Gotenberg](https://gotenberg.dev) under the hood. Gotenberg is an MIT-licensed Docker image that wraps headless Chromium and LibreOffice behind an HTTP API, and it is excellent.

So this isn't a "Gotenberg vs us" page. It helps you decide whether to run Gotenberg yourself or call a hosted version of its Chromium HTML-to-PDF routes, with a JSON API, API keys and per-page billing.

**Quick answer.** Replace your `/forms/chromium/convert/html` call with one JSON request to the hosted API.

```bash
curl -X POST https://html-pdf.com/v1/pdf \
  -H "Authorization: Bearer $HTML_PDF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}' \
  -o out.pdf
```

## Self-hosted Gotenberg vs html-pdf.com

This table shows what each option gives you, side by side.

| | Gotenberg (self-hosted) | html-pdf.com |
|---|---|---|
| License / cost | MIT, free; you pay for servers | Per page, from $10 for 1,000 pages |
| Engine | Chromium + LibreOffice | Gotenberg's Chromium routes |
| Request format | `multipart/form-data` | JSON, or multipart (`index.html` + assets + `options`) |
| Auth | Optional basic auth; usually kept on a private network | API keys (`Authorization: Bearer` or `X-API-Key`) |
| HTML and URL to PDF | Yes | Yes (public URLs only) |
| Markdown route | Yes | No (convert Markdown to HTML first) |
| Office documents (DOCX, XLSX, PPTX) | Yes, via LibreOffice | No |
| Merge, split, PDF/A, PDF/UA | Yes | No |
| Screenshots (PNG/JPEG/WebP) | Yes | No |
| Webhooks / async | Yes | No (synchronous; optional 24-hour download link) |
| Scaling, patching, monitoring | You | Us |
| MCP server for AI agents | No | Yes, at `https://html-pdf.com/mcp` |
| Usage limits | Whatever you configure | 20 MB request, 30 s render, 120 requests/min |

## When self-hosting Gotenberg is the better choice

This section lists the cases where running your own Gotenberg wins. Run it yourself if any of these apply.

- **You need features beyond HTML to PDF.** Think Office conversion, merging, PDF/A, screenshots or webhooks. We don't expose those routes.
- **Your HTML must stay on your network**, or the pages you print are internal and not reachable from the internet.
- **You have high, steady volume** and already operate containers. Gotenberg on a couple of instances is cheap to run.
- **You want full control** over Chromium flags, fonts installed in the image, and timeouts.

Two guides get you there, [self-host Gotenberg with Docker](https://html-pdf.com/self-host-gotenberg-docker) and [deploy Gotenberg on Railway](https://html-pdf.com/deploy-gotenberg-railway).

## When the hosted version is the better choice

This section lists the cases where the hosted API saves you work.

- **You only need HTML or URL to PDF** and don't want another service to keep up, patch and size for memory spikes.
- **You call it from the public internet.** Self-hosted Gotenberg should not be exposed without auth and network rules, because a browser that renders arbitrary HTML can be pointed at internal addresses. We block private networks and handle keys for you.
- **Volume is low or irregular.** Credits never expire, so a quiet month costs nothing.
- **AI agents generate your PDFs.** Claude, ChatGPT, Cursor and others connect to the [PDF MCP server](https://html-pdf.com/pdf-mcp-server) with a URL and a key.

## Gotenberg form fields to html-pdf.com JSON

This table helps you translate an existing Gotenberg request. If you already call `/forms/chromium/convert/html`, most fields map one to one, just in snake_case JSON.

| Gotenberg | html-pdf.com |
|---|---|
| `files=@index.html` | `"html": "..."`, or multipart `index.html` |
| `/forms/chromium/convert/url` + `url` | `"url": "https://..."` |
| `paperWidth` / `paperHeight` | `"width"` / `"height"` (e.g. `"210mm"`), or `"format": "A4"` (A3 to A6, Letter, Legal, Tabloid) |
| `marginTop`, `marginRight`, `marginBottom`, `marginLeft` | `"margin": "10mm"` or `{"top", "right", "bottom", "left"}` |
| `landscape` | `"landscape"` |
| `printBackground` | `"print_background"` (defaults to `true` here; Gotenberg defaults to `false`) |
| `preferCssPageSize` | `"prefer_css_page_size"` |
| `scale` | `"scale"` |
| `nativePageRanges` | `"page_ranges"`, e.g. `"1-3, 5"` |
| `emulatedMediaType` | `"media"`: `"print"` or `"screen"` |
| `waitDelay` (e.g. `2s`) | `"wait_delay": 2` (seconds, 0 to 10) |
| `waitForExpression` | `"wait_for_expression"` |
| `header.html` / `footer.html` | `"header_html"` / `"footer_html"` (classes `pageNumber`, `totalPages`, `date`, `title`; needs a margin) |
| `Gotenberg-Output-Filename` header | `"filename"` |
| Extra asset files | Multipart: `index.html` + asset files + an `options` JSON field |

We also add a few options on top. These are `css` (extra stylesheet for `html` input), `max_pages` (fail long documents without being charged), and `response` (`binary`, `base64`, or `url` for a 24-hour link).

## Migrating a request

Here is the same request before and after the switch.

**Before (self-hosted Gotenberg):**

```bash
curl http://localhost:3000/forms/chromium/convert/html \
  -F files=@index.html \
  -F paperWidth=8.27 -F paperHeight=11.7 \
  -F marginTop=0.6 -F marginBottom=0.6 -F marginLeft=0.6 -F marginRight=0.6 \
  -F printBackground=true \
  -F waitForExpression="window.ready === true" \
  -F files=@footer.html \
  -o out.pdf
```

**After (html-pdf.com, multipart keeps your files):**

```bash
curl https://html-pdf.com/v1/pdf \
  -H "Authorization: Bearer $HTML_PDF_KEY" \
  -F "index.html=@index.html" \
  -F "logo.png=@logo.png" \
  -F 'options={"format":"A4","margin":"15mm","wait_for_expression":"window.ready === true","footer_html":"<div style=\"font-size:9px;width:100%;text-align:center\"><span class=\"pageNumber\"></span>/<span class=\"totalPages\"></span></div>"}' \
  -o out.pdf
```

**Or as JSON:**

```bash
curl -X POST https://html-pdf.com/v1/pdf \
  -H "Authorization: Bearer $HTML_PDF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>", "format": "A4", "margin": "15mm"}' \
  -o out.pdf
```

The output is the same Chromium rendering you get from Gotenberg, so templates that already look right there should look right here.

## Pricing

You pay per page, with no subscription. 1 credit = 1 PDF page. You get 100 free credits once, then packs run from $10 for 1,000 up to $250 for 50,000 ($0.005 per page).

Purchased credits never expire, auto top-up is optional, and failed renders are free. You can also sign up from the command line.

```bash
curl -X POST https://html-pdf.com/v1/signup -H "Content-Type: application/json" -d '{"email": "you@example.com"}'
# Then open the link we email you to confirm (adds the 100 free credits)
```

[Get a free API key](https://html-pdf.com/login) · [API docs](https://html-pdf.com/docs) · [Gotenberg in n8n](https://html-pdf.com/gotenberg-n8n) · [Guides](https://html-pdf.com/guides)

## FAQ

### Is html-pdf.com built on Gotenberg?

Yes. It runs Gotenberg's Chromium routes behind a JSON API with API keys and per-page billing, so the rendering matches a self-hosted Gotenberg.

### Is there a hosted Gotenberg API with a free tier?

Yes. html-pdf.com gives you 100 free credits once, with no card, and 1 credit = 1 PDF page. After that, packs cost $10 for 1,000 up to $250 for 50,000.

### Can html-pdf.com convert Office documents or merge PDFs like Gotenberg?

No. It only exposes HTML and URL to PDF. For DOCX, XLSX, PPTX, merging, PDF/A or screenshots, [self-host Gotenberg with Docker](https://html-pdf.com/self-host-gotenberg-docker).

### Do credits expire?

No. Purchased credits never expire, so a quiet month costs nothing, and failed renders are not charged.