HTML to Image HTTP API Documentation

Overview

This document describes direct HTTP access to the HTML to Image API. It supports converting a URL, an uploaded HTML file, or an HTML string to an image. If you prefer a language-specific client library, see the Official SDKs.

Quick Start

Start by running one of the complete cURL commands below. These commands use direct HTTP POST requests and cover URL, file, and HTML string input.

The API uses HTTP Basic authentication. The commands below use demo credentials and work as-is. You can obtain your own PDFCrowd username and API key from a free trial or API license.

curl -f -u "demo:demo" \
    -o "example.png" \
    -F "output_format=png" \
    -F "url=http://www.example.com" \
    https://api.pdfcrowd.com/convert/24.04/

curl -f -u "demo:demo" \
    -o "output.png" \
    -F "output_format=png" \
    -F "file=@/path/to/your/document.html" \
    https://api.pdfcrowd.com/convert/24.04/

curl -f -u "demo:demo" \
    -o "output.png" \
    -F "output_format=png" \
    -F "file=@/path/to/your/archive.zip" \
    https://api.pdfcrowd.com/convert/24.04/

generate_html | curl -f -u "demo:demo" \
    -o "html.png" \
    -F "output_format=png" \
    -F "text=<-" \
    https://api.pdfcrowd.com/convert/24.04/

curl -f -u "demo:demo" \
    -o "customized.jpg" \
    -F "screenshot_width=1280" \
    -F "output_format=jpg" \
    -F "scale_factor=50" \
    -F "url=http://www.example.com" \
    https://api.pdfcrowd.com/convert/24.04/

curl -f -u "demo:demo" \
    -o "custom_css.png" \
    -F "output_format=png" \
    --form-string "custom_css=
        /* Hide navigation, ads, and sidebar */
        nav, .advertisement, .sidebar, footer {
            display: none !important;
        }
        /* Adjust layout for screenshot */
        .content {
            width: 100% !important;
            max-width: none !important;
        }
    " \
    -F "url=http://www.example.com" \
    https://api.pdfcrowd.com/convert/24.04/

curl -f -u "demo:demo" \
    -o "custom_js.png" \
    -F "output_format=png" \
    --form-string "custom_javascript=
        // Remove dynamic content before conversion
        document.querySelectorAll('.video-player, .chat-widget').forEach(el => {
            el.remove();
        });
        // Expand collapsed sections
        document.querySelectorAll('.collapsed').forEach(el => {
            el.classList.remove('collapsed');
        });
    " \
    -F "url=http://www.example.com" \
    https://api.pdfcrowd.com/convert/24.04/

# Wait for a specified time before conversion
curl -f -u "demo:demo" \
    -o "with_delay.png" \
    -F "output_format=png" \
    -F "javascript_delay=2000" \
    -F "url=http://www.example.com" \
    https://api.pdfcrowd.com/convert/24.04/

# Wait for a specific element to appear
curl -f -u "demo:demo" \
    -o "wait_element.png" \
    -F "output_format=png" \
    -F "wait_for_element=#content-loaded" \
    -F "url=http://www.example.com" \
    https://api.pdfcrowd.com/convert/24.04/

curl -f -u "demo:demo" \
    -o "print_media.png" \
    -F "output_format=png" \
    -F "use_print_media=true" \
    -F "url=http://www.example.com" \
    https://api.pdfcrowd.com/convert/24.04/

<nav class="pdfcrowd-remove">This won't appear in the screenshot</nav>
<div class="pdfcrowd-hide">This is invisible but takes up space</div>

<style>
  /* These styles only apply during image conversion */
  .pdfcrowd-body h1 { font-size: 48px; }
  .pdfcrowd-body footer { display: none; }
  .pdfcrowd-body .main-content { width: 100%; }
</style>

HTTP Request

All conversion API requests are sent as POST requests to the conversion endpoint. This section covers the technical details, including endpoint URLs, authentication methods, parameter format, and request structure.

Endpoint

https://api.pdfcrowd.com/convert/24.04/

Show older API versions

Authentication

The API uses HTTP Basic authentication with a PDFCrowd username and API key. To get started quickly, you can use these demo credentials for testing:

• Username: demo
• API key: demo

Use your own PDFCrowd username and API key for production. You can obtain API credentials from a free trial or API license.

Show authentication details

POST Parameters

Conversion settings and options are sent as parameters in the POST request body to configure the conversion. For a complete list of available parameters and their descriptions, see the Parameter Reference.

URL Parameters

The following optional parameter can be appended to the endpoint URL:

• errfmt – Specifies the error response format (see HTTP Response)
  • txt – Returns errors in plain text format (default)
  • json – Returns errors in JSON format

Example: https://api.pdfcrowd.com/convert/24.04/?errfmt=json

Request Format

The Content-Type header must match the request body format. Most HTTP libraries and tools set this automatically based on how you structure your request.

• multipart/form-data – Required when uploading local files
• application/x-www-form-urlencoded – May be used when no files are uploaded

Note: If you are using a standard HTTP client library or tool, the Content-Type is typically set automatically. You only need to set this manually when working with low-level HTTP libraries.

HTTP Response

The API returns different responses based on the conversion outcome. This section explains HTTP status codes, response body formats for both successful conversions and errors, and response headers containing conversion metadata.

Success Response

HTTP Status: 200 OK

The converted file is returned in the response body. The Content-Type header is set to the appropriate MIME type for the output format.

Error Response

HTTP Status: 4xx (client error)

Error details are returned in the response body. The format is controlled by the errfmt URL parameter (see HTTP Request).

Text Format (errfmt=txt, default)

Content-Type: text/plain

<status_code>.<reason_code> - <message>

JSON Format (errfmt=json)

Content-Type: application/json

{
  "status_code": <http_status_code>,
  "reason_code": <specific_error_code>,
  "message": "<error_message>"
}

For a complete list of status codes and reason codes, see API Status Codes.

Response Headers

The HTTP response includes the following headers with additional information about the conversion:

Troubleshooting

This section helps diagnose common HTTP API issues and points to the relevant settings, examples, and support information.

Common Issues

Debugging Tools and Techniques

Debug Log

Use the debug_log parameter to capture detailed information about the conversion process on PDFCrowd servers, including resource loading, timeouts, browser console output, and load times. Set it to true to enable it.

The debug log URL is returned in the x-pdfcrowd-debug-log HTTP response header and is also available in your conversion log.

Inspect Failed cURL Requests

Use this command when the API returns HTTP status 400 or higher and you need to inspect the error response. It preserves the response body, saves response headers, and requests structured JSON error details.

curl --fail-with-body -u "demo:demo" \
    -D headers.txt \
    -o error-response.json \
    -F "url=http://www.example.com" \
    "https://api.pdfcrowd.com/convert/24.04/?errfmt=json"

--fail-with-body keeps the error body visible while still returning a non-zero exit status, -D headers.txt saves response headers, and errfmt=json returns structured error details.

API Status Codes

If you receive an error, refer to the API Status Codes page for detailed explanations of specific error codes. You can also use errfmt=json in the endpoint URL to get structured error responses (see HTTP Response).

Getting Help

If you're still experiencing issues after trying these solutions:

• Review the API Status Codes for specific error code explanations
• Check the FAQ for answers to common questions
• Visit the Parameter Reference for detailed configuration options
• Contact support with the information below

When contacting support, please include:

• Your complete curl command (or HTTP request details)
• The source URL or HTML file you're trying to convert
• Any error messages or HTTP status codes received
• Debug log output (if available)
• Expected behavior vs. actual result