Generate a screenshot using cURL

Capturing screenshots of webpages can be a powerful tool for developers, marketers, and content creators. Whether you’re automating a task, archiving a page, or creating dynamic visuals for reports, using HTML2Img’s API makes the process seamless. In this guide, we’ll show you how to generate a screenshot of a webpage using cURL.

Prerequisites

Before we dive in, ensure you have:

1. Access to the our API.

2. A valid API key.

3. cURL installed on your machine (most systems come with it pre-installed).

Step 1: Understand the API Endpoint

HTML to Image provides a REST API endpoint for generating screenshots:

POST https://app.html2img.com/screenshot

You will send a JSON payload with parameters to customize your screenshot.

Step 2: Choose Your Parameters

Here are some commonly used parameters:

• url (string, required): The URL of the webpage you want to capture. It must be publicly accessible.

• webhook_url (string, optional): A URL to receive asynchronous updates when the screenshot is ready.

• width (integer, optional): The viewport width (default: 1440).

• height (integer, optional): The viewport height (default: 900).

• fullpage (boolean, optional): Whether to capture the entire page (default: false).

• ms_delay (integer, optional): Delay in milliseconds before capturing (useful for animations or slow-loading content).

For the full list of parameters, check out the documentation.

Step 3: Write the cURL Command

To generate a screenshot, create a cURL command like the one below:

curl -X POST https://app.html2img.com/screenshot \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: YOUR_API_KEY" \
     -d '{
          "url": "https://example.com",
          "fullpage": true,
          "width": 1920,
          "height": 1080,
          "ms_delay": 1000
     }'

Breakdown of the Command

1. -X POST: Specifies the HTTP method.

2. -H: Adds headers for content type and authorization using the X-API-KEY header.

3. -d: Provides the JSON payload with parameters like url, fullpage, and ms_delay.

Step 4: Handle the API Response

When you send the request, the API will return a JSON response like this:

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

The url field contains the link to the generated screenshot. You can download it or use it as needed.

Step 5: Use Webhook for Large Requests

For large or complex captures (e.g., fullpage screenshots), consider using the webhook_url parameter. This allows the API to process the request asynchronously and notify your server when the screenshot is ready. Example:

curl -X POST https://app.html2img.com/screenshot \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: YOUR_API_KEY" \
     -d '{
          "url": "https://example.com",
          "fullpage": true,
          "webhook_url": "https://your-domain.com/webhook"
     }'

Webhook Response:

{
    "status": "success",
    "url": "https://i.html2img.com/image-1641234567890-123456.png"
}

Using cURL with the HTML2Img API is an efficient way to automate screenshot generation. With customizable options and asynchronous processing, you can tailor the output to your exact needs. Explore the API documentation for more advanced features.