Webpage Screenshot Capture API

Capture public webpages as PNG images for content reviews, reporting, and visual records. Choose a full-page image or a fixed viewport, then receive Base64 text or a public download link. The response also includes rendered page HTML when available.

View API details or try the Demo.

Capture a page

Send POST https://api.gugudata.io/v1/websitetools/url2snapshot with JSON. Place appkey in the query string, not in the JSON body. Keep your key on your server.

curl 'https://api.gugudata.io/v1/websitetools/url2snapshot?appkey=YOUR_APPKEY' \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://gugudata.io/","responseFormat":"url","fullPage":false,"width":1280,"height":720}'

JSON field	Default	Meaning
url	Required	Complete public HTTP/HTTPS URL, at most 2048 characters; no credentials, literal IP addresses, or non-standard ports.
responseFormat	base64	Use url for a public image link or base64 for PNG Base64 text. Other values retain the legacy Base64 behavior.
fullPage	true	Capture the page height rather than only the viewport.
width	1920	Viewport width in CSS pixels, 1–8192.
height	1080	Viewport height in CSS pixels, 1–8192.
deviceScaleFactor	1	Integer scale, 1–3.
userAgent	Default desktop agent	Optional string up to 1024 characters, without control characters.
isMobile	false	Enable mobile viewport emulation.

The scaled viewport area (width × height × deviceScaleFactor²) must not exceed 64,000,000 pixels. A full-page image can be taller than height and is still subject to image size limits. PNG output is limited to 32 MiB and 64 million pixels; an oversized or invalid image fails instead of being returned as a successful capture.

Read the result

Successful responses use the existing dataStatus and data envelope. Check both HTTP status and dataStatus.statusCode before using the result.

Field	Type	Meaning
data.image	string	PNG Base64 text, or a public image link when responseFormat is url.
data.content	string	Rendered HTML, or an empty string when no HTML is returned.
dataStatus.requestParameter	string	Source host/path and capture options; source query values and credentials are omitted.

This illustrative data fragment shows URL mode; the address is a placeholder, not a saved capture:

{
  "image": "https://assets.example/snapshot.png",
  "content": "<!doctype html><html><body><h1>Example page</h1></body></html>"
}

For Base64 mode, decode data.image into PNG bytes before saving or displaying it. For URL mode, download and save the image if you need to retain it. The URL is public; do not assume permanent hosting or treat it as private storage.

Treat data.content as untrusted HTML. It is not sanitized content and should not be inserted directly into your application. Page animations, late-loading content, consent dialogs, and site access restrictions can affect captures; identical output is not guaranteed.

Demo behavior

The Demo captures this public guide page with a 1920 × 1080 viewport, full-page capture, scale 1, and URL output. Its request metadata includes the public input link.

A successful result is cached for 15 minutes. X-GuGuData-Demo-Mode reports live or cached, and X-GuGuData-Generated-At identifies when that cached result was generated. Failed captures are not cached. Use your authenticated request for your own pages.

Handle failures

• 400: correct the URL, JSON, viewport, scale, or user-agent value.
• 401 / 403: check the application key and product access.
• 429: reduce request frequency and follow any retry guidance in the response.
• 500 / 503: capture or storage could not complete. Handle the failure explicitly; do not display a missing image as a successful capture or retry indefinitely.

Avoid logging full source URLs, keys, HTML, or Base64 output. Record safe request context and response status instead.

Related APIs

• Readable content extraction
• Webpage Markdown
• Webpage links

See the OpenAPI specification for the full response schema.