HTML to Image / HTTP API Documentation

Overview

The HTTP API provides direct access to PDFCrowd's conversion service without requiring library installation. Send an HTTP POST request to convert to image from any programming language or platform that supports HTTP requests.

Getting started: Jump to Quick Start for working examples. For technical details about request format, authentication, and response handling, see HTTP Request and HTTP Response. For complete parameter documentation, visit the Parameter Reference.

Quick Start

The following examples demonstrate progressive use of the HTTP API, from basic conversion to advanced customization. Each example is complete and ready to use - just replace the file paths with your own. You can also explore our additional examples for more code samples.

Examples below use demo credentials for testing. For production use, start a free trial or purchase a 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/

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

For production use, start a free trial or purchase a 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 guide helps you diagnose and resolve common HTTP API issues. If you encounter problems, try the solutions below before contacting support.

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.

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

API Parameter Reference

Refer to the HTML to Image API Parameter Reference for a detailed description of all parameters.