How to Return a PDF Instead of a PNG from ScreenshotOne

To return a PDF instead of a PNG from ScreenshotOne, set the request parameter format=pdf. With the default response_type=by_format, the response body contains the selected format as binary data, so save or stream it as a PDF rather than treating it as an image.

For a full-page-style PDF with background graphics, start with format=pdf, media_type=screen, pdf_print_background=true, and pdf_fit_one_page=true. Set paper size and margins explicitly when they matter to your layout.

1. Make the smallest change

Keep your existing ScreenshotOne request and change its format value from png to pdf. For example, the endpoint can be called with GET query parameters or a POST JSON body. Use HTTPS.

GET https://api.screenshotone.com/take?access_key=YOUR_ACCESS_KEY&url=https%3A%2F%2Fexample.com&format=pdf

In an application, pass the URL as a properly encoded query parameter or use a request library that encodes parameters for you. Do not assume a PDF response is image data: write the raw response bytes to a .pdf file.

2. Complete runnable examples

cURL

curl -G 'https://api.screenshotone.com/take' \
  --data-urlencode 'access_key=YOUR_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'format=pdf' \
  -o page.pdf

To request a one-page-style PDF with screen media and background graphics, add the PDF options:

curl -G 'https://api.screenshotone.com/take' \
  --data-urlencode 'access_key=YOUR_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'format=pdf' \
  --data-urlencode 'media_type=screen' \
  --data-urlencode 'pdf_print_background=true' \
  --data-urlencode 'pdf_fit_one_page=true' \
  --data-urlencode 'pdf_paper_format=A4' \
  --data-urlencode 'pdf_margin=0' \
  -o page.pdf

Python

import requests

response = requests.get(
    "https://api.screenshotone.com/take",
    params={
        "access_key": "YOUR_ACCESS_KEY",
        "url": "https://example.com",
        "format": "pdf",
        "media_type": "screen",
        "pdf_print_background": "true",
        "pdf_fit_one_page": "true",
        "pdf_paper_format": "A4",
        "pdf_margin": "0",
    },
    timeout=120,
)
response.raise_for_status()

with open("page.pdf", "wb") as pdf_file:
    pdf_file.write(response.content)

Use wb so Python writes the bytes without text encoding or newline conversion. The timeout shown is an application choice; tune it for your own request and workload.

Node.js

const params = new URLSearchParams({
  access_key: 'YOUR_ACCESS_KEY',
  url: 'https://example.com',
  format: 'pdf',
  media_type: 'screen',
  pdf_print_background: 'true',
  pdf_fit_one_page: 'true',
  pdf_paper_format: 'A4',
  pdf_margin: '0',
});

const response = await fetch(`https://api.screenshotone.com/take?${params}`);
if (!response.ok) {
  throw new Error(`ScreenshotOne returned HTTP ${response.status}: ${await response.text()}`);
}

const pdfBytes = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(({ writeFile }) => writeFile('page.pdf', pdfBytes));

For POST requests, send the same options in a JSON body. POST is especially useful when sending large HTML or Markdown input, which should not be placed in a long URL.

3. Choose PDF layout options

Option	What it controls	Practical guidance
`format=pdf`	Selects PDF output.	Required for this use case.
`media_type=screen`	Requests screen media styling.	Useful when the website’s print stylesheet hides or rearranges content. Omit or change it if print styling is desired.
`pdf_print_background=true`	Includes background graphics.	Defaults to false; enable it for colored backgrounds and background images that should appear in the PDF.
`pdf_fit_one_page=true`	Attempts to fit the website on one page.	Defaults to false. Use for a single, full-page-style document; very tall pages may become difficult to read when scaled down.
`pdf_landscape=true`	Sets landscape orientation.	Use when the page or data table is wider than it is tall.
`pdf_paper_format`	Chooses a paper size.	Specify it when output dimensions matter. The options documentation is inconsistent about whether the default is Letter or A4, so do not rely on the default.
`pdf_margin`	Sets the overall page margin.	Specify a value that suits the content and printing needs.
Per-side margin overrides	Set individual margins for each page edge.	Use when top, bottom, left, and right whitespace need different values; consult the official options reference for exact parameter names and accepted units.

The one-page and background options were added for PDF rendering in ScreenshotOne’s changelog. The combined starting configuration is format=pdf&media_type=screen&pdf_print_background=true&pdf_fit_one_page=true. Add paper and margin settings only when you need to control the printed page geometry.

4. Handle the response correctly

With the documented default response_type=by_format, ScreenshotOne returns the requested format directly as binary data and sets the response content type for that format. For PDF, consume the response as bytes and store it with a .pdf filename. Do not parse it as JSON or decode it as UTF-8.

Other response types, including empty and json, are available. If your existing integration changes response_type, review its response handling before switching formats. The direct file examples above assume by_format.

5. Troubleshoot common problems

Symptom	Likely cause	Fix
The response is still a PNG.	The request still sends `format=png`, a wrapper overrides the value, or the request parameters were not encoded as intended.	Inspect the final URL or POST body and confirm `format=pdf` reaches the API.
The saved PDF will not open.	The response was written in text mode, truncated, or contains an API error response rather than a PDF.	Write raw bytes (`wb` in Python; `arrayBuffer()` in Node.js). Check the HTTP status and content type before saving.
Your code reports a JSON parsing error.	The request expects JSON while the default response is the binary file itself.	Read the response as bytes for direct PDF output. Parse JSON only when deliberately using a JSON response type or handling a JSON error.
Background colors or images are missing.	`pdf_print_background` is false by default.	Set `pdf_print_background=true`.
The PDF uses unexpected pagination or scale.	`pdf_fit_one_page` is off, or fitting a tall page to one sheet makes the result too small.	Enable one-page fitting for a single-sheet result; leave it off when readable multi-page output is preferable. Set paper size and margins explicitly.
Content looks like a print layout rather than the website.	The page’s print stylesheet changes the layout.	Set `media_type=screen` if the desired output should follow screen styling.
The API returns an error instead of a document.	Possible causes include internal failures, invalid options, or service limits.	Check the HTTP status and error response, verify option names and values against the official docs, and correct the request or address the reported limit before retrying.

6. Reliability, performance, and cost considerations

Keep the binary response intact. Stream or buffer bytes, and only mark a result successful after the HTTP response is successful and the file has been written.
Use explicit output settings. Paper size defaults are described inconsistently in the options page, so specify paper format when predictable dimensions are required.
Choose fit-to-one-page deliberately. It avoids page breaks by scaling content, but that can reduce legibility on long pages. Compare the intended page size and content density.
Set timeouts at the caller. A page capture can take longer than a simple metadata request. Use a timeout appropriate to your application and report timeouts separately from invalid-request errors.
Protect the access key. Keep credentials out of public client-side code and avoid logging full request URLs containing secrets.
Cost and limits depend on your ScreenshotOne account and plan. The reviewed documentation establishes request options and errors related to limits, but does not provide pricing or a per-request cost here. Check your account’s current plan and usage information before scaling a batch workflow.

7. Or skip the browser setup

ScreenshotNeo returns a PDF with a single GET request. Its API documentation covers the available options.

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.pdf

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

8. FAQ

Can I keep using GET?

Yes. ScreenshotOne accepts GET query parameters as well as POST JSON bodies. Use POST when the input payload is large.

Does one-page fit guarantee a readable PDF?

No. It attempts to fit the website onto one page; a very long page may be scaled down substantially. Use normal pagination when legibility is more important than a single sheet.

Do I need to convert a PNG to PDF afterward?

No. Request format=pdf to receive PDF output directly.

Sources

ScreenshotOne options reference for supported formats and PDF settings.
ScreenshotOne getting started guide for request methods, response behavior, HTTPS, and errors.
ScreenshotOne changelog, February 2, 2024 entry for one-page PDF fitting and background graphics.