Webpage to Image Rendering API Integration Guide
Learn how to integrate the Webpage to Image Rendering API with documented request parameters, response fields, error handling, and practical examples.
Webpage to Image Rendering API Integration Guide
Render a public webpage as a PNG image for previews, reports, monitoring, and visual QA.
View API details or try the Demo.
API details
| Item | Value |
|---|---|
| API name | Webpage to Image Rendering |
| Category | Website Tools APIs |
| Method | GET |
| Endpoint | https://api.gugudata.io/v1/websitetools/url2image |
| Success content type | image/png |
| Demo endpoint | https://api.gugudata.io/v1/websitetools/url2image/demo |
| Detail page | https://gugudata.io/details/url2image |
| OpenAPI JSON | https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json |
When to use this API
- Render public pages as images for previews or monitoring.
- Generate visual snapshots for reports and dashboards.
- Capture page state for QA workflows.
Request parameters
This endpoint accepts parameters through the query string. Keep appkey out of client-side public code and send it only from trusted server-side environments.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
appkey |
string |
Yes | YOUR_APPKEY |
Application key supplied in the query string. |
url |
string |
Yes | - | Public HTTP(S) URL, up to 2,048 characters. |
isFullPage |
boolean |
No | false |
Whether the renderer should capture the full page height. |
width |
integer |
No | 250 |
Output width, from 1 to 4,096 pixels. |
height |
integer |
No | 250 |
Output height, from 1 to 4,096 pixels. |
viewportWidth |
integer |
No | 1080 |
Viewport width, from 320 to 4,096 pixels. |
viewportHeight |
integer |
No | 1080 |
Viewport height, from 200 to 4,096 pixels. |
forceReload |
boolean |
No | false |
Whether the renderer should bypass cached page content before capture. |
isMobile |
boolean |
No | false |
Whether the renderer should emulate a mobile device viewport. |
isDarkMode |
boolean |
No | false |
Whether the renderer should emulate dark mode when rendering the target page. |
deviceScaleFactor |
integer |
No | 1 |
Device scale factor from 1 to 4. |
Example request
curl -G "https://api.gugudata.io/v1/websitetools/url2image" \
--data-urlencode "appkey=YOUR_APPKEY" \
--data-urlencode "url=https://example.com/article" \
--data-urlencode "isFullPage=false" \
--data-urlencode "width=250" \
--data-urlencode "height=250" \
--data-urlencode "viewportWidth=1080" \
--data-urlencode "viewportHeight=1080" \
--data-urlencode "forceReload=false" \
--data-urlencode "isMobile=false" \
--data-urlencode "isDarkMode=false" \
--data-urlencode "deviceScaleFactor=1"Response
A successful request returns the PNG bytes directly with Content-Type: image/png. Save the body as a .png file or stream it to your own storage. Error responses use JSON instead of image bytes.
HTTP status codes
Use the HTTP status code for transport-level handling. If the response body contains dataStatus.statusCode, treat it as an application-level status field in the JSON payload.
| HTTP status | Meaning | Recommended handling |
|---|---|---|
200 |
PNG rendered successfully. | Read or save the binary response body. |
400 |
Invalid request parameters or request format. | Check required fields, data types, and request body format. |
401 |
Missing or unknown application key. | Send a valid appkey with the request. |
403 |
The application key is recognized but access is not allowed. | Check subscription, trial state, and endpoint access. |
429 |
Request rate or trial usage limit exceeded. | Reduce concurrency or retry after the limit window resets. |
500 |
The renderer returned an invalid result. | Retry later or contact support if the error persists. |
503 |
Rendering is temporarily unavailable. | Retry later with backoff. |
Boundaries
The API accepts public HTTP(S) pages only. Credentials in URLs, IP-literal targets, private network destinations, non-standard ports, and non-HTTP schemes are rejected. Dynamic pages may render differently depending on loading time, viewport, responsive layout, and the availability of page resources.
The service returns a rendered image, not the page HTML or a permanent archive. Store the result in your own system when retention matters.
FAQ
Where is the official API detail page?
The official detail page is https://gugudata.io/details/url2image. It is the best place to review the latest public endpoint information before publishing or integrating.
Is the response JSON?
No. A successful response is a PNG binary stream. JSON is returned only for errors.
Can I use the demo endpoint in production?
No. The demo endpoint is for quick testing and examples. Use the authenticated endpoint with your appkey for production workflows.
Related GuGuData APIs
- Webpage Readable Content Extraction
- Domain SSL Certificate Information Parsing
- Domain DNS Information Query
For more developer APIs, visit GuGuData.