API 04 · Requires worker
Screenshot API
Captures a page in headless Chromium driven over the Chrome DevTools Protocol from Rust. Supports desktop (1440×900) and mobile (390×844 @2x) presets, custom viewports, full-page capture and PNG/JPEG/WebP output. All browser traffic passes through the worker's Rust egress proxy, which blocks private and metadata addresses.
POST https://dev.itsozy.lol/api/v1/screenshotRequires worker. Chromium cannot run reliably inside Vercel functions; captures run on the optional worker. Without it this endpoint returns 503 worker_unavailable.
Authentication
Send Authorization: Bearer ozy_… with an API key that includes the screenshot permission (or *). Signed-in dashboard sessions work in the playground. Each call costs 10 units.
Parameters
| Name | Type | Description | |
|---|---|---|---|
url | string | required | Public http(s) URL |
device | string | optional | desktop (default) or mobile |
width / height | integer | optional | Custom viewport, 320-2560 × 240-2560 |
full_page | boolean | optional | Capture the full scroll height |
format | string | optional | png (default), jpeg or webp |
quality | integer | optional | 1-100 for jpeg/webp (default 80) |
Example request
curl -X POST https://dev.itsozy.lol/api/v1/screenshot \
-H "Authorization: Bearer $OZY_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "device": "mobile", "full_page": true, "format": "webp"}'Example response (illustrative)
{
"bytes": 48211,
"final_url": "https://example.com/",
"format": "webp",
"height": 1688,
"image_base64": "UklGR…",
"width": 390
}Errors
Errors use one envelope: {"error": {"code": "…", "message": "…"}}.
| Status | Code | Meaning |
|---|---|---|
| 503 | worker_unavailable | The optional self-hosted worker is not configured on this deployment |
| 502 | worker_failed | The worker could not complete the job |
| 400 | invalid_input | A parameter is missing or invalid |
| 401 | unauthorized | No valid API key or session |
| 403 | permission_denied | The key does not include this API's permission |
| 429 | quota_exceeded | Free-tier quota reached (20 units/min, 100 units/day) |
| 503 | database_unavailable | Persistent storage is temporarily unavailable |
Rate limits
20 units per minute and 100 units per day per account; outbound fetches to the same host are spaced at least one second apart. Exceeding a limit returns 429.