DEV Community

GuGuData
GuGuData

Posted on

Webpage to Image API Documentation - Convert Any URL to High-Quality Screenshot

Webpage to Image API

Category: Web Tools & Image Generation

Endpoint: GET https://api.gugudata.io/v1/websitetools/url2image?appkey={{appkey}}

Description: Convert any webpage to high-quality PNG image with customizable capture options and device simulation

Overview

The Webpage to Image API from GuGuData provides powerful webpage screenshot capabilities that enable you to capture any publicly accessible website as a high-quality PNG image. This robust API offers extensive customization options including full-page capture, mobile device simulation, dark mode support, and high-DPI rendering. Perfect for website monitoring, social media previews, documentation, and automated testing.

Key highlights:

  • Universal webpage capture – Screenshot any publicly accessible website or web application
  • Flexible image dimensions – Customize width, height, and viewport settings
  • Device simulation – Mobile, tablet, and desktop viewport options
  • Advanced rendering options – Dark mode, high-DPI, and full-page capture
  • Real-time processing – Generate screenshots on-demand with fast response times
  • PNG format output – High-quality image files ready for immediate use

Demo URL

https://api.gugudata.io/v1/websitetools/url2image/demo

Request Parameters

Send a GET request to the endpoint with the following parameters:

Parameter Type Required Default Value Description
appkey string Yes YOUR_APPKEY Your API access key obtained after subscription
url string Yes N/A The URL of the webpage to capture (must be publicly accessible)
isFullPage boolean No false Whether to capture the full page (true) or just viewport (false)
width int No 250 Image width in pixels
height int No 250 Image height in pixels
viewportWidth int No 1080 Viewport width in pixels for rendering
viewportHeight int No 1080 Viewport height in pixels for rendering
forceReload boolean No false Whether to force reload the page ignoring cache
isMobile boolean No false Whether to simulate mobile device
isDarkMode boolean No false Whether to enable dark mode
deviceScaleFactor int No 1 Device scale factor for high-DPI displays (1-4)

Example Request:

GET https://api.gugudata.io/v1/websitetools/url2image?appkey=YOUR_APPKEY&url=https://www.gugudata.io&isFullPage=true&width=1200&height=800&isMobile=false&isDarkMode=false

Response Format

The API returns a PNG image file stream with the following characteristics:

Response Type Value Description
Content-Type image/png PNG format image file
Cache-Control public, max-age=86400 Image cached for 24 hours
Image Quality High-quality Lossless PNG compression
File Size Variable Depends on image complexity and dimensions

Response Headers:

Content-Type: image/png
Cache-Control: public, max-age=86400
Content-Length: [image_size_in_bytes]
Enter fullscreen mode Exit fullscreen mode

Error Codes

Status Code Description Notes
200 Success Image successfully generated and returned
400 Bad Request Invalid parameters or missing required URL
402 Payment Required Invalid or expired APPKEY
403 Forbidden Account overdue or subscription expired
429 Too Many Requests Rate limit exceeded (max 100 requests per second)
500 Server Error Internal server error during image generation
503 Service Unavailable External service temporarily unavailable

Features

  1. Universal Website Support – Capture screenshots from any publicly accessible webpage
  2. Flexible Image Dimensions – Customize width and height to fit your requirements
  3. Full Page Capture – Screenshot entire webpage or just the visible viewport
  4. Mobile Device Simulation – Test and capture responsive designs
  5. Dark Mode Support – Capture websites in dark mode for modern aesthetics
  6. High-DPI Rendering – Generate crisp images with up to 4x device scale factor
  7. Cache Optimization – Force reload option to bypass cached content
  8. Real-time Processing – Generate screenshots on-demand with fast response times
  9. Global CDN Deployment – Fast and reliable image delivery worldwide
  10. HTTPS Support – Secure API calls (TLS v1.0-1.3)

Use Cases

  1. Website Monitoring – Automate visual regression testing and monitoring
  2. Social Media Previews – Generate website preview images for social sharing
  3. Documentation – Create visual documentation of web interfaces
  4. Portfolio Generation – Capture website designs for portfolios
  5. Competitor Analysis – Monitor competitor website changes
  6. Marketing Materials – Create website screenshots for presentations
  7. Quality Assurance – Visual testing across different devices and modes
  8. Archive & Backup – Create visual backups of web content
  9. Email Campaigns – Include website previews in email marketing
  10. Blog Content – Enhance articles with website screenshots

Advanced Configuration Examples

Mobile Screenshot 

GET /v1/websitetools/url2image?appkey=YOUR_APPKEY&url=https://example.com&isMobile=true&viewportWidth=375&viewportHeight=667&width=375&height=667
Enter fullscreen mode Exit fullscreen mode

High-Resolution Full Page 

GET /v1/websitetools/url2image?appkey=YOUR_APPKEY&url=https://example.com&isFullPage=true&deviceScaleFactor=2&width=2560&viewportWidth=1280
Enter fullscreen mode Exit fullscreen mode

Dark Mode Capture 

GET /v1/websitetools/url2image?appkey=YOUR_APPKEY&url=https://example.com&isDarkMode=true&width=1200&height=800
Enter fullscreen mode Exit fullscreen mode

Getting Started

  1. Register at GuGuData.io – Get your API access key
  2. Choose Your Plan – Select the subscription that best fits your needs (starting at ¥99)
  3. Make API Calls – Start capturing webpage screenshots
  4. Integrate – Add screenshot functionality to your applications

Best Practices

  1. Rate Limiting – Stay within the 100 requests per second limit
  2. URL Validation – Ensure target URLs are publicly accessible
  3. Dimension Optimization – Choose appropriate image dimensions for your use case
  4. Error Handling – Implement proper error handling for all status codes
  5. Caching Strategy – Consider caching screenshots for frequently accessed pages
  6. Security – Keep your APPKEY secure and never expose it in client-side code
  7. Testing – Test with different viewport sizes and device modes
  8. Performance – Use appropriate image dimensions to balance quality and file size

Technical Specifications

  • Supported Protocols: HTTP, HTTPS
  • Maximum Image Width: 4096 pixels
  • Maximum Image Height: 4096 pixels
  • Supported Output Format: PNG
  • Maximum File Size: 50MB
  • Processing Timeout: 30 seconds
  • Concurrent Requests: Up to 100 per second
  • Geographic Coverage: Global CDN deployment

Integration Examples

cURL 

curl -X GET "https://api.gugudata.io/v1/websitetools/url2image?appkey=YOUR_APPKEY&url=https://www.gugudata.io&isFullPage=true&width=1200" \
     -H "Accept: image/png" \
     --output screenshot.png
Enter fullscreen mode Exit fullscreen mode

JavaScript (Node.js) 

const response = await fetch("https://api.gugudata.io/v1/websitetools/url2image?appkey=YOUR_APPKEY&url=https://www.gugudata.io&isFullPage=true&width=1200");
const imageBuffer = await response.buffer();
require("fs").writeFileSync("screenshot.png", imageBuffer);
Enter fullscreen mode Exit fullscreen mode

Python 

import requests

response = requests.get('https://api.gugudata.io/v1/websitetools/url2image', params={
    'appkey': 'YOUR_APPKEY',
    'url': 'https://www.gugudata.io',
    'isFullPage': True,
    'width': 1200
})

with open('screenshot.png', 'wb') as f:
    f.write(response.content)
Enter fullscreen mode Exit fullscreen mode

About GuGuData

GuGuData is a leading provider of data-centric APIs, offering solutions for Website Tools, QR Code Generation, Image Recognition, and more. Our services emphasize reliability, ease of use, and performance—helping developers build better applications faster.

Why Choose GuGuData:

  • Proven Track Record – Nine years of reliable service
  • Extensive API Portfolio – Over 4,200 APIs available
  • High Customer Satisfaction – 95% customer satisfaction rate
  • Global Infrastructure – Worldwide CDN deployment
  • 24/7 Support – Dedicated technical assistance
  • Competitive Pricing – Starting at ¥99 with ¥49 discount available

Transform your web applications with the Webpage to Image API. Visit our official website to explore more data-driven solutions from GuGuData.

Top comments (0)