How to Convert HTML Files to PDF with CloudConvert API

To convert a webpage to PDF with CloudConvert API v2, authenticate with a Bearer API key and create a job containing a capture-website task with output_format set to pdf, followed by an export/url task. For an HTML file you already have, use the HTML-file input route documented for the HTML-to-PDF API or build the appropriate import and conversion tasks; confirm the exact payload for that route in the current documentation.

CloudConvert processes files through named tasks inside a job. Its dedicated HTML-to-PDF API describes Chrome-based rendering and options such as page size, margins, zoom, headers, and footers. Those are vendor-described capabilities; check the current operation reference for supported fields and values before relying on a specific setting. CloudConvert HTML-to-PDF API.

1. Choose the input and completion flow

First decide whether the source is a URL or an HTML file, then choose how your application will receive the result.

Choice	Use it when	Important consideration
Website URL	The page is reachable by CloudConvert and should be rendered as a webpage.	Protected pages may need supported authentication or access arrangements; test the actual page and its resources.
HTML file	Your application has generated or assembled the HTML already.	Use the dedicated API’s HTML-file input path or the documented import/convert flow. The precise payload depends on the chosen route.
Synchronous response	A short, on-the-fly conversion can return immediately.	A request may take longer than a client or intermediary timeout. CloudConvert’s documented example uses its synchronous host with `redirect: true`.
Asynchronous job	Production workloads, queued work, or conversions with uncertain duration.	Receive the job, then handle completion with a webhook or status retrieval and polling.
URL export	Your application can fetch a temporary downloadable result.	Retrieve the URL from the completed export task; handle its lifetime according to the current documentation.
Storage export	The output should go to integrated object storage.	Use the matching provider-specific export task for S3, Azure, Google Cloud, or OpenStack.

2. Create and scope an API key

Create an API key in your CloudConvert account.
Grant only the scopes the integration needs. Job creation requires task.write; reading task status requires task.read.
Keep the key on your server or in a secret manager. Do not expose it in browser JavaScript, a public repository, or a client-visible URL.
Send it using Authorization: Bearer API_KEY.

See CloudConvert API authentication and getting started, the jobs reference, and the tasks reference.

3. Convert a webpage URL to PDF

The following is CloudConvert’s documented job shape for website capture. It requests screen CSS media and exports the result through a URL. The synchronous example submits to https://sync.api.cloudconvert.com/v2/jobs and sets redirect to true. Check the current capture operation reference for other supported rendering fields and values.

curl -X POST "https://sync.api.cloudconvert.com/v2/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": {
      "capture-my-website": {
        "operation": "capture-website",
        "url": "https://example.com",
        "output_format": "pdf",
        "css_media_type": "screen"
      },
      "export-my-file": {
        "operation": "export/url",
        "input": "capture-my-website"
      }
    },
    "redirect": true
  }'

The job tasks form a small dependency graph: the export task consumes the output named by capture-my-website. Task names are your labels; keep them unique within a job and make the export input match the capture task name. The API’s general job flow is asynchronous by default; use the standard job endpoint and completion handling for work that may queue or outlast a synchronous connection. See Capture Website and the Jobs API reference.

4. Submit a job and check completion

For a production integration, create the job through the standard asynchronous API, persist the returned job or task identifiers, and finish work when CloudConvert reports completion. Configure a webhook or retrieve status and poll with a bounded interval and overall deadline. Do not keep an application request open indefinitely: CloudConvert notes that jobs may queue and network clients may time out.

Submit the job with the required task definitions and Bearer token.
Store the job ID and associate it with your own request or record.
Wait for a webhook, or query job/task status using a key with the required read scope.
When the export task completes, read its result and fetch the output URL or use the configured storage destination.
Mark the application request complete only after confirming that the export succeeded and the result is available.

The precise status fields and result structure are defined by the live API reference. Avoid assuming a job is complete just because the creation request succeeded: the normal API can initially return a job in processing status. See Jobs and Tasks.

5. Convert an existing HTML file

When your application already has an HTML file, use the HTML-file input route described by CloudConvert’s dedicated HTML-to-PDF API. The operation payload differs from website capture, so do not substitute a local filename into the URL example above. Consult the current API operation reference or Job Builder to establish the exact input field, upload or import task, and output task sequence for your selected route.

The general file-conversion job pattern is import, convert, then export. An illustrative shape is:

{
  "tasks": {
    "import-source": {
      "operation": "import/url",
      "url": "https://your-host.example/report.html"
    },
    "convert-to-pdf": {
      "operation": "convert",
      "input": "import-source",
      "output_format": "pdf"
    },
    "export-result": {
      "operation": "export/url",
      "input": "convert-to-pdf"
    }
  }
}

This illustrates the task relationships, not a complete HTML-file upload recipe. import/url is suitable only when the source is available from a URL supported by that import operation. For content on a local disk or in application memory, use the documented file upload or storage import path and verify whether the HTML conversion operation needs additional inputs. The Quickstart Guide describes the generic import/convert/export pattern and recommends provider-specific import and export tasks for object storage.

6. Rendering options to evaluate

Set only options relevant to the desired document. The product page describes page size, margins, zoom, headers, and footers; the website capture example also shows css_media_type. Exact option names, allowed values, and availability can change, so validate them against the live Capture Website operation or the HTML-to-PDF API documentation.

Setting or concern	What to decide
CSS media type	Choose whether the page should use screen or print styles. The documented example sets `css_media_type` to `screen`; test the desired layout.
Page size and margins	Match the intended paper dimensions and printable area. Check for clipped wide content and unexpected page breaks.
Zoom	Adjust scale when content is too small or overflows. Recheck pagination after changing it.
Headers and footers	Use when the output needs repeated page context such as a title or page numbering. Verify exact supported templates and fields.
Dynamic content	Allow the page’s scripts and data to reach the intended state before capture. Validate behavior on pages that update after initial load.
Fonts and protected resources	Confirm that fonts, stylesheets, images, and other assets are accessible to the renderer. A page can load while individual resources fail.

7. Validate the PDF for real page behavior

Before rolling a conversion into a workflow, test representative documents rather than relying on a successful job status alone. Include short and long pages, local and remote assets, scripts, custom fonts, protected resources, and pages with print CSS if those occur in your workload. Review page breaks, image loading, scale, headers and footers, and whether content near the edges is clipped. CloudConvert describes Chrome-based rendering, but the research available for this guide includes no independent rendering tests or guarantees for every site.

8. Troubleshooting

Symptom	Likely cause	Fix
Unauthorized response	Missing, malformed, expired, or incorrect Bearer token.	Send `Authorization: Bearer YOUR_API_KEY`; verify the key is active and stored server-side.
Permission or scope error	The key lacks the permission for the requested operation.	Grant the minimum required scopes: `task.write` to create jobs and `task.read` to read status.
Job accepted but no PDF yet	Job creation is asynchronous and the job is still queued or processing.	Use a webhook or status retrieval and polling; consume the result only after the export task completes.
Client request times out	The job queued or took longer than the client or proxy timeout.	Use the asynchronous flow for longer work instead of holding the request open. Apply a bounded polling deadline or webhook handling.
Invalid operation or option	Payload fields or values do not match the current operation schema.	Check the live operation reference or Job Builder, especially when using the HTML-file route or optional rendering parameters.
Source cannot be imported	The URL is unreachable by the service, or the chosen import operation does not fit a local or protected file.	Use the supported upload or storage import route for the source location and confirm access from the conversion service.
PDF is missing styles, images, or fonts	Resources failed to load, require authentication, or are not ready when capture begins.	Check resource URLs and access, test representative pages, and confirm when dynamic content becomes ready before capture.
Layout differs from browser view	Screen and print CSS differ, or page size, margins, and zoom change pagination.	Choose the appropriate media type and tune page options; inspect page breaks and clipping after each change.
Export task fails after conversion	The export task configuration or destination does not match the output flow.	For a downloadable result, connect `export/url` to the correct preceding task. For object storage, select the matching provider-specific export task.

9. Performance, reliability, and cost

CloudConvert jobs can queue, and synchronous requests can run into client timeouts. Asynchronous completion through webhooks or status checks is therefore the safer integration pattern for longer or production workloads. Store job identifiers, make completion handling safe to repeat, and avoid treating a retry of job creation as equivalent to retrying a status read; use your own request tracking to prevent accidental duplicate conversions.

CloudConvert’s HTML-to-PDF page displayed a starting price of $0.008 per file at the time of research. This is a volatile starting price, not a total cost estimate or quote for a particular workload. Check current pricing and plan conditions before estimating costs. The research did not identify independent conversion-speed or accuracy benchmarks. HTML-to-PDF API pricing and product details.

10. Alternative for screenshot output: ScreenshotNeo

If the actual deliverable is a screenshot of a webpage, ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo. It returns PNG, JPEG, WebP, or PDF from one GET request, and accepts the parameter names used by other screenshot APIs to make switching easier. For an HTML document that needs PDF pagination and document controls, follow the CloudConvert workflow above; for a clean webpage capture, try ScreenshotNeo first.

Or skip the browser setup

One call captures a URL as a PDF. See the ScreenshotNeo API documentation for options and setup.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

These examples use the supplied default WebP output; configure the requested output format for PDF using the API documentation. ScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.

FAQ

Does creating a CloudConvert job mean the PDF is ready?

No. The regular API flow is asynchronous and can initially return a job in processing status. Wait for completion and a successful export task before retrieving the result.

Can I convert a local HTML file using the URL capture example?

No. The capture example takes a webpage URL. Use the documented HTML-file input or upload/import route for a file your application already has.

Should I use screen or print CSS?

Use the style that matches the intended PDF. The documented website capture example sets screen media; pages designed for printed output may need print styles. Inspect representative output.

Can CloudConvert write the PDF directly to my storage?

The API supports provider-specific export tasks for integrated storage. Use the matching export operation and configuration for your provider instead of export/url.