Complete reference for the PDFSnap REST API v1.0.0
The PDFSnap API lets you convert any public URL to a high-quality PDF or screenshot image. All requests require an API key and return JSON responses.
https://screenshot.soniyal.com/api/v1
application/json
POST for conversions, GET for status
All API requests require an API key. Pass it using the X-API-Key HTTP header.
X-API-Key: pk_live_your_api_key_here
Errors return a JSON object with success: false and an error object:
{
"success": false,
"error": {
"code": "INVALID_URL",
"message": "Invalid or blocked URL provided."
}
}
| HTTP Code | Error Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | Missing API key |
| 401 | INVALID_API_KEY | Invalid or revoked key |
| 403 | FORBIDDEN | Key lacks permission for this endpoint |
| 400 | MISSING_URL | url parameter not provided |
| 400 | INVALID_URL | URL is invalid or points to private host |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests per minute |
| 429 | DAILY_LIMIT_EXCEEDED | Daily quota reached |
| 500 | CONVERSION_FAILED | Conversion error |
| Plan | Requests/Day | Requests/Minute |
|---|---|---|
| FREE | 50 | 5 |
| PRO | 2,000 | 30 |
| ENTERPRISE | 50,000 | 100 |
Daily limits reset at midnight IST. Rate limit windows are per-minute per API key.
https://screenshot.soniyal.com/api/v1/pdf.php
Convert URL to PDF file
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | REQUIRED | — | The URL to convert (must be public http/https) |
page_size | string | optional | A4 | A4, A3, A5, Letter, Legal, Tabloid, Executive |
orientation | string | optional | Portrait | Portrait or Landscape |
margin_top | integer | optional | 10 | Top margin in mm (0–50) |
margin_right | integer | optional | 10 | Right margin in mm (0–50) |
margin_bottom | integer | optional | 10 | Bottom margin in mm (0–50) |
margin_left | integer | optional | 10 | Left margin in mm (0–50) |
zoom | float | optional | 1.0 | Zoom factor (0.1–3.0) |
javascript_delay | integer | optional | 0 | Wait N ms for JS to execute (0–10000) |
no_background | boolean | optional | false | Remove page background |
grayscale | boolean | optional | false | Convert to grayscale |
page_numbering | boolean | optional | false | Add page numbers in footer |
header_text | string | optional | — | Custom header text on each page |
footer_text | string | optional | — | Custom footer text on each page |
{
"success": true,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"data": {
"url": "https://screenshot.soniyal.com/uploads/pdf_abc123.pdf",
"filename": "pdf_abc123.pdf",
"size": 148340,
"size_human": "144.86 KB",
"pages": 3,
"type": "pdf",
"options": {
"page_size": "A4",
"orientation": "Portrait",
"margin_top": 10,
"margin_right": 10,
"margin_bottom": 10,
"margin_left": 10,
"zoom": 1.0
},
"expires_at": "2024-01-01T13:00:00+05:30"
},
"usage": {
"today": 3,
"limit": 50,
"remaining": 47
}
}
curl -X POST "https://screenshot.soniyal.com/api/v1/pdf.php" \
-H "X-API-Key: pk_live_your_api_key" \
-d "url=https://example.com/invoice/123" \
-d "page_size=A4" \
-d "orientation=Portrait" \
-d "margin_top=15" \
-d "margin_bottom=15" \
-d "page_numbering=1" \
-d "footer_text=Confidential Document"
https://screenshot.soniyal.com/api/v1/image.php
Screenshot via BYOK provider chain
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | REQUIRED | — | URL to screenshot (public http/https only) |
engine | string | optional | auto | auto tries BYOK chain then native. byok BYOK only. native wkhtmltoimage (Pro). Or a specific provider slug: apiflash, screenshotone, google_pagespeed, screenshotlayer, thumio, screenshotapi, abstractapi, screenshotmachine |
format | string | optional | png | Output format: png, jpg |
viewport_width | integer | optional | 1440 | Browser viewport width |
viewport_height | integer | optional | 900 | Browser viewport height |
output_width | integer | optional | 0 | Resize output to this width (0 = no resize) |
output_height | integer | optional | 0 | Resize output to this height (0 = auto) |
is_mobile | boolean | optional | false | Mobile viewport emulation |
is_full_page | boolean | optional | false | Capture full scrollable page |
is_dark_mode | boolean | optional | false | Request dark mode rendering |
device_scale_factor | float | optional | 1 | DPR — use 2 for Retina quality |
quality | integer | optional | 90 | JPEG quality (10–100) |
javascript_delay | integer | optional | 0 | Wait N ms for JS before capture |
block_ads | boolean | optional | false | Block ads (ScreenshotOne only) |
block_cookie_banners | boolean | optional | false | Block cookie banners (ScreenshotOne only) |
{
"success": true,
"request_id": "uuid-here",
"data": {
"url": "https://screenshot.soniyal.com/uploads/shot_apiflash_abc123.png",
"filename": "shot_apiflash_abc123.png",
"size": 245120,
"size_human": "239.38 KB",
"width": 1440,
"height": 900,
"format": "png",
"type": "screenshot",
"provider": "apiflash",
"provider_name": "ApiFlash",
"expires_at": "2024-01-01T13:00:00+05:30"
},
"usage": { "today": 4, "limit": 200, "remaining": 196, "plan": "free" }
}
# Auto — tries your provider chain in priority order
curl -X POST "https://screenshot.soniyal.com/api/v1/image.php" \
-H "X-API-Key: pk_live_your_key" \
-d "url=https://example.com" \
-d "engine=auto" \
-d "is_full_page=1" \
-d "is_mobile=0"
# Force specific provider
curl -X POST "https://screenshot.soniyal.com/api/v1/image.php" \
-H "X-API-Key: pk_live_your_key" \
-d "url=https://example.com" \
-d "engine=screenshotone" \
-d "block_ads=1&block_cookie_banners=1&is_dark_mode=1"
Screenshot API works on the Free plan when you bring your own provider keys. The system tries them in your configured priority order — if one fails or runs out of quota, it automatically moves to the next.
engine=auto (default) — it handles the rest.https://screenshot.soniyal.com/api/v1/url_to_png.php
Always PNG — all viewport/device options available
Same as image.php but output format is always png. Supports same engine param and all BYOK providers. Available on all plans including Free.
curl -X POST "https://screenshot.soniyal.com/api/v1/url_to_png.php" \
-H "X-API-Key: pk_live_your_api_key" \
-d "url=https://example.com" \
-d "viewport_width=1440" \
-d "viewport_height=900" \
-d "output_width=720" \
-d "output_height=450" \
-d "device_scale_factor=2" \
-d "is_full_page=1" \
-d "is_dark_mode=0" \
-d "is_mobile=0" \
-d "javascript_delay=500"
https://screenshot.soniyal.com/api/v1/dynamic_print.php
Overlay custom text on any image — certificates, cards, invoices
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
image_url | string | REQUIRED | — | Base image URL (PNG/JPG/GIF/WEBP) |
text1, text2... | string | REQUIRED | — | Text content for each layer (up to 20) |
textN_x | integer | optional | 0 | X position in pixels from left |
textN_y | integer | optional | 0 | Y position in pixels from top |
textN_position | string | optional | — | Shorthand: 120,230 (x,y) |
textN_size | integer | optional | 24 | Font size in pixels (6–500) |
textN_font | string | optional | arial | Font: arial, times, courier, ubuntu, roboto, poppins, opensans, montserrat, lato, dejavu (or any TTF filename in /fonts/) |
textN_color | string | optional | #000000 | Hex color code e.g. #FF5733 |
textN_bold | boolean | optional | 0 | Bold text |
textN_italic | boolean | optional | 0 | Italic text |
textN_align | string | optional | left | Text alignment: left, center, right |
textN_angle | float | optional | 0 | Rotation angle in degrees |
textN_opacity | integer | optional | 100 | Opacity 0–100 (%) |
textN_shadow | boolean | optional | 0 | Drop shadow effect |
textN_stroke | boolean | optional | 0 | Text outline/stroke |
textN_stroke_color | string | optional | #ffffff | Stroke color |
textN_stroke_width | integer | optional | 2 | Stroke width 1–10 px |
textN_max_width | integer | optional | 0 | Auto word-wrap at this width (0=none) |
textN_line_height | float | optional | 1.2 | Line height multiplier |
output_format | string | optional | png | Output: png or jpg |
output_quality | integer | optional | 90 | JPG quality (10–100) |
output_width | integer | optional | 0 | Resize final image width (0=keep original) |
output_height | integer | optional | 0 | Resize final image height |
curl -X POST "https://screenshot.soniyal.com/api/v1/dynamic_print.php" \
-H "X-API-Key: pk_live_your_key" \
-d "image_url=https://example.com/certificate-template.png" \
-d "text1=Preet Singh" \
-d "text1_x=600" \
-d "text1_y=420" \
-d "text1_size=48" \
-d "text1_font=times_bold" \
-d "text1_color=%23333333" \
-d "text1_align=center" \
-d "text1_shadow=1" \
-d "text2=Father: Gurpreet Singh" \
-d "text2_x=600" \
-d "text2_y=490" \
-d "text2_size=28" \
-d "text2_font=arial" \
-d "text2_color=%23555555" \
-d "text2_align=center" \
-d "text3=Date: 2 May 2026" \
-d "text3_x=600" \
-d "text3_y=550" \
-d "text3_size=20" \
-d "text3_font=arial" \
-d "text3_color=%23888888" \
-d "text3_align=center" \
-d "output_format=png"
<?php
$students = [
['name' => 'Preet Singh', 'father' => 'Gurpreet Singh', 'date' => '2026-05-02'],
['name' => 'Deepam Jain', 'father' => 'Rajesh Jain', 'date' => '2026-05-02'],
// ... more students
];
$apiKey = 'pk_live_your_key';
$templateUrl = 'https://yoursite.com/cert-template.png';
$endpoint = 'https://screenshot.soniyal.com/api/v1/dynamic_print.php';
foreach ($students as $student) {
$params = http_build_query([
'image_url' => $templateUrl,
'text1' => $student['name'],
'text1_x' => 600, 'text1_y' => 420,
'text1_size' => 48, 'text1_font' => 'times_bold',
'text1_color' => '#333333', 'text1_align' => 'center',
'text1_shadow' => 1,
'text2' => 'Father: ' . $student['father'],
'text2_x' => 600, 'text2_y' => 490,
'text2_size' => 28, 'text2_font' => 'arial',
'text2_color' => '#555555', 'text2_align' => 'center',
'text3' => 'Date: ' . $student['date'],
'text3_x' => 600, 'text3_y' => 550,
'text3_size' => 20, 'text3_font' => 'arial',
'text3_color' => '#888888', 'text3_align' => 'center',
'output_format' => 'png',
]);
$ctx = stream_context_create([
'http' => [
'method' => 'POST',
'header' => "X-API-Key: {$apiKey}\r\nContent-Type: application/x-www-form-urlencoded",
'content' => $params,
'timeout' => 30,
]
]);
$res = json_decode(file_get_contents($endpoint, false, $ctx), true);
$pdfUrl = $res['data']['url'];
// Save or email certificate
echo "Certificate for {$student['name']}: {$pdfUrl}\n";
}
?>
https://screenshot.soniyal.com/api/v1/status.php
Check account & usage
curl "https://screenshot.soniyal.com/api/v1/status.php" \
-H "X-API-Key: pk_live_your_api_key"
<?php
function convertInvoiceToPdf(string $invoiceUrl, string $apiKey): ?string {
$params = http_build_query([
'url' => $invoiceUrl,
'page_size' => 'A4',
'orientation' => 'Portrait',
'margin_top' => 15,
'margin_right' => 15,
'margin_bottom' => 20,
'margin_left' => 15,
'page_numbering' => 1,
'footer_text' => 'Generated by MyApp',
]);
$context = stream_context_create([
'http' => [
'method' => 'POST',
'header' => "X-API-Key: {$apiKey}\r\nContent-Type: application/x-www-form-urlencoded",
'content' => $params,
'timeout' => 60,
]
]);
$response = file_get_contents('https://screenshot.soniyal.com/api/v1/pdf.php', false, $context);
if (!$response) return null;
$data = json_decode($response, true);
if (!$data['success']) {
error_log('PDF error: ' . $data['error']['message']);
return null;
}
return $data['data']['url']; // Download URL
}
// Usage:
$pdfUrl = convertInvoiceToPdf('https://myapp.com/invoices/INV-001', 'pk_live_xxx');
header('Location: ' . $pdfUrl); // Redirect user to download
?>
curl -X POST "https://screenshot.soniyal.com/api/v1/image.php" \
-H "X-API-Key: pk_live_your_api_key" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "url=https://github.com" \
-d "width=1280" \
-d "format=jpg" \
-d "quality=90" \
-d "full_page=0" | python3 -m json.tool
async function urlToPdf(url, apiKey) {
const params = new URLSearchParams({
url,
page_size: 'A4',
orientation: 'Portrait',
margin_top: 10,
margin_bottom: 10,
});
const response = await fetch('https://screenshot.soniyal.com/api/v1/pdf.php', {
method: 'POST',
headers: {
'X-API-Key': apiKey,
'Content-Type': 'application/x-www-form-urlencoded',
},
body: params.toString(),
});
const data = await response.json();
if (!data.success) throw new Error(data.error.message);
return data.data.url; // PDF download URL
}
// Usage
urlToPdf('https://example.com', 'pk_live_xxx')
.then(pdfUrl => window.open(pdfUrl, '_blank'))
.catch(console.error);
import requests
def url_to_pdf(url: str, api_key: str) -> str:
response = requests.post(
'https://screenshot.soniyal.com/api/v1/pdf.php',
headers={'X-API-Key': api_key},
data={
'url': url,
'page_size': 'A4',
'orientation': 'Portrait',
'margin_top': 15,
'page_numbering': '1',
},
timeout=60
)
response.raise_for_status()
data = response.json()
if not data['success']:
raise Exception(data['error']['message'])
return data['data']['url']
# Usage
pdf_url = url_to_pdf('https://invoice.example.com/123', 'pk_live_xxx')
print(f'PDF ready: {pdf_url}')