# Pearl REST API capture preview images from channels, inputs, and outputs

The API can return a still preview image for a channel, an input, or an HDMI output. These endpoints return image data directly rather than a JSON envelope, which makes them useful for confidence monitoring and dashboards.

*Applies to: Pearl-2, Pearl Mini, Pearl Nexus, Pearl Nano.*

| Method and path | Returns |
| --- | --- |
| `GET /channels/{cid}/preview` | Preview of a channel's program output |
| `GET /inputs/{sid}/preview` | Preview of a single input source |
| `GET /outputs/{did}/preview` | Preview of what an HDMI output is showing |

**Parameters.**

| Parameter | Applies to | Notes |
| --- | --- | --- |
| `resolution` | All three | `widthxheight` (`1920x1080`), a width alone (`1920`), or `auto`. Supplying only a width scales the image to that width and preserves the original aspect ratio |
| `keep_aspect_ratio` | Channels and inputs | Default `true` |
| `format` | All three | `jpg` or `png`. Default `jpg`. JPG is the recommended format |

The default resolution is `auto` for channel and input previews, and `1920x1080` for output previews.

```
GET /api/v2.0/channels/1/preview?resolution=640&format=jpg
```

The response is `image/jpeg` or `image/png` binary data. A request naming a channel, input, or output that does not exist returns 404 with a JSON error body.

Because preview images are generated on demand by the device, poll them at a modest rate in monitoring tools rather than at frame rate.

> product: pearl-family · topic: layout · source: pearl-rest-api.md · updated: Oct 7, 2026