How to Add Custom Headers and Cookies to an ApiFlash Request

To capture a page that requires authentication, send the target site’s credentials to ApiFlash with the screenshot request: use headers for authorization or other custom HTTP headers, and cookies for session cookies. ApiFlash accepts these as GET query parameters or POST form fields. URL-encode their values with your HTTP client’s parameter encoder so semicolons, equals signs, spaces, and other reserved characters are transmitted correctly. ApiFlash documents the endpoint and parameters; its FAQ discusses authenticated pages and custom-header side effects.

1. Choose headers or cookies

Target site’s authentication	ApiFlash parameter	Example value before encoding
Bearer token or another custom request header	headers	Authorization=Bearer YOUR_TOKEN
Logged-in browser session represented by cookies	cookies	sessionid=YOUR_SESSION;theme=dark

The API’s access_key authenticates your request to ApiFlash. It is separate from the token or cookie used to authenticate to the target website. Put the API key in access_key, and target-site credentials in headers or cookies.

2. Send custom headers

For a token-protected page, provide a semicolon-separated list of header-name and value pairs. The example below uses a bearer token and an additional preview header. Use a real token issued for the target site.

GET request

curl -G 'https://api.apiflash.com/v1/urltoimage' \
  --data-urlencode 'access_key=YOUR_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com/private' \
  --data-urlencode 'headers=Authorization=Bearer YOUR_TOKEN;X-Preview-Key=YOUR_SECRET' \
  -o page.png

The encoder handles the nested value. ApiFlash’s documentation illustrates the encoded form as Header1%3Dvalue1%3BHeader2%3Dvalue2. Avoid building a query string by concatenating raw values: a token may contain characters that change how the server parses the request.

POST form request

ApiFlash also accepts POST parameters as form data. This can keep long parameter values out of the URL, though the form body still needs normal secret-handling protections.

curl -X POST 'https://api.apiflash.com/v1/urltoimage' \
  --data-urlencode 'access_key=YOUR_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com/private' \
  --data-urlencode 'headers=Authorization=Bearer YOUR_TOKEN;X-Preview-Key=YOUR_SECRET' \
  -o page.png

3. Send session cookies

If the website authenticates a browser session with cookies, pass the cookie name/value pairs in cookies. Obtain valid cookie values through the site’s normal authentication flow; do not guess or reuse expired values.

GET request

curl -G 'https://api.apiflash.com/v1/urltoimage' \
  --data-urlencode 'access_key=YOUR_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com/account' \
  --data-urlencode 'cookies=sessionid=YOUR_SESSION;theme=dark' \
  -o account.png

Encode the entire cookies value as one parameter. The documented pattern encodes cookie1=value1;cookie2=value2 as cookie1%3Dvalue1%3Bcookie2%3Dvalue2. In the curl example, --data-urlencode performs that encoding for you.

POST form request

curl -X POST 'https://api.apiflash.com/v1/urltoimage' \
  --data-urlencode 'access_key=YOUR_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com/account' \
  --data-urlencode 'cookies=sessionid=YOUR_SESSION;theme=dark' \
  -o account.png

4. Runnable examples in Python and Node.js

Python with requests

Pass a parameter dictionary to requests; it encodes the query string. This example writes the response body to a PNG file and checks for an HTTP error before saving.

import requests

endpoint = "https://api.apiflash.com/v1/urltoimage"
params = {
    "access_key": "YOUR_ACCESS_KEY",
    "url": "https://example.com/private",
    "headers": "Authorization=Bearer YOUR_TOKEN;X-Preview-Key=YOUR_SECRET",
    # For session auth, use this instead of headers:
    # "cookies": "sessionid=YOUR_SESSION;theme=dark",
}

response = requests.get(endpoint, params=params, timeout=90)
response.raise_for_status()
with open("page.png", "wb") as image:
    image.write(response.content)

Node.js with built-in fetch

URLSearchParams encodes parameter values. This example requires a Node.js version with global fetch.

const endpoint = 'https://api.apiflash.com/v1/urltoimage';
const params = new URLSearchParams({
  access_key: 'YOUR_ACCESS_KEY',
  url: 'https://example.com/private',
  headers: 'Authorization=Bearer YOUR_TOKEN;X-Preview-Key=YOUR_SECRET',
  // For session auth, use this instead of headers:
  // cookies: 'sessionid=YOUR_SESSION;theme=dark',
});

const response = await fetch(`${endpoint}?${params}`);
if (!response.ok) {
  throw new Error(`ApiFlash returned HTTP ${response.status}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('page.png', image));

5. Handle encoding and credential edge cases

• Encode at the parameter boundary. Supply the raw semicolon-separated value to your HTTP library’s query or form encoder. Do not pre-encode and then encode again, which can turn percent signs into %25 and leave the server with an unusable value.
• Keep each list unambiguous. ApiFlash documents semicolon-separated pairs. If a cookie or header value itself contains a semicolon, the documented list format may be ambiguous. The dossier does not specify an escaping convention for embedded separators; consult current ApiFlash documentation or use an authentication method with values that fit the documented format.
• Use the correct cookie scope. The cookie must be valid for the target site’s domain and the page being captured. A cookie for a different environment or an expired session commonly produces the signed-out page rather than an API error.
• Expect headers to affect subrequests. ApiFlash’s FAQ says custom headers are applied to all page requests, including requests for fonts from Google Fonts and other CDNs. A header intended for the application can cause browser security restrictions to block those external resources. For session-based authentication, cookies may be a better fit when supported by the target site; another option is to self-host the required fonts.
• Do not expose credentials to clients. Avoid putting API keys, bearer tokens, or session cookies in frontend JavaScript, public URLs, logs, analytics, or shared screenshots. Make authenticated captures from a trusted backend and restrict who can request them. POST moves parameters into the request body, but it does not by itself make a secret safe to expose.

6. Troubleshooting

Symptom	Likely cause	What to check
The capture shows a login page	The target credential is missing, expired, malformed, or not valid for that URL.	Confirm whether the site expects a header or a session cookie, renew the credential through its normal login flow, and verify the URL and cookie scope.
Authorization appears ignored	The header value was not encoded as one parameter, or the target expects a different header or token format.	Use a query/form encoder; check the target site’s expected header name and scheme. Keep ApiFlash’s access_key separate.
Cookie string fails to authenticate	Separators or equals signs were parsed incorrectly, or the site requires additional session cookies.	Pass the whole raw list through the HTTP client’s encoder. Confirm the required cookie set and whether the session is still valid.
Fonts or other external assets disappear	A custom header is sent to external requests and may trigger browser security restrictions.	Use cookies for session auth where suitable, or self-host fonts as ApiFlash’s FAQ suggests.
HTTP 401 from ApiFlash	The ApiFlash access key is invalid or revoked.	Check the API key itself; changing the target site’s token will not fix an invalid API key.
HTTP 403	The plan does not support one of the requested features.	Review the current plan and requested parameters in ApiFlash’s documentation.
HTTP 429	The request rate or repeated-failure limit was reached.	Reduce concurrency, back off, and avoid retrying the same failing parameters in a tight loop. ApiFlash documents 20 requests per second with a burst size of 400; excess ordinary traffic is delayed and requests beyond the burst are terminated with 429. It also documents rate limiting five identical failed captures per hour. These figures are from the documentation reviewed for this guide and may change.
The saved file is not a valid image	An API error response may have been saved as if it were an image.	Check the HTTP status and response content type before treating the body as an image; do not save an unsuccessful response as a successful capture.

7. Performance, reliability, and cost considerations

Authenticated captures add operational dependencies: a token can expire, a session can be revoked, and target pages can redirect differently for signed-in visitors. Keep retries bounded, refresh credentials through the site’s supported flow, and capture only pages you are authorized to access. For rate limiting, use gradual backoff and control concurrency instead of retrying failures immediately. ApiFlash’s documented request limits are useful for capacity planning, but confirm the current limits before relying on them.

The research sources reviewed for this guide describe rate limits and some API errors but do not establish current pricing or a cost per capture. Check ApiFlash’s current product information for your plan and usage costs before estimating spend. Avoid caching private captures in a publicly accessible location, and apply your own retention and access controls to saved images.

8. Or skip the browser setup

If you need authenticated captures plus clean output without managing the capture browser, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Send a URL in one GET request and receive PNG, JPEG, WebP, or PDF. Its headers, cookies, and authorization options can pass credentials for pages you are allowed to capture. 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 -o shot.webp

With ScreenshotNeo, cookie banners are accepted and removed before the shot, along with known newsletter popups and chat widgets. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 screenshots.

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

FAQ

Can I use both headers and cookies in one request?

The reviewed ApiFlash material establishes each parameter separately but does not confirm combined behavior. Check the current documentation for whether your specific request supports both together.

Does sending a cookie log in to the target site?

No. The cookie value must already represent a valid session issued by the target site. Obtain it through that site’s normal authentication process.

Can I put the ApiFlash key in the target site’s Authorization header?

No. The ApiFlash key belongs in access_key. The headers parameter is for credentials and other headers the target website expects.

Why could cookie authentication be preferable to a custom header?

ApiFlash says custom headers can also be sent to external page requests such as CDN font requests. A session cookie may avoid that particular side effect when the target site supports cookie authentication.

Sources

• ApiFlash Screenshot API Documentation
• ApiFlash Screenshot API FAQ
• ApiFlash Screenshot API Guides and Tutorials