# File formats

Choose the file with `format`. Every format costs the same.

## The four formats

| Format | Good for | Notes |
| --- | --- | --- |
| `png` | Sharp text and interfaces. The default. | No loss. Larger files. |
| `jpeg` | Photos and long pages. | Smaller files. Set `quality`. `jpg` is accepted too. |
| `webp` | The smallest images. | Set `quality`. |
| `pdf` | A document to keep, print or send. | Always the whole page. |

**A smaller image**

```bash
curl "https://api.localscreenshot.com/v1/screenshot?url=https://www.wikipedia.org&format=webp&quality=70" \
  -H "Authorization: Bearer $LOCALSCREENSHOT_API_KEY" \
  -o shot.webp
```

## Quality

`quality` goes from 1 to 100 and applies to `jpeg` and `webp`. It is ignored for `png` and `pdf`. Without it, we use 80.

## Scale the image down

`max_width` scales the image down to a width in pixels, keeping its proportions. It is useful to keep an image small for a vision model. The MCP server uses 1,568 pixels unless you say otherwise.

## PDF

A `pdf` holds the whole page, on as many sheets as it needs.

- It cannot be combined with `selector` or `max_width`.
- `image.pages` gives the number of pages. `image.width` and `image.height` are `null`.
- It is sent as a file to download, never shown inside a page.

**Save a page as a PDF**

```bash
curl "https://api.localscreenshot.com/v1/screenshot?url=https://www.wikipedia.org&format=pdf" \
  -H "Authorization: Bearer $LOCALSCREENSHOT_API_KEY" \
  -o page.pdf
```

## What you get back

By default the answer is the file itself, with its type in `Content-Type`. With `response=json` you get a description of the file and a link to it.

| Format | Content-Type |
| --- | --- |
| `png` | `image/png` |
| `jpeg` | `image/jpeg` |
| `webp` | `image/webp` |
| `pdf` | `application/pdf` |

**The image field, for a PDF**

```json
{
  "url": "https://api.localscreenshot.com/v1/screenshots/01JABC.../image?expires=...&signature=...",
  "mime": "application/pdf",
  "bytes": 318422,
  "width": null,
  "height": null,
  "pages": 3,
  "sha256": "9c1d0f6ab2e4...",
  "truncated": false,
  "available_until": "2026-10-15T10:47:02Z"
}
```

## Very long pages

- `image.truncated` is `true` when the page was longer than one file can hold: the end is missing.
- When the picture would be too large to produce at all, the screenshot fails with `image_too_large`. Use a smaller viewport, or turn off `full_page`.
- `image.sha256` is the fingerprint of the file. Use it to check a download.