[DEMO] URL to Image

Webpage to Image Rendering
Render a target webpage as an image binary stream with configurable viewport options.

Method: GET
Path: /v1/websitetools/url2image
Demo: https://api.gugudata.io/v1/websitetools/url2image/demo
OpenAPI: https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json

Request Parameters:

appkey (string, required): Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.

url (string, required): Target webpage URL.

isFullPage (boolean, optional): Whether the renderer should capture the full page height.

width (integer, optional): Output width in pixels.

height (integer, optional): Output height in pixels.

viewportWidth (integer, optional): Viewport width in pixels used during page rendering.

viewportHeight (integer, optional): Viewport height in pixels used during page rendering.

forceReload (boolean, optional): Whether the renderer should bypass cached page content before capture.

isMobile (boolean, optional): Whether the renderer should emulate a mobile device viewport.

isDarkMode (boolean, optional): Whether the renderer should emulate dark mode when rendering the target page.

deviceScaleFactor (integer, optional): Device scale factor used during page rendering.

Response Fields:

image (binary, required): Rendered image binary stream returned on success. On failure, the endpoint returns a JSON error payload instead of binary content.

HTTP Status Codes:

200: Request processed successfully. Some endpoints expose a separate application-level status field in the response body, such as dataStatus.statusCode.

400: Invalid request parameters or request format. Check required fields, data types, and request body format.

401: Missing or unknown application key. Provide a valid appkey with the request.

403: The application key is recognized but access is not allowed. The key may be expired, inactive, or not permitted for the requested API.

429: Request rate or trial usage limit exceeded. Reduce concurrency or retry after the limit window resets.

500: Internal service error. Retry later or contact support if the error persists.

503: Upstream service unavailable. Retry later; the requested upstream dependency is temporarily unavailable.

Business Status Codes:

200 Normal return: Image successfully generated and returned

400 Parameter error: Invalid or missing required parameters

429 Request frequency limited: Cannot exceed 100 requests per second

403 Account in arrears: Payment required to continue using the service

402 APPKEY error: Please check whether the APPKEY passed is obtained from the developer center

500 API response error: Internal server error during image generation

503 Service unavailable: External service temporarily unavailable

Key Features:

Support capturing screenshots from any publicly accessible webpage.

Flexible image dimensions with customizable width and height.

Full page capture or viewport-only screenshot options.

Mobile device simulation for responsive design testing.

Dark mode support for modern websites.

High-DPI rendering with device scale factor up to 4x.

Full API support for HTTPS (TLS v1.0 / v1.1 / v1.2 / v1.3).

Fully compatible with Apple ATS.

Nationwide multi-node CDN deployment.

Ultra-fast response, API interface load balancing built with multiple servers.

Details:
https://gugudata.io/details/url2image

application/json

Bodyapplication/json

Example

{
  "image": null,
  "DataStatus": {
    "StatusCode": 100,
    "StatusDescription": "OK",
    "ResponseDateTime": "2026-01-01 00:00:00",
    "DataTotalCount": 1
  }
}

Request

Request Code Samples

Responses