How to Set Cookies and Headers in ScreenshotMachine CLI

ScreenshotMachine’s documented CLI-style method is a Bash script that calls its HTTP screenshot API with curl; the documentation does not establish a separate ScreenshotMachine CLI executable. Pass cookies in the cookies parameter. For the documented request-header controls, use accept-language and user-agent. The reviewed API documentation does not establish a generic arbitrary-headers parameter.

1. Pass cookies and documented header settings with curl

Here is a Bash example following ScreenshotMachine’s documented curl pattern, with the cookie and header-control parameters added. Replace the placeholders with your account key, target URL, and authorized cookie values.

#!/usr/bin/env bash
set -euo pipefail

CUSTOMER_KEY="YOUR_CUSTOMER_KEY"
URL="https://example.com/account"
COOKIES="session=YOUR_SESSION_VALUE;theme=dark"
LANGUAGE="en-US"
USER_AGENT="Mozilla/5.0 (compatible; ExampleBot/1.0)"
OUTPUT="output.png"

ARGS=(
  --data-urlencode "key=$CUSTOMER_KEY"
  --data-urlencode "url=$URL"
  --data-urlencode "cookies=$COOKIES"
  --data-urlencode "accept-language=$LANGUAGE"
  --data-urlencode "user-agent=$USER_AGENT"
)

curl -Gs "https://api.screenshotmachine.com" "${ARGS[@]}" -o "$OUTPUT"

The command uses curl --data-urlencode to encode each query parameter value, including reserved characters in the URL and cookie string. The documented cookie format is semicolon-separated name/value pairs. Use only session cookies you are authorized to use, and treat them as credentials.

Minimal cookie-only request

If you do not need to control language or user agent, omit those parameters:

curl -Gs "https://api.screenshotmachine.com" \
  --data-urlencode "key=YOUR_CUSTOMER_KEY" \
  --data-urlencode "url=https://example.com/account" \
  --data-urlencode "cookies=session=YOUR_SESSION_VALUE;theme=dark" \
  -o output.png

Using the documented options

Parameter	Purpose	Notes
key	Required account authentication.	Keep it out of public repositories, shared scripts, and logs.
url	Required page to capture.	URL-encode it; --data-urlencode handles this in the examples.
cookies	Semicolon-separated cookie name/value pairs applied for capture.	Cookie values need percent encoding. Use --data-urlencode rather than manually assembling an encoded query string.
accept-language	Controls the documented Accept-Language request header.	For example, en-US.
user-agent	Controls the documented User-Agent request header.	Provide the user-agent string you need; the docs include a mobile browser example.
hash	Optional request authentication when a secret phrase is configured.	See authentication and security below.

Cookie formatting and encoding

Write cookies as pairs separated by semicolons, such as name1=value1;name2=value2. ScreenshotMachine’s documentation says the cookie parameter must be percent-encoded, illustrating the encoded form name1%3Dvalue1%3Bname2%3Dvalue2. In the curl examples, --data-urlencode performs that encoding for the parameter value. Avoid encoding the entire value yourself and then passing it through --data-urlencode, since that can double-encode percent signs.

The cookie parameter supplies cookies for the capture; it is not a way to send an arbitrary HTTP header. The reviewed documentation does not specify more detailed cookie-domain or path behavior, so use cookies appropriate for the target site and verify the rendered result.

2. Understand what “headers” the API supports

For ScreenshotMachine, the sources reviewed document dedicated accept-language and user-agent parameters. They do not document a generic headers query parameter or a way to forward arbitrary headers such as Authorization. Do not assume that a curl option like -H 'Authorization: …' sets a header on the browser request made by the screenshot service; that option would set a header on the request from curl to the API.

If a page requires authentication, the documented cookie parameter may work when you have an authorized session cookie for that page. The reviewed documentation does not establish arbitrary header forwarding as an alternative. Check the official Website Screenshot API documentation for current supported parameters.

Cookie alternatives are different operations

• cookies sends cookie pairs for the capture.
• click activates a CSS selector before capture.
• hide hides selected page elements, and can be used to hide a cookie banner visually.

click and hide change page behavior or appearance; neither transmits a session cookie. A banner hidden from the screenshot may still have appeared to the site, while a cookie parameter is for supplying cookie state.

3. Authentication and safe handling

The API requires the customer key parameter. If you configured a secret phrase, ScreenshotMachine documents a hash computed as MD5 of the target URL concatenated with that secret phrase. Requests missing the required hash or using an incorrect one are ignored. Consult the vendor’s Python example repository and API documentation for account and signing details before implementing this option.

• Keep the customer key, secret phrase, and session cookie in environment variables or a secrets manager for production use.
• Do not commit credentials or print full request URLs to shared logs; query parameters can expose secrets in shell history, process listings, and observability systems.
• Use a secret phrase when calls originate from publicly accessible webpages, as the vendor’s Python example recommends.
• Do not use cookies to access accounts or pages without authorization.

4. Capture options that affect the result

Cookies and header controls determine the page context. Other documented ScreenshotMachine options influence what part of the rendered page becomes the output: dimensions, device presets, image format, waiting delay, zoom, CSS-selector capture, and cropping. They are separate from cookie and header syntax. If an authenticated page is long or renders content asynchronously, choose capture dimensions and wait behavior that fit the page, then inspect the output.

Refer to the vendor’s API options table for exact parameter names and accepted values. This guide does not assume undocumented defaults, limits, or combinations.

5. Troubleshooting

Symptom	Likely cause	What to do
The image shows a login page.	The session cookie is absent, invalid, expired, malformed, or for a different site context.	Confirm the cookie names and values, refresh the authorized session, and pass pairs in the documented semicolon-separated format. Ensure the target URL is on the expected site.
The saved file is an error image.	The API may return an error image for an invalid or incomplete request.	Inspect the X-Screenshotmachine-Response response header; documented error codes include invalid_key, invalid_url, invalid_selector, and no_credits.
Cookies with punctuation do not work.	Reserved characters were not encoded, or were encoded twice.	Pass the raw semicolon-separated cookie string as one quoted value to --data-urlencode. Do not pre-encode it as well.
The page language is unchanged.	The request is missing or misspells the dedicated language parameter, or the page chooses content independently.	Use accept-language exactly as documented, for example en-US. The page may still select language using its own rules or saved state.
The site ignores the user agent.	The user-agent parameter may be absent or the site may determine its layout through other signals.	Set user-agent to the desired complete string. A user-agent string alone does not guarantee a particular device rendering.
An arbitrary Authorization header is not reaching the page.	The reviewed ScreenshotMachine API documentation does not establish generic custom-header forwarding.	Do not use curl’s -H for this purpose; it applies to curl’s API request. Check current vendor documentation for supported authentication approaches, or use a screenshot service whose documented API accepts the required header.
The request works locally but credentials appear in logs.	Secrets are present in query parameters or shell history.	Move values into protected runtime configuration, limit logging, rotate exposed credentials, and avoid sharing shell transcripts.

6. Performance, reliability, and cost considerations

The reviewed sources provide no attributable performance benchmark or dated latency figure for this cookie-and-header workflow, so plan around the behavior of your pages and account rather than an assumed response time. Authenticated pages can take longer when they redirect, load scripts, or wait for client-side content. Keep the requested capture focused, use the vendor’s documented wait and sizing options where needed, and handle unsuccessful responses explicitly.

For a production integration, distinguish transport success from a valid screenshot: save the response, inspect X-Screenshotmachine-Response when the result looks like an error, and alert on documented account or request failures such as no_credits. The reviewed sources do not establish pricing details for this specific setup; check ScreenshotMachine’s current account and pricing information before estimating costs.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Its API accepts a URL in one GET request and returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com/account \
  -o shot.webp

In Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com/account"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

In Node.js:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com/account'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

• Cookie and consent banners are accepted like a visitor and removed before capture; 60+ known consent platforms, newsletter popups, and chat widgets are supported, and each cleanup step can be turned off.
• Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report the page verdict and billing status.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
• The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; all features are available on every plan.

Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.

8. FAQ

Is ScreenshotMachine CLI a standalone program?

The reviewed official material documents a Bash and curl way to call the HTTP API, not a separate CLI executable.

Can I pass multiple cookies?

The documented format is semicolon-separated cookie name/value pairs in the cookies parameter.

Can I send any custom header?

The reviewed API page documents controls for Accept-Language and User-Agent, but not generic arbitrary headers.

Does hiding a cookie banner set consent?

No. The hide option affects visibility in the capture; it is distinct from transmitting cookies or interacting with a consent control.