Docs / Parameters / url parameter | HTML to Image Docs

URL Parameter

The url parameter is required for the Screenshot API and specifies which webpage to capture.

Specifications

Property	Value
Type	string
Required	Yes
Default	None
API	Screenshot API only

Description

The URL of the webpage you want to screenshot. The URL must be:

Publicly accessible
A valid URL with protocol (http:// or https://)
Responsive within a reasonable timeout period

We strongly recommend using the webhook_url parameter with URL screenshots, as page load times can be unpredictable and may exceed the 30-second timeout limit.

Examples

Basic URL Screenshot

{
    "url": "https://example.com"
}

Response:

{
    "success": true,
    "credits_remaining": 95,
    "id": "abc123",
    "url": "https://i.html2img.com/abc123.png"
}

URL with Query Parameters

{
    "url": "https://example.com/search?q=test&page=1"
}

URL with Specific Viewport

{
    "url": "https://example.com",
    "width": 1920,
    "height": 1080
}

Some websites block or behave differently when accessed by our service. Make sure the target website does not require authentication, allows automated access, and is publicly reachable.

Common values

https://example.com/articles/123 - a public article page on a content site.
https://twitter.com/user/status/123 - a tweet permalink for screenshotting an embed.
https://app.html2img.com/templates/invoice/preview?id=42 - a public preview page on your own site.
https://news.ycombinator.com/item?id=12345 - a discussion thread.

When to use

Use the url parameter when the page already exists somewhere on the public web and you want a screenshot of it. For pages that need data injected, prefer the html parameter so you can build the markup at request time.

Common mistakes

Pointing at a localhost or intranet URL. The Screenshot API runs on our servers and cannot reach private hosts.
Forgetting redirects. A URL that returns 301 or 302 follows the redirect, but a 401 or 403 returns an error. Make sure the page is reachable without auth.
Capturing pages with cookie banners. Inject a hide selector via the css parameter before render.

Documentation