Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsCalling a screenshot API from Python is an authenticated HTTP request: send the target URL and provider-supported capture options, check the HTTP status, then handle the response in the format that provider documents. Some APIs return image bytes to save directly; others return JSON with a screenshot URL. The methods, parameter names, and authentication schemes are not interchangeable.
How a Python screenshot API call works
- Choose an API and read its current endpoint documentation.
- Get an API key and store it outside your source code, such as in an environment variable.
- Send an HTTP request with the required authentication, page URL, and supported capture settings.
- Check the HTTP status before treating the response as a successful screenshot.
- Parse JSON or save response bytes according to the endpoint’s documented response format.
A vendor SDK is optional when the provider documents ordinary HTTP requests. For example, Screenshot API documents a Python requests.post call using bearer authentication and JSON, while ScreenshotAPI.to documents a GET request using an x-api-key header and saving the response body. Follow the chosen provider’s contract rather than combining snippets from different services. See the Screenshot API REST API reference and ScreenshotAPI.to Python documentation.
Example: POST request that returns a screenshot URL
This provider-specific example follows Screenshot API’s documented pattern: POST to its screenshot endpoint, send a bearer token and JSON payload, then read screenshotUrl from the JSON response. Its documentation describes GET and POST routes; advanced settings such as CSS and selectors are restricted to POST. Check the current reference for required fields and accepted values.
import os
import requests
api_key = os.environ["SCREENSHOT_API_KEY"]
endpoint = "https://api.screenshot-api.org/api/v1/screenshot"
payload = {
"url": "https://example.com",
"viewport": {"width": 1440, "height": 900},
"format": "png",
"fullPage": True,
}
response = requests.post(
endpoint,
headers={"Authorization": f"Bearer {api_key}"},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data["screenshotUrl"])Install the HTTP client with python -m pip install requests, then set SCREENSHOT_API_KEY in your environment before running the script. The 120-second timeout is an example setting from ScreenshotEngine’s documentation, not a general service guarantee. Screenshot API recommends authentication headers over a query parameter. Do not commit a real key to source control.
#1 Best Overall
Save the returned image
The example above returns a URL rather than image bytes. If you need a local file, fetch that URL and save its response content; check that download’s status too.
image_response = requests.get(data["screenshotUrl"], timeout=60)
image_response.raise_for_status()
with open("page.png", "wb") as image_file:
image_file.write(image_response.content)Use the extension and media type that match the actual image format. The API reference should specify whether the returned URL is temporary or durable; do not assume its lifetime.
When the API returns image bytes directly
Some endpoints respond with the image itself, not JSON. For that contract, write response.content in binary mode (wb) after checking the status. ScreenshotAPI.to’s raw HTTP example uses a GET request, an x-api-key header, raise_for_status(), and writes the response body to a file. Its exact endpoint and supported parameters should come from its current documentation.
import os
import requests
response = requests.get(
"PROVIDER_DOCUMENTED_ENDPOINT",
headers={"x-api-key": os.environ["SCREENSHOT_API_KEY"]},
params={"url": "https://example.com"},
timeout=60,
)
response.raise_for_status()
with open("page.png", "wb") as image_file:
image_file.write(response.content)The endpoint string and parameter names above must be replaced with those documented by the provider; this is a pattern, not a universal screenshot API contract. For a standard-library alternative, ScreenshotEngine documents using urllib.request.Request with JSON-encoded POST data, bearer authentication, a timeout, and writing returned bytes. See its code examples.
Recommended Free Tools
Choose request options from the provider’s documentation
Capture settings differ between services, including their names, allowed values, and whether they can be sent by GET or require POST. Common documented controls include:
- Viewport: width and height for the browser window.
- Full-page capture: whether to capture beyond the visible viewport.
- Output format: for example, PNG or another format the endpoint supports.
- CSS and selectors: apply CSS changes or capture a selected element where supported.
- Wait behavior: wait for a selector or a specified delay when a page renders content asynchronously.
These are examples of provider-specific features, not a promise that every API supports them. HTML to Image’s Python integration documentation describes capture controls and service-specific error codes.
Handle errors and operational failures
Call raise_for_status() before parsing JSON or writing a file. In production code, catch transport exceptions and HTTP errors, log enough context to diagnose the request, and avoid logging API keys or sensitive headers.
- Invalid request: verify the URL, JSON shape, parameter names, and supported option values against the selected endpoint’s documentation.
- Authentication failure: confirm the key is present, active, and sent in the required header or other documented location.
- Quota or plan restriction: inspect the provider’s error body and account limits; do not assume all services use the same status code.
- Rate limiting: follow the provider’s retry guidance, if documented, and avoid immediate unbounded retries.
- Timeout or network failure: set a client timeout suited to your application and decide whether a limited retry is appropriate. A timeout value is a client-side limit, not a promise about rendering speed.
- Unexpected response format: check the endpoint contract and response content type. Do not pass image bytes to
response.json()or treat JSON metadata as a PNG.
For one specific mapping, HTML to Image documents 400/422 for validation, 401 for authentication, 402/403 for credits or plan errors, 429 for rate limiting, and 504 for rendering timeout. Those codes describe that service’s documentation and should not be generalized to other providers.
Or skip the browser setup
ScreenshotNeo is a screenshot API and MCP server for developers. One GET request can return a PNG, JPEG, WebP, or PDF; the code below saves the response body as a WebP file. See the ScreenshotNeo API documentation for the endpoint contract and options.
import os
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": os.environ["SCREENSHOTNEO_API_KEY"], "url": "https://example.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides screenshot and PDF tools for AI agents. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to try 1,000 screenshots a month with no card.
Frequently Asked Questions
Do I need a screenshot provider’s Python SDK?
No. If the provider documents raw HTTP, Python’s standard library or an HTTP client such as requests can make the call.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Why does my screenshot response fail when I try to parse JSON?
The endpoint may return image bytes directly rather than JSON. Check its documented response format and content type.
Can I use the same parameters with every screenshot API?
No. Authentication, HTTP method, parameter names, response format, and available capture controls vary by provider.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
