Use a maintained browser renderer or a PDF API when you replace wkhtmltopdf. With thirds.ai, you send HTML or a saved template with data and get a PDF back. Start with one invoice, compare the downloaded file with your old output, and adjust the layout before you move more documents. This guide gives you a small API recipe and the checks that matter during the move. Each successful PDF costs one credit.
Is wkhtmltopdf deprecated?
The main wkhtmltopdf repository is archived and read-only. GitHub records the archive date as 2 January 2023. That's a good reason to review an old dependency. It doesn't mean every existing installation fails. The project repository records its status, and the maintainer's status page explains the older Qt WebKit engine.
For a new workflow, choose between running a maintained renderer yourself and sending documents to a service. Compare your actual page breaks, fonts, asset handling, and operating work. A change of renderer can change the output even when the HTML stays the same. The DocRaptor comparison covers another PDF service.
How to convert HTML to PDF using wkhtmltopdf?
The old command has an input and output, such as wkhtmltopdf --page-size A4 invoice.html invoice.pdf. The command reference lists its options. To replace it, send the HTML text to POST /v1/pdf, or save the design once and send its ID with new data.
The migration guide maps margins, page size, headers, and JavaScript settings. It also names options with no direct match. A local file path or page URL is not an HTML request body. Read the file in your app first and send its text. Check print styles and assets that previously relied on your local machine.
Run one saved-template example
This gallery invoice gives you a fixed design for the first check. The recipe uses its sample data, so the picture and source describe the same sample. A render can still vary with fonts and renderer changes.
Open the template in the editor, keep its source and schema, and publish your copy. Read the template ID and version from your template list. Set THIRDS_TEMPLATE_ID and THIRDS_TEMPLATE_VERSION to those values. Set THIRDS_API_KEY through your secret store. None of those setup steps needs an AI call.
You only need curl on macOS or Linux. No SDK is needed. Make a private work folder first:
umask 077
THIRDS_WORK=$(mktemp -d)
Save this JSON as request.json in that folder. Put your template ID and version in it. The values are a short version of the sample data on the template's source page.
{
"template_id": "tpl_00000000000000000000000000000000",
"version": 1,
"data": {
"business_name": "Northline Studio",
"business_email": "hello@northlinestudio.co.uk",
"client_name": "Fieldnote Labs",
"client_email": "accounts@fieldnotelabs.co.uk",
"invoice_number": "NS-1042",
"issued_on": "2026-10-03",
"items": [
{
"description": "Product launch identity and packaging",
"amount": 2400
},
{ "description": "Campaign photography set, 12 images", "amount": 850 },
{ "description": "Social media template pack", "amount": 320 }
],
"subtotal": 3570,
"tax": 714,
"total": 4284,
"payment_terms": "Payment is due within 14 days. Amounts are shown in US dollars.",
"payment_note": "Please use NS-1042 as your payment reference when you pay."
},
"wait": false
}
Check the template, version, and values. The next command creates one PDF and costs one credit on success. Choose your own Idempotency-Key for it.
curl --fail-with-body --silent --show-error \
https://thirds.ai/v1/pdf \
-H "Authorization: Bearer $THIRDS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: YOUR_UNIQUE_INVOICE_REQUEST' \
--data-binary @"$THIRDS_WORK/request.json"
Keep the id from the response. Read the job until its status is succeeded, and replace the sample ID with yours:
curl --fail-with-body --silent --show-error \
https://thirds.ai/v1/pdf/pdf_00000000000000000000000000000000 \
-H "Authorization: Bearer $THIRDS_API_KEY"
Copy download.url from that response and add https://thirds.ai before it. The download doesn't need your API key.
curl --fail --silent --show-error \
'https://thirds.ai/v1/downloads/YOUR_SIGNED_DOWNLOAD_TOKEN' \
--output "$THIRDS_WORK/output.pdf"
Open output.pdf. The job's artifact field has the file's byte_size and sha256 if you want to check your download. If the create command stops, send it again with the same Idempotency-Key and the same request.json. A new key makes a new PDF.
Compare the old and new PDF at the same zoom. Check page count, margins, long item names, totals, and the last page. This sample proves the new API path. To check your own migration, repeat with your existing HTML and approved records using the migration guide.
Is wkhtmltopdf safe to use?
The maintainer warns against processing untrusted HTML with wkhtmltopdf. Read the project's security guidance before you expose an old command to customer input. HTML can load assets and exercise the renderer, so a file extension is not a trust check.
When you use thirds.ai, keep credentials out of HTML and image URLs. Use the supported private asset path for account files. The render limits and PDF options describe accepted input and limits. Inspect the finished file before you deliver it.
Fix errors without creating duplicate files
| Code or state | Next step |
|---|---|
template_data_invalid | Use the saved schema's required fields and types. |
unsafe_asset | Check the asset address and use a supported asset source. |
insufficient_credits | Add credits before retrying the same intended request. |
idempotency_conflict | Send the original request with its key. Use a new key only for a new intended output. |
succeeded, but the layout differs | Check print CSS, margins, fonts, and page breaks. Save the corrected design as a new version. |
What is the best alternative to PDF?
Keep PDF when the reader needs fixed pages to print or store. Use a web page when the content needs to adapt to a screen, or a PNG, JPEG, or WebP for one static image. A new file format doesn't fix an HTML layout. If PDF is still the right result, change the renderer and keep the document format.
Open the HTML to PDF page to review the workflow, then make one sample invoice. Check pricing before you run a larger comparison set. Keep both files so you can review the change.
