API Reference
Complete reference for the SnapAPI REST API. Capture screenshots, generate PDFs, record videos, extract content, and analyze web pages with AI.
https://api.snapapi.pics
Authentication
All API requests (except health checks) require an API key sent via the x-api-key header. Get your key from the dashboard.
# Include your API key in every request curl https://api.snapapi.pics/v1/screenshot \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com"}'
Rate Limits
Rate limits are per API key. Check the response headers for your current status:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests per window |
| X-RateLimit-Remaining | Remaining requests in current window |
| X-RateLimit-Reset | Unix timestamp (ms) when the window resets |
| X-Request-Id | Unique request ID for debugging |
Error Handling
All errors return a JSON body with statusCode, error, and message fields.
| Code | Meaning |
|---|---|
| 400 | Bad Request โ invalid parameters or missing required fields |
| 401 | Unauthorized โ invalid or missing API key |
| 403 | Forbidden โ feature not available on your plan |
| 429 | Too Many Requests โ rate limit or quota exceeded |
| 503 | Service Unavailable โ server busy, retry with backoff |
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "Rate limit exceeded. Try again in 30s."
}
Take Screenshot
Capture a screenshot of any URL, raw HTML, or Markdown. Supports full-page capture, device emulation, dark mode, ad blocking, custom CSS/JS, caching, async processing, webhooks, and cloud storage.
๐ Body Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| url | string | URL to capture. One of url, html, or markdown required. | |
| html | string | Raw HTML to render (max 5MB) | |
| markdown | string | Markdown to render (max 1MB) | |
| format | string | png | Output format pngjpegwebpavifpdf |
| quality | integer | 80 | Image quality (1-100) |
| width | integer | 1280 | Viewport width (100-3840) |
| height | integer | 800 | Viewport height (100-2160) |
| device | string | Device preset (overrides width/height) iphone-15-proipad-pro-11pixel-8macbook-pro-16+20 more | |
| fullPage | boolean | false | Capture full scrollable page |
| darkMode | boolean | false | Force dark color scheme |
| blockAds | boolean | false | Block ads (Starter+) |
| blockCookieBanners | boolean | false | Block cookie consent banners |
| selector | string | CSS selector to capture a specific element | |
| delay | integer | 0 | Delay before capture in ms (0-30000) |
| css | string | Inject custom CSS (Starter+) | |
| javascript | string | Inject custom JS (Pro+) | |
| cache | boolean | false | Enable response caching (Pro+) |
| cacheTtl | integer | 86400 | Cache TTL in seconds (60-2592000) |
| async | boolean | false | Process asynchronously (returns job ID) |
| webhookUrl | string | Webhook URL for async completion | |
| responseType | string | binary | Response format binarybase64json |
| proxy | object | Custom proxy: { server, username, password } | |
| geolocation | object | Spoof geolocation: { latitude, longitude } | |
| timezone | string | Timezone override (e.g. "America/New_York") |
curl -X POST https://api.snapapi.pics/v1/screenshot \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "format": "png", "fullPage": true, "darkMode": true, "blockAds": true }' \ --output screenshot.png
const response = await fetch('https://api.snapapi.pics/v1/screenshot', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://example.com', format: 'png', fullPage: true, darkMode: true, blockAds: true }) }); const buffer = await response.arrayBuffer(); fs.writeFileSync('screenshot.png', Buffer.from(buffer));
import requests response = requests.post( "https://api.snapapi.pics/v1/screenshot", headers={"x-api-key": "YOUR_API_KEY"}, json={ "url": "https://example.com", "format": "png", "fullPage": True, "darkMode": True, "blockAds": True } ) with open("screenshot.png", "wb") as f: f.write(response.content)
package main import ( "bytes" "encoding/json" "net/http" "os" "io" ) func main() { body, _ := json.Marshal(map[string]any{ "url": "https://example.com", "format": "png", "fullPage": true, "darkMode": true, }) req, _ := http.NewRequest("POST", "https://api.snapapi.pics/v1/screenshot", bytes.NewBuffer(body)) req.Header.Set("x-api-key", "YOUR_API_KEY") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() f, _ := os.Create("screenshot.png") io.Copy(f, resp.Body) }
<?php $ch = curl_init('https://api.snapapi.pics/v1/screenshot'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'x-api-key: YOUR_API_KEY', 'Content-Type: application/json' ], CURLOPT_POSTFIELDS => json_encode([ 'url' => 'https://example.com', 'format' => 'png', 'fullPage' => true, 'darkMode' => true, ]) ]); $image = curl_exec($ch); file_put_contents('screenshot.png', $image);
Response
200 โ Returns image binary by default. With responseType: "json":
{
"success": true,
"cached": false,
"data": "iVBORw0KGgo...",
"format": "png",
"width": 1280,
"height": 800,
"fileSize": 245890,
"took": 1240
}
Take Screenshot (GET)
Simple GET endpoint for screenshots via query parameters. Perfect for embedding in <img> tags or quick testing.
๐ Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| urlREQUIRED | string | URL to capture | |
| format | string | png | png, jpeg, webp, avif, pdf |
| width | integer | 1280 | Viewport width |
| height | integer | 800 | Viewport height |
| full_page | string | false | "true" or "false" |
| dark_mode | string | false | "true" or "false" |
| block_ads | string | false | "true" or "false" |
| cache | string | false | "true" or "false" |
curl "https://api.snapapi.pics/v1/screenshot?url=https://example.com&format=png&full_page=true" \ -H "x-api-key: YOUR_API_KEY" \ --output screenshot.png
Batch Screenshots
Submit up to 100 URLs for batch processing. Returns a job ID to poll for results. Perfect for bulk captures like sitemaps or competitor monitoring.
๐ Body Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| urlsREQUIRED | string[] | Array of URLs to capture (1-100) | |
| format | string | png | Output format |
| width | integer | 1280 | Viewport width |
| fullPage | boolean | false | Full-page capture |
| webhookUrl | string | Webhook for completion notification |
curl -X POST https://api.snapapi.pics/v1/screenshot/batch \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "urls": [ "https://example.com", "https://google.com", "https://github.com" ], "format": "png", "fullPage": true }'
const res = await fetch('https://api.snapapi.pics/v1/screenshot/batch', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ urls: ['https://example.com', 'https://google.com'], format: 'png' }) }); const { jobId } = await res.json(); console.log(`Batch job: ${jobId}`);
response = requests.post( "https://api.snapapi.pics/v1/screenshot/batch", headers={"x-api-key": "YOUR_API_KEY"}, json={ "urls": ["https://example.com", "https://google.com"], "format": "png" } ) job_id = response.json()["jobId"]
Response โ 202 Accepted
{
"success": true,
"jobId": "batch_abc123",
"status": "pending",
"total": 3,
"message": "Batch job accepted"
}
Get Batch Job Status
Check the status and results of a batch screenshot job.
curl https://api.snapapi.pics/v1/screenshot/batch/batch_abc123 \
-H "x-api-key: YOUR_API_KEY"
Get Async Screenshot Status
Check the status of an async screenshot job. Pass includeData=true to get base64 data in the response.
curl "https://api.snapapi.pics/v1/screenshot/async/job_xyz?includeData=true" \ -H "x-api-key: YOUR_API_KEY"
Generate PDF
Generate a PDF from any URL or HTML. Supports custom page sizes, margins, headers/footers, landscape mode, and background printing.
๐ Key Parameters (in pdfOptions)
| Parameter | Type | Default | Description |
|---|---|---|---|
| url | string | URL to convert | |
| html | string | Raw HTML to convert | |
| pdfOptions.pageSize | string | a4 | a3a4a5letterlegaltabloid |
| pdfOptions.landscape | boolean | false | Landscape orientation |
| pdfOptions.printBackground | boolean | false | Include background graphics |
| pdfOptions.scale | number | 1 | Scale factor (0.1-2) |
| pdfOptions.marginTop | string | CSS margin (e.g. "1cm") |
curl -X POST https://api.snapapi.pics/v1/pdf \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "pdfOptions": { "pageSize": "a4", "printBackground": true, "landscape": false } }' \ --output page.pdf
const res = await fetch('https://api.snapapi.pics/v1/pdf', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://example.com', pdfOptions: { pageSize: 'a4', printBackground: true } }) }); const pdf = await res.arrayBuffer();
response = requests.post( "https://api.snapapi.pics/v1/pdf", headers={"x-api-key": "YOUR_API_KEY"}, json={ "url": "https://example.com", "pdfOptions": { "pageSize": "a4", "printBackground": True } } ) with open("page.pdf", "wb") as f: f.write(response.content)
Record Video
Record a video of any webpage with optional auto-scrolling. Outputs WebM, MP4, or GIF. Costs 5 credits per recording.
๐ Body Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| urlREQUIRED | string | URL to record | |
| format | string | webm | webmmp4gif |
| duration | integer | 5 | Duration in seconds (1-30) |
| width | integer | 1280 | Video width (320-1920) |
| height | integer | 720 | Video height (240-1080) |
| fps | integer | 25 | Frames per second (10-30) |
| scrolling | boolean | false | Auto-scroll during recording |
| scrollSpeed | integer | 100 | Scroll speed (px/frame) |
curl -X POST https://api.snapapi.pics/v1/video \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "format": "mp4", "duration": 10, "scrolling": true, "scrollSpeed": 150 }' \ --output recording.mp4
const res = await fetch('https://api.snapapi.pics/v1/video', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://example.com', format: 'mp4', duration: 10, scrolling: true }) });
Response โ 200 OK (with responseType: "json")
{
"success": true,
"format": "mp4",
"width": 1280,
"height": 720,
"duration": 10,
"fileSize": 1548320,
"took": 12450
}
Extract Web Content
Extract content from any webpage as HTML, text, markdown, article, links, images, metadata, or structured data. Optimized for LLM consumption โ feed web content directly to your AI pipeline.
๐ Body Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| urlREQUIRED | string | URL to extract from | |
| type | string | markdown | Extraction type htmltextmarkdownarticlelinksimagesmetadatastructured |
| selector | string | CSS selector to target specific element | |
| waitFor | string | Wait for selector before extracting | |
| maxLength | integer | Max content length (100-500000) | |
| cleanOutput | boolean | true | Clean/simplify extracted content |
| blockAds | boolean | false | Block ads before extraction |
curl -X POST https://api.snapapi.pics/v1/extract \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://blog.example.com/article", "type": "article", "blockAds": true, "cleanOutput": true }'
const res = await fetch('https://api.snapapi.pics/v1/extract', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://blog.example.com/article', type: 'markdown', maxLength: 50000 }) }); const { data } = await res.json();
response = requests.post( "https://api.snapapi.pics/v1/extract", headers={"x-api-key": "YOUR_API_KEY"}, json={ "url": "https://blog.example.com/article", "type": "structured" } ) data = response.json()["data"]
Response โ 200 OK
{
"success": true,
"type": "article",
"url": "https://blog.example.com/article",
"data": {
"title": "How to Build a Screenshot API",
"content": "# How to Build a Screenshot API\n\n...",
"author": "John Doe",
"publishedTime": "2026-01-15T10:00:00Z"
},
"responseTime": 890
}
Extract Web Content (GET)
Simple GET endpoint for content extraction via query parameters.
curl "https://api.snapapi.pics/v1/extract?url=https://example.com&type=markdown&max_length=10000" \ -H "x-api-key: YOUR_API_KEY"
AI-Powered Web Analysis
Analyze any webpage using AI with your own LLM API key (BYOK). Supports OpenAI and Anthropic. Get structured JSON output via jsonSchema. Perfect for competitive intelligence, compliance audits, and automated data extraction.
๐ Body Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| urlREQUIRED | string | URL to analyze | |
| promptREQUIRED | string | Analysis prompt for the LLM (max 5000 chars) | |
| apiKeyREQUIRED | string | Your own LLM provider API key | |
| provider | string | openai | openaianthropic |
| model | string | Model override (e.g. "gpt-4o", "claude-sonnet-4-20250514") | |
| jsonSchema | object | JSON Schema for structured output | |
| includeScreenshot | boolean | false | Send screenshot to LLM for visual analysis |
| maxContentLength | integer | 50000 | Max content sent to LLM |
curl -X POST https://api.snapapi.pics/v1/analyze \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://competitor.com/pricing", "prompt": "Extract all pricing plans with features", "provider": "openai", "apiKey": "sk-your-openai-key", "jsonSchema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } } } } } } } }'
const res = await fetch('https://api.snapapi.pics/v1/analyze', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://competitor.com/pricing', prompt: 'Extract all pricing plans', provider: 'openai', apiKey: 'sk-your-openai-key' }) }); const { analysis } = await res.json();
response = requests.post( "https://api.snapapi.pics/v1/analyze", headers={"x-api-key": "YOUR_API_KEY"}, json={ "url": "https://competitor.com/pricing", "prompt": "Extract all pricing plans", "provider": "anthropic", "apiKey": "sk-ant-...", "model": "claude-sonnet-4-20250514" } ) analysis = response.json()["analysis"]
Response โ 200 OK
{
"success": true,
"url": "https://competitor.com/pricing",
"metadata": {
"title": "Pricing - Competitor",
"description": "..."
},
"analysis": {
"plans": [
{ "name": "Pro", "price": "$19/mo", "features": ["..."] }
]
},
"provider": "openai",
"model": "gpt-4o",
"responseTime": 3240
}
Get API Usage
Check your current API usage, remaining quota, and reset time.
curl https://api.snapapi.pics/v1/usage \
-H "x-api-key: YOUR_API_KEY"
Response โ 200 OK
{
"used": 150,
"limit": 1000,
"remaining": 850,
"resetAt": "2026-03-01T00:00:00Z"
}
Ping
Simple health check. No authentication required.
curl https://api.snapapi.pics/v1/ping
Response
{ "status": "ok", "timestamp": 1708372800000 }
Health Check
Returns server health status. Use /health/detailed for database, Redis, and queue status.
curl https://api.snapapi.pics/health/detailed
Need help? support@snapapi.pics ยท Quick Start Guide ยท Interactive Playground