# Screenshot (HTML) API

> Render HTML you send to a JPEG, PNG or PDF.

Stages the markup you post on the API host, renders it in headless Chromium at the requested viewport and saves the capture. The staged page is deleted as soon as the capture is done; the capture itself stays at the returned URL under `/screen/html/s/`.

- **Endpoint:** `POST https://api.zactonz.com/screen/html/`
- **Category:** Media
- **Version:** 1
- **Status:** stable
- **Authentication:** `Authorization: Bearer YOUR_API_KEY`
- **Reference page:** https://developers.zactonz.com/apis/screenshot-html/

## Parameters

Send parameters as `application/x-www-form-urlencoded` form fields in the request body.

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `html` | string | yes |  | The HTML document to render, up to 2 MB. Larger bodies are rejected with `413`. |
| `width` | integer | no | `1280` | Viewport width in pixels, 200 to 3840. Values outside the range are clamped. Default 1280. |
| `height` | integer | no | `1024` | Viewport height in pixels, 150 to 4320. Values outside the range are clamped. Default 1024. |
| `format` | enum | no | `jpeg` | Output type. `jpeg` (default), `png`, `webp`, or `pdf` for a paged document. Allowed values: `jpeg`, `png`, `webp`, `pdf`. |
| `quality` | integer | no | `100` | JPEG quality from 1 to 100. Default 100. Ignored for other formats. |

## Example request

```bash
curl -X POST "https://api.zactonz.com/screen/html/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "html=<html><body><h1>Invoice #1042</h1></body></html>" \
  --data-urlencode "width=1280" \
  --data-urlencode "height=1024" \
  --data-urlencode "format=jpeg" \
  --data-urlencode "quality=100"
```

## Response

Metadata and the URL of the saved capture.

| Field | Type | Description |
|---|---|---|
| `status` | string | `"200"` on success (a string). See status codes below. |
| `width` | integer | Viewport width that was used. |
| `height` | integer | Viewport height that was used. |
| `data` | string | Absolute URL of the saved image or PDF, or an error message. |

```json
{
    "status": "200",
    "width": 1280,
    "height": 1024,
    "data": "https://api.zactonz.com/screen/html/s/Pm2Lq_147xVt8Nc3Rz0Kw.jpeg"
}
```

## Status codes

The outcome is reported in the JSON `status` field. General rules: https://developers.zactonz.com/apis/errors.md

| status | Meaning | Description |
|---|---|---|
| `200` | OK | The capture was saved. Note that this endpoint returns `status` as a string. |
| `400` | Bad request | `html` was missing, or `quality` was `0` for JPEG output. |
| `413` | Too large | The HTML body exceeds 2 MB. |
| `502` | Not rendered | The browser could not load or capture the page within the time limit. |

## Notes

Send a complete document (`<html>…</html>`). Relative URLs inside it will not resolve, so use absolute URLs for images, fonts and stylesheets. PDF output uses Chromium's default page size and prints without backgrounds.