POST /v1/render

Endpoint and authentication

POST https://capture.viperisuseful.cc/v1/render requires Content-Type: application/json and Authorization: Bearer vc_live_…. Create an API key in the dashboard. The API rejects unknown fields. You can send an X-Request-Id with 1–128 letters, digits, dots, underscores, colons, or hyphens.

Use the async image job API if the client cannot keep the render connection open. See advanced rendering for browser selection, actions, video, diagnostics, deterministic mode, certification, and slices.

curl --fail-with-body https://capture.viperisuseful.cc/v1/render \
  -H "Authorization: Bearer $VIPERCAPTURE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: docs-example-001" \
  --data '{"url":"https://example.com","output":"png"}' \
  --output capture.png

Source fields

• Supply exactly one of url, html, or markdown.
• url must be public HTTP(S). Private, loopback, link-local, reserved, and DNS-rebinding targets are blocked, including redirects and subresources.
• html and markdown accept at most 5 MiB UTF-8. They may use a public base_url to resolve relative links. base_url is invalid with url.
• headers is an object of at most 32 string values and 16 KiB serialized. Managed hop-by-hop, Host, Sec-*, Proxy-*, and X-Forwarded-* headers are rejected. Authorization and Cookie reach only the exact initial origin, never a cross-origin redirect or subresource.

Example request

{
  "url": "https://example.com",
  "output": "webp",
  "viewport": { "width": 1440, "height": 900, "device_scale_factor": 1 },
  "viewports": null,
  "environment": {
    "device": "desktop",
    "color_scheme": "dark",
    "reduced_motion": "reduce",
    "locale": "en-US",
    "timezone": "America/New_York"
  },
  "full_page": true,
  "preserve_viewport_width": true,
  "lazy_load": "adaptive",
  "selector": null,
  "clip": null,
  "custom_css": "header { display: none !important; }",
  "fail_on_status": [404, 429, 500, 502, 503],
  "image": {
    "quality": 88,
    "transparent_background": false,
    "optimize_for_speed": true
  },
  "pdf": null,
  "extract_mode": "document",
  "headers": { "Accept-Language": "en-US" },
  "wait_for": {
    "event": "load",
    "selector": ".ready",
    "selector_state": "visible",
    "text": null,
    "images": true,
    "delay_ms": 500,
    "timeout_ms": 15000
  },
  "cleanup": {
    "consent_mode": "reject",
    "block_ads": true,
    "block_trackers": true,
    "block_chats": true,
    "block_newsletters": true
  },
  "cache": true,
  "proceed_on_captcha": false
}

Defaults and bounds

• output: png. Other values: jpeg, webp, avif, gif, webm, mp4, pdf, html, markdown, metadata.
• engine: chromium; alternatives are firefox and webkit. PDF and fast encoding are Chromium-only.
• viewport: 1280×720 CSS pixels at density 1. Schema bounds are width/height 1–65,535 and density 0.1–8; plan and global execution limits are stricter.
• full_page: true. preserve_viewport_width: false. lazy_load: thorough; alternatives are adaptive and none.
• wait_for.event: load; selector_state: visible, attached, hidden, or detached; images: false; delay_ms: 0, maximum 15,000; timeout_ms: 15,000, maximum 30,000 and also plan-limited.
• cleanup.consent_mode: none; all four blocking flags default false. Consent values are none, reject, accept, and hide.
• custom_css: null, maximum 64 KiB UTF-8. fail_on_status: empty, maximum 32 unique integers from 100 through 599.
• cache: false. Set true only for a single PNG, JPEG, or WebP API output to reuse an exact account-scoped render for up to 15 minutes.
• proceed_on_captcha: false. Setting true captures a visible challenge; it never solves or bypasses one.

Image selection and crop

selector captures the first visible matching element. It requires an image output and full_page=false. clip contains non-negative x/y and positive width/height in CSS pixels. It also requires an image output and full_page=false. A clip must remain inside the final document and cannot be combined with selector or a viewport pack.

JPEG, WebP, and AVIF accept image.quality from 1–100. PNG, WebP, and AVIF support transparent backgrounds. image.width and image.height resize a single image while preserving aspect ratio when one dimension is omitted. Chromium can use optimize_for_speed for PNG or WebP. Full-page captures are capped at 20,000 CSS pixels high and by the global pixel budget. If horizontal overflow exceeds plan width, retry with preserve_viewport_width=true.

PDF, HTML, Markdown, and metadata

PDF costs two credits. pdf.mode is print or single_page; paper supports A0–A6, Legal, Letter, and Tabloid, orientation is portrait or landscape, and each margin is 0–4 inches. Set pdf.tagged=true to ask Chromium for structural tags used by assistive technology and document parsers. Tags depend on the source markup and are not PDF/UA certification. Print output supports bounded header/footer templates and page ranges and is capped at 50 pages; single-page PDF is capped at one 20,000-CSS-pixel page. HTML and Markdown can use extract_mode=document or article and can serialize bounded open shadow roots. Metadata is bounded JSON; see the metadata schema.

Render order

1. Validate JSON and count the API attempt. For cache=true, check the account-scoped exact-request cache before reserving full render credits or entering the browser queue.
2. On a cache miss, reserve API credits and wait in the account-fair queue.
3. Create a fresh isolated context in the selected browser, apply environment and network controls, route-protect every request, and navigate or load inline content.
4. Evaluate fail_on_status, finish consent handling, apply custom CSS, execute waits and typed actions, then evaluate assertions.
5. Apply cleanup, detect blocking CAPTCHA pages, optionally scroll lazy content, and capture, encode, slice, certify, or extract the final DOM.
6. Validate the artifact, release its browser slot, and best-effort store cache-enabled images in UploadThing for 15 minutes. Only then settle normal render credits and return it. Cache storage failure does not fail a valid render.

Fifteen-minute image cache

cache=true is opt-in and valid only for a single PNG, JPEG, or WebP output. The cache key covers the complete validated request, including source, headers, waits, cleanup, viewport, engine, and encoding options. Entries are isolated to the authenticated account; request sources and header values are never stored in cache metadata. Cache hits still count against API attempt limits, but bypass credit reservation, the render queue, and the browser.

Cached delivery is metered account-wide at two hits per credit. The first hit opens a 15-minute pending half and costs zero. A second cache hit during that window costs one credit and clears the pending half. If no second hit arrives, the pending half expires and the lone hit remains free. Pairing is atomic across concurrent requests and across all cache keys and API keys on the account.

Successful response

The body is the artifact itself, not a JSON wrapper. Read Content-Type and the filename in Content-Disposition. Diagnostics are returned as integer headers: X-ViperCapture-Queue-Ms, X-ViperCapture-Render-Ms, X-ViperCapture-Output-Count, and when available X-ViperCapture-Navigation-Status, X-ViperCapture-Width, X-ViperCapture-Height, and X-ViperCapture-Blocked-Subresources. Cache-enabled requests also return X-ViperCapture-Cache (HIT, MISS, or MISS-NOT-STORED), cache expiry, the actual credit cost, and pending-half state. Cache hits report zero queue/render milliseconds. The final URL is not included in the headers because query strings can contain secrets. Metadata JSON contains the final URL.

Field conflicts

• selector and clip are mutually exclusive; each disables full-page mode.
• viewports requires 2–3 PNG, JPEG, or WebP viewports, full_page=false, and no selector or clip.
• cache=true requires a single PNG, JPEG, or WebP output and cannot be combined with a viewport pack.
• PDF and video settings are output-specific. Image quality, resizing, transparency, and fast encoding are restricted to compatible formats and engines.
• Hosted requests reject custom proxies, persistent browser profiles, and synchronous webhook delivery.
• Article extraction is valid only for HTML or Markdown.
• Inline HTML/Markdown has no HTTP navigation response, so fail_on_status cannot match and the navigation-status header is omitted.

See errors and retry rules, credits and limits, and the machine-readable OpenAPI schema.