---
title: "Generate a screenshot using cURL"
description: "Learn how to generate a screenshot using cURL using the HTML to Image API. With full examples, including dimensions and webhook usage."
url: "https://html2img.com/articles/generate-a-screenshot-using-curl/"
section: "Tutorials"
published: "2025-01-13T16:44:44.335Z"
updated: "2026-06-29T08:37:06.941Z"
---

# Generate a screenshot using cURL

By Mike Griffiths. https://html2img.com/articles/generate-a-screenshot-using-curl/

![Generate a screenshot using cURL](https://a.storyblok.com/f/320619/1200x630/654ef40e89/generate-a-screenshot-using-curl.png)

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](https://app.html2img.com/).
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](https://html2img.com/docs/parameters/).

## Step 3: Write the cURL Command

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

```bash
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:

```bash
{
    "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:

```bash
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:

```bash
{
    "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](https://html2img.com/docs/parameters/) for more advanced features.