Getting Started with SnapService
Learn how to integrate our automated screenshot API into your applications. SnapService provides high-fidelity previews with intelligent caching.
API Endpoints
Returns PNG image bytes directly when cached.
Returns HTTP 302 redirect to the cached static image path.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| url | string | The target URL (must start with https://) |
| width | number | Viewport width (default: 480) |
| height | number | Viewport height (default: 270) |
Allowed Resolutions
For security and performance, only specific viewport resolutions are supported. If only one dimension is provided, the API will automatically infer the other. If no match is found, it will default to 480x270.
Response Behavior
Success
Returns the PNG image binary directly from cache on /api/screenshot.
Redirect
On /api/raw, cached images are returned as a redirect to a static PNG URL.
Accepted (Processing)
The screenshot is being generated in the background. A placeholder image is returned with aRefresh header.
Quick Example
The most efficient way to use the API is to check if the response contains a Refresh header.
HTTP/1.1 202 Accepted Content-Type: image/png Refresh: 5
/**
* Fetches a screenshot and handles the asynchronous processing
* by respecting the 'Refresh' header.
*
* @param {string} url - The URL to capture
* @param {HTMLImageElement} imgElement - The image element to update
*/
async function captureWithPolling(url, imgElement) {
const apiEndpoint = `${origin}/api/screenshot?url=${encodeURIComponent(url)}`;
// Initial request to trigger capture
imgElement.src = apiEndpoint;
// Polling function
const poll = async () => {
try {
const response = await fetch(apiEndpoint, { method: 'HEAD' });
// Check for the 'Refresh' header (usually set to '5' for 5 seconds)
const refreshHeader = response.headers.get('Refresh');
if (refreshHeader) {
console.log(`Screenshot processing... retrying in ${refreshHeader}s`);
setTimeout(poll, parseInt(refreshHeader) * 1000);
} else {
console.log("Screenshot ready!");
imgElement.src = apiEndpoint;
}
} catch (err) {
console.error("Polling failed:", err);
}
};
// Start polling if needed (initially it might already be 200 or 202)
// We'll wait a bit before first poll to let the initial request settle
setTimeout(poll, 2000);
}