HTML to Image HTTP API

Overview

Convert a web page, HTML string, or uploaded HTML file to an image with a direct HTTP request from any language or platform. For language-specific client libraries, see the SDK guides.

Quick Start

Choose an input below.

Each example uses cURL and saves the returned image to a local file. If a conversion fails, inspect the response for error details.

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

curl -f -s -S \
  -u 'demo:demo' \
  -o document.png \
  -F file=@document.html \
  -F output_format=png \
  https://api.pdfcrowd.com/convert/24.04/

Build a Request

Authentication

Use your PDFCrowd username as the HTTP Basic username and your API key as the password. Configure these credentials using your HTTP client's Basic authentication option.

These credentials authenticate the conversion request to PDFCrowd. To load a protected source website, configure its authentication separately using website credentials, cookies, or a custom HTTP header.

Request Format

Send the input and conversion settings as form fields in a POST request. JSON request bodies are not supported. Your HTTP client handles form encoding and the appropriate headers.

Use the versioned endpoint: https://api.pdfcrowd.com/convert/24.04/. Keep the version explicit in your integration and review API versioning before changing it.

Errors are returned as plain text by default; add ?errfmt=json to the endpoint to receive JSON errors. This changes only the error format; a successful response still contains the converted image. See Handle the Response for response handling.

Choose an Input

Supply one of the following inputs for your conversion:

If your application renders HTML from a template, send the rendered HTML using text. PDFCrowd can also combine an HTML template with structured data; see the HTML Template to Image guide.

For file, upload the file's contents. Sending a filename or local path as a text field does not provide the document to PDFCrowd.

PDFCrowd cannot fetch a page from your computer's localhost. Upload the HTML or send its content in text instead.

Send HTML Content

Send HTML content in the text form field. Pass the HTML string to your HTTP client and let it encode the form. This example reads the HTML from an existing document.html file and saves the result as html.png:

curl -f -s -S \
  -u 'demo:demo' \
  -o html.png \
  -F 'text=<-' \
  -F output_format=png \
  https://api.pdfcrowd.com/convert/24.04/ < document.html

For uploaded HTML or HTML content, use absolute URLs for remote assets, or add an HTML <base href="https://example.com/"> element to resolve relative URLs. These URLs must be accessible to PDFCrowd.

Include Local Assets

Package the HTML and its local images, CSS, and JavaScript in a .zip, .tar.gz, or .tar.bz2 archive. Preserve the relative paths used by the HTML, then upload the archive in the file field. This example uploads an existing document.zip:

curl -f -s -S \
  -u 'demo:demo' \
  -o output.png \
  -F file=@document.zip \
  -F output_format=png \
  https://api.pdfcrowd.com/convert/24.04/

Set zip_main_filename to the name of the HTML document to convert, such as index.html. This is especially useful when the archive contains several HTML files. Resources hosted at accessible internet URLs can be loaded directly.

Add Conversion Settings

Send conversion settings as additional form fields alongside your input. Common options include:

The parameter reference lists all settings, accepted values, defaults, and constraints. Use the API Playground to try settings and generate request examples. For complete conversion requests, see the HTTP examples. See also the guides below.

Handle the Response

Successful Conversion

A successful conversion returns 200 OK with the image bytes in the response body. Save those bytes to a file or return them to your application's user.

An illustrative response is:

HTTP/1.1 200 OK
Content-Type: image/png
x-pdfcrowd-job-id: example-job-id

[PNG bytes]

Check the HTTP status before processing the body. Treat a successful response as binary data; parsing it as JSON or decoding it as text will not produce a usable image.

This example shows PNG. The response content type follows the selected output format, such as image/png for PNG.

Errors

An unsuccessful request returns an error HTTP status. PDFCrowd error responses also include a reason code that identifies the specific problem.

By default, the error body is plain text in this format:

<status_code>.<reason_code> - <message>

For structured errors, append ?errfmt=json to the endpoint:

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

An example JSON error body for missing conversion input is:

{
  "status_code": 400,
  "reason_code": 325,
  "message": "There is no input specified to be converted."
}

PDFCrowd JSON errors use Content-Type: application/json. A successful request still returns an image when errfmt=json is set. If a failed response has a different content type, retain its body and status for diagnosis instead of assuming it is JSON.

Common Status Codes

See all status and reason codes for specific error explanations. For request limits and retry guidance, see Limits and Retries.

Response Headers

Use these headers, when present, to record conversion results and diagnose problems:

Limits and Retries

Request rate and concurrency limits depend on your license. Control how quickly you submit conversions and how many you run at once. A 429 response concerns request rate; a 430 response concerns requests already in progress.

The maximum upload size is 300 MB. The maximum size for any created image is 65 megapixels. Images exceeding this size are cropped vertically to meet this limit.

For temporary failures, use a bounded number of retries with increasing delays. Correct invalid input, authentication, or account problems before retrying those requests.

If a conversion exceeds 60 seconds of processing time, PDFCrowd stops it and returns an error response.

If PDFCrowd returns reason code 323, the conversion exceeded its processing time. Check for slow resource downloads or long-running JavaScript. Increasing the HTTP client's timeout does not fix that server-side conversion failure.

Troubleshooting

Inspect a Request

Capture the HTTP status, response headers, and response body when diagnosing a request. Set debug_log to true to enable a conversion debug log, and add errfmt=json to the endpoint's query string for structured error details. Use the input and conversion settings from the request you're investigating.

curl --fail-with-body \
  -u 'demo:demo' \
  -D response.headers \
  -o response.body \
  -w 'HTTP %{http_code}\n' \
  -F url=http://www.example.com \
  -F output_format=png \
  -F debug_log=true \
  'https://api.pdfcrowd.com/convert/24.04/?errfmt=json'

Check the HTTP status before interpreting the body. A successful response contains image bytes; an unsuccessful response should be inspected for error details. If no HTTP response arrives, check the error reported by your HTTP client.

The x-pdfcrowd-debug-log header links to resource-loading details, timeouts, and browser console messages. You can also find logs in your conversion history.

Common Problems

For help, contact support and include any available diagnostics and enough detail for us to reproduce the problem.