How to Set a Custom Page Size When CloudConvert Converts HTML to PDF

For an HTML file, create a CloudConvert convert task with input_format: "html" and output_format: "pdf". Find the custom page-size option for that exact conversion and engine in CloudConvert’s Job Builder or Operations API, then use the returned option name, type, units, and value format. Do not guess the parameter: the available options depend on the format pair and engine.

This guide covers an HTML file being converted to PDF. A live website URL is a different workflow: CloudConvert documents a separate capture-website operation. Its parameters are not proof of which options apply to HTML-file conversion. See CloudConvert’s Convert Files documentation and its separate Capture Website documentation.

1. Confirm the source and operation

First decide what you are converting:

An HTML file: use convert, with HTML input and PDF output.
A live website: investigate capture-website, which captures a URL and can produce a PDF. Do not copy its settings into a file-conversion task without verifying they apply.

The distinction matters because the operation determines which options CloudConvert exposes. This article uses an HTML file as the source.

2. Look up the current HTML-to-PDF options

Open CloudConvert’s Job Builder and select the HTML-to-PDF conversion, or query the Operations API.
Inspect the options for the exact input format html, output format pdf, and engine/version you intend to use.
Find the option that describes custom page dimensions. Record its exact name, data type, accepted value shape, units, defaults, and whether width and height must be supplied together.
Use those returned details in the convert task. Recheck them if you change the engine or conversion pair.

CloudConvert’s Operations API reference describes listing operations and including option details such as names, types, defaults, descriptions, possible values, and engine/version information. The Quickstart Guide describes the import, convert, and export task pattern and points to the Job Builder for available options.

The material cited here does not establish the exact HTML-to-PDF page-size field, units, or value syntax. Those details must come from the current Job Builder or Operations API response; the placeholder below is deliberately not a literal request.

3. Build the import, convert, and export job

A typical job imports the HTML, converts it, then exports the PDF. Replace the placeholder key and value with the exact option and documented value returned for your selected conversion:

{
  "tasks": {
    "import-html": {
      "operation": "import/url",
      "url": "https://example.test/document.html"
    },
    "convert-html-to-pdf": {
      "operation": "convert",
      "input": "import-html",
      "input_format": "html",
      "output_format": "pdf",
      "<option-name-from-current-html-to-pdf-options>": "<documented-value>"
    },
    "export-pdf": {
      "operation": "export/url",
      "input": "convert-html-to-pdf"
    }
  }
}

This is a task-structure example, not a complete authenticated HTTP request. Add the authentication and job submission steps required by your CloudConvert integration. Do not send the angle-bracket placeholders as option names or values.

4. Validate the resulting PDF

Run a conversion with the intended HTML source and the documented custom dimensions.
Check the resulting PDF’s page dimensions with your PDF viewer or inspection tool.
Check every page if the document has multiple pages; page-size behavior and pagination are separate concerns.
Keep a small fixture document with known content and dimensions so you can detect changes after updating the engine, templates, or conversion settings.

No conversion was run for this guide, so it makes no claim about observed output. Confirm the dimensions in your own generated PDF before relying on them in production.

Options and details to verify

Detail	What to check
Option name	Copy the exact name returned for HTML input and PDF output. Do not infer it from another CloudConvert operation.
Value type and shape	Check whether the option expects a number, string, object, or separate width and height fields.
Units	Use the units documented by the current option. Do not assume pixels, points, millimeters, or inches.
Dimension pairing	Confirm whether both width and height are required and whether one can be omitted to retain a default.
Engine and version	Make sure the option details correspond to the engine/version used by the job.
Defaults and allowed values	Review defaults, supported values, and any constraints returned by the option listing.

CloudConvert states that conversion parameters differ based on input_format and output_format. A parameter documented for website capture or another file conversion should not be assumed to work for HTML-to-PDF.

Edge cases to account for

HTML versus a URL: an HTML file conversion and capturing a live website are different operations. Choose based on the source you actually have.
Changing engines: re-check option names, types, defaults, and supported values when changing engine/version.
Custom dimensions versus content layout: setting a page size does not itself guarantee that HTML content fits on one page. Check wrapping, overflow, and pagination in the output.
Multi-page PDFs: verify dimensions across pages and test long content; do not infer all-page behavior from a short one-page fixture.
External assets: if the HTML references stylesheets, fonts, or images, ensure they are available to the conversion process and that the document renders as expected before diagnosing page size.
Stale examples: if an older snippet conflicts with current option details for your selected conversion, use the current operation response as the source of truth.

Troubleshooting

Symptom	Likely cause	What to do
The API rejects the page-size parameter	The option name or value shape does not match the selected HTML-to-PDF operation, or the option belongs to a different operation.	Retrieve the current options for HTML input, PDF output, and the chosen engine. Copy the exact name and type.
The job accepts the request but uses an unexpected size	The value may be in different units, a default may apply, or the setting may not be the option for this conversion pair.	Review the option details and defaults, then inspect the actual PDF page dimensions.
Width or height is ignored	The option may require both dimensions or a particular combined value format.	Check the option’s documented shape and whether width and height must be supplied together.
A website-capture example does not work in a convert task	`capture-website` and file `convert` are separate operations with their own parameters.	Use `convert` for an HTML file and inspect its options, or choose website capture if the source is a live URL.
Page size is right but content clips or spans extra pages	Page dimensions and HTML layout/pagination are distinct; content may exceed the printable area or wrap differently.	Inspect the rendered PDF, adjust the HTML/CSS, and validate with representative long and short documents.
The output changes after an engine update	The available options or rendering behavior may differ by engine/version.	Query the options for the current engine/version and rerun the PDF dimension and layout checks.

Performance, reliability, and cost considerations

For repeatable conversions, keep the source format, target format, engine/version, and page-size option explicit in the job configuration. Validate a representative fixture when any of those change. The Operations API can help prevent guesswork by exposing the current option metadata for the selected conversion.

Do not treat successful job submission as proof that the PDF has the intended physical page dimensions or that all content fits. Inspect the generated artifact. This guide does not state CloudConvert prices, conversion timing, or service guarantees because the cited research does not establish them; consult CloudConvert’s current product and account information for those details.

Or skip the browser setup

If the actual goal is a screenshot of a live webpage rather than a PDF made from an HTML file, ScreenshotNeo is a website screenshot API and MCP server. Its API returns PNG, JPEG, or WebP screenshots, or a PDF. For a live page, a single GET request can produce a PDF:

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

See the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie and 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/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.

FAQ

Can I use a page-size option from CloudConvert’s website capture operation?

Only if the current documentation for the operation you are actually using exposes that option. Website capture and HTML-file conversion are separate workflows.

Can I copy a custom-size parameter from another format conversion?

No. Confirm the option against the HTML-to-PDF pair and selected engine/version.

Does setting a custom page size guarantee a one-page PDF?

No. Page size describes the page dimensions; the HTML content and pagination determine how many pages are produced.