Migration Guide

Overview

This document provides step-by-step guidance for migrating all integrations from Thumbnail.ws to HQAPI, a newer and more flexible screenshot API.

1. Base URL and Authentication

Aspect	thumbnail.ws	HQAPI
Base URL	https://api.thumbnail.ws/api/{API_KEY}/thumbnail/get	https://api.eu-west.hqapi.com/api/v1/{TOKEN}/screenshot/create
Auth Method	API key in the URL path	Token in the URL path
Methods	GET, POST, or SOAP	POST (preferred), or GET for simple requests
Response Type	Raw image (JPEG by default)	Raw image (PNG by default, JPEG supported)

2. Parameter Mapping

The important parameters are still the same.

Thumbnail.ws parameter	HQAPI parameter	Notes
url	url	Same purpose
width	browser_width or image_width	HQAPI distinguishes between browser viewport size and final image size
delay	delay	Same range (0–5000 ms)
fullpage	full_page	Same purpose
mobile	mobile	Same purpose
format	format	Same purpose
refresh	not needed	HQAPI always captures fresh screenshots
(new)	browser_width, browser_height	Sets the browser viewport
(new)	jpeg_quality	Only used for format=jpeg
(new)	hide_cookie_popups	Optional feature
(new)	theme	Optional feature
SOAP support	Removed	HQAPI uses only REST (no SOAP)

3. Example: Old vs New (PHP GET)

Thumbnail.ws example:

<?php

$url = "https://www.google.com/";
$apikey = "YOUR-FREE-API-KEY";
$width = 640;

$fetchUrl = "https://api.thumbnail.ws/api/" . $apikey . 
    "/thumbnail/get?url=" . urlencode($url) . "&width=" . $width;
$image = file_get_contents($fetchUrl);

header("Content-type: image/jpeg");
echo $image;

?>

HQAPI example:

<?php

$url = "https://www.google.com/";
$apiToken = "YOUR-API-TOKEN";
$width = 640;

$fetchUrl = "https://api.eu-west.hqapi.com/api/v1/" . $apiToken . 
    "/screenshot/create?url=" . urlencode($url) . "&image_width=" . $width;
$image = file_get_contents($fetchUrl);

header("Content-type: image/png");
echo $image;

?>

4. Example: Old vs New (cUrl)

Thumbnail.ws example:

$ curl "https://api.thumbnail.ws/api/YOUR-FREE-API-KEY/thumbnail/get?url=https%3A%2F%2Fwww.google.com%2F&width=320"

HQAPI example:

$ curl -X POST --data '{"url":"https://www.google.com/","image_width":320}' \
    "https://api.eu-west.hqapi.com/api/v1/YourToken01/screenshot/create"

5. Example: Old vs New (Python)

Thumbnail.ws example:

import requests

url = "https://api.thumbnail.ws/api/YOUR-FREE-API-KEY/thumbnail/get"
params = {"url": "https://www.google.com/", "width": 640}

response = requests.get(url, params=params)

with open("screenshot.jpg", "wb") as f:
    f.write(response.content)

HQAPI.com example:

import requests
import json

token = "YourToken01"
api_url = f"https://api.eu-west.hqapi.com/api/v1/{token}/screenshot/create"

payload = {
    "url": "https://www.google.com/",
    "browser_width": 1024,
    "browser_height": 768,
    "image_width": 640,
    "format": "jpeg"
}

response = requests.post(api_url, data=json.dumps(payload), headers={"Content-Type": "application/json"})

with open("screenshot.jpg", "wb") as f:
    f.write(response.content)

6. Migration Checklist

✅ Replace base URL with HQAPI endpoint
✅ Replace API key with HQAPI token
✅ Switch to JSON-based POST requests
✅ Add browser_height if you need non-default viewport
✅ Use image_width instead of width
✅ Test image output and format (png vs jpeg)
✅ Remove SOAP-based integrations
✅ Add new options like hide_cookie_popups or theme