How to Return a Screenshot as a PDF with ScreenshotAPI.net
Return a webpage screenshot as a PDF with ScreenshotAPI.net. Learn the request options, save the response, and troubleshoot page size, ranges, and dynamic content.
To return a screenshot as a PDF with ScreenshotAPI.net, send a GET request to its v3 screenshot endpoint with your API token, the target page URL, and file_type=pdf. Save the response as a binary PDF file. For example, request an A4 document by also setting pdf_options[format]=A4.
curl --get 'https://shot.screenshotapi.net/v3/screenshot' \
--data-urlencode 'token=YOUR_API_KEY' \
--data-urlencode 'url=https://example.com' \
--data-urlencode 'file_type=pdf' \
--data-urlencode 'pdf_options[format]=A4' \
--output page.pdfThe API key is a secret: keep it out of source control and public client-side code. The request and PDF settings below follow ScreenshotAPI.net’s API documentation and PDF reference. Confirm current parameter syntax in the reference before shipping production code.
1. Choose the PDF page shape
Set the page dimensions for the intended use. ScreenshotAPI.net documents this priority:
- Standard format: Set a paper format such as A4 when the output should print or share as conventional pages.
- Explicit dimensions: If no standard format is supplied,
widthandheightdetermine page dimensions. - Continuous page: If neither format nor dimensions are specified, the PDF is one long page without page breaks.
Standard paper is usually easier to print and read page by page. A continuous PDF can suit a long dashboard or article when preserving one flowing capture matters more than conventional pagination.
2. Configure page range, orientation, and print styling
Use page_range to retain an interval from a multi-page PDF. Its documented form is start-end, using positive page numbers, with the start no greater than the end. For example, 2-6 selects five pages. Check that the rendered document actually has those pages; a range beyond the available pages cannot provide the intended section.
The PDF examples also include landscape orientation, print media, and print backgrounds. Choose these based on the source: landscape can help wide tables, print media can use a site’s print stylesheet, and print backgrounds can preserve colored sections. These are rendering choices, not universal defaults. Validate the result for your particular page.
3. Runnable examples
cURL
curl --get 'https://shot.screenshotapi.net/v3/screenshot' \
--data-urlencode 'token=YOUR_API_KEY' \
--data-urlencode 'url=https://example.com' \
--data-urlencode 'file_type=pdf' \
--data-urlencode 'pdf_options[format]=A4' \
--output page.pdf--data-urlencode encodes the destination URL and option values for the query string. The output flag writes the response body to a file instead of printing binary bytes in the terminal.
Python
import requests
endpoint = "https://shot.screenshotapi.net/v3/screenshot"
params = {
"token": "YOUR_API_KEY",
"url": "https://example.com",
"file_type": "pdf",
"pdf_options[format]": "A4",
}
with requests.get(endpoint, params=params, timeout=90, stream=True) as response:
response.raise_for_status()
with open("page.pdf", "wb") as pdf:
for chunk in response.iter_content(chunk_size=64 * 1024):
if chunk:
pdf.write(chunk)Install the dependency with python -m pip install requests. Binary mode (wb) is essential; text mode can corrupt the PDF. Streaming avoids keeping the entire document in memory.
Node.js
const endpoint = new URL("https://shot.screenshotapi.net/v3/screenshot");
endpoint.searchParams.set("token", "YOUR_API_KEY");
endpoint.searchParams.set("url", "https://example.com");
endpoint.searchParams.set("file_type", "pdf");
endpoint.searchParams.set("pdf_options[format]", "A4");
const response = await fetch(endpoint);
if (!response.ok) {
throw new Error(`Screenshot request failed: ${response.status} ${await response.text()}`);
}
const pdf = Buffer.from(await response.arrayBuffer());
const { writeFile } = await import("node:fs/promises");
await writeFile("page.pdf", pdf);This uses the built-in fetch and file APIs in modern Node.js. For large documents, use a streaming response-to-file approach to limit memory use.
4. Tune the render for the page
| Need | Setting or approach |
|---|---|
| Printed pages | Set a standard format, such as A4. |
| Custom page dimensions | Supply width and height when no standard format is used. |
| Only part of a multi-page PDF | Set page_range in start-end form. |
| Wide source content | Try landscape orientation and inspect the resulting layout. |
| Page relies on print styles | Try print media and compare with the default screen render. |
| Background colors or images matter | Enable print backgrounds. |
| Content appears after page load | Use a documented delay, lazy-loading option, or injected JavaScript/CSS as appropriate. |
| Render supplied markup | Use custom_html; it replaces URL fetching and works with PDF options. |
For longer HTML, use POST as the documentation recommends; a GET URL has practical length limits. With custom_html, do not expect the supplied url to be fetched: the HTML is the render input. Dynamic-content controls can help prepare a page, but cannot guarantee correct output or bypass access restrictions.
5. Or skip the browser setup
ScreenshotNeo provides a one-request screenshot API that can return PDF as well as image formats. Its API supports PDF settings including paper size, margins, landscape, and page ranges. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-d format=pdf \
-o page.pdfScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo free: 1,000 screenshots a month, no card required.
6. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Response is not a PDF | The file type was omitted or misspelled, or the server returned an error body. | Set file_type=pdf; check HTTP status and response content before saving. |
| PDF file is unreadable | Binary content was handled as text or a failed response was saved as a PDF. | Write bytes in binary mode, call raise_for_status() or check response.ok, and inspect errors before writing. |
| Unexpectedly long single page | No format or width/height was specified. | Choose a standard paper format or specify dimensions. |
| Content is clipped or too small | Page shape or orientation does not fit the source. | Try landscape or adjust the documented format/dimensions, then inspect the PDF. |
| Selected pages are missing | The requested page range is invalid or outside the generated page count. | Use positive page numbers, ensure start is at most end, and select a range within the actual document. |
| Late content is absent | The page renders asynchronously or loads images lazily. | Try delay, lazy loading, or injected JavaScript/CSS; check whether access restrictions prevent the content loading. |
| Request fails with supplied HTML | Long markup may exceed URL length limits, or URL and HTML inputs are being confused. | Use POST for longer markup and remember custom_html replaces fetching the URL. |
7. Performance, reliability, and cost
PDF generation time depends on page loading and rendering work; no universal duration is established here. Set a client timeout suitable for your application, handle non-success responses, and avoid retrying indefinitely. A retry may repeat a render request, so apply your own request limits and log the status and error body without exposing the API token.
For large PDFs, stream the response to disk or object storage rather than buffering it all in memory. If the output is unexpectedly empty or incomplete, distinguish a successful HTTP transfer from a successful page render and inspect the returned status and document. ScreenshotAPI.net pricing and service guarantees are not established by the cited documentation, so check its current official terms for cost and reliability commitments.
FAQ
Can I convert supplied HTML instead of a live webpage?
Yes. The PDF reference documents custom_html as raw HTML input that overrides URL fetching. Use POST when the markup is long.
Does choosing A4 guarantee the page will fit?
No. It sets the paper format; wide or unusually laid-out content may need landscape or other dimensions. Review the resulting pages.
Can I include only selected PDF pages?
Yes. Set page_range as a positive start and end page, such as 2-6.
Will a delay make every dynamic site render correctly?
No. Delay and related render controls can help with content that appears later, but the page’s behavior and access rules still determine what can be captured.
