In this guide you will learn how to convert HTML to PDF in Perl using the HTML2PDF REST API. We will cover:

  • Converting a URL to PDF with Perl
  • Converting raw HTML to PDF
  • Setting page size, orientation and layout options
  • Handling errors and status codes

The HTML2PDF API accepts both URLs and HTML and returns the generated PDF in the HTTP response. You call https://api.html2pdf.co.uk/ with your license key and parameters.

Prerequisites

  • Perl 5
  • LWP::UserAgent and URI::Escape modules (installable via CPAN)
  • An HTML2PDF license key

1. Convert a URL to PDF in Perl

The example below uses LWP::UserAgent to call the API and save the PDF to disk. 

#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;
use URI::Escape;

my $ENDPOINT    = 'https://api.html2pdf.co.uk/';
my $LICENSE_KEY = 'yourlicensekey';

sub url_to_pdf {
    my ($source_url, $output_path) = @_;

    my $ua = LWP::UserAgent->new( timeout => 60 );

    my $query = 'license=' . uri_escape($LICENSE_KEY)
              . '&url='    . uri_escape($source_url);

    my $url = $ENDPOINT . '?' . $query;

    my $response = $ua->get($url);

    if (!$response->is_success) {
        die 'HTML2PDF API error: HTTP ' . $response->code . ' ' . $response->message . "\n";
    }

    open my $fh, '>:raw', $output_path or die "Cannot open $output_path: $!";
    print {$fh} $response->decoded_content;
    close $fh;

    print "PDF created at $output_path\n";
}

url_to_pdf('https://example.com', 'perl-example.pdf');

This script downloads the generated PDF and saves it as perl-example.pdf.

2. Convert raw HTML to PDF in Perl

To convert raw HTML instead of a URL, send a POST request with the html parameter. 

#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;

my $ENDPOINT    = 'https://api.html2pdf.co.uk/';
my $LICENSE_KEY = 'yourlicensekey';

sub html_to_pdf {
    my ($html, $output_path) = @_;

    my $ua = LWP::UserAgent->new( timeout => 60 );

    my %form = (
        license => $LICENSE_KEY,
        html    => $html,
    );

    my $response = $ua->post($ENDPOINT, \%form);

    if (!$response->is_success) {
        die 'HTML2PDF API error: HTTP ' . $response->code . ' ' . $response->message . "\n";
    }

    open my $fh, '>:raw', $output_path or die "Cannot open $output_path: $!";
    print {$fh} $response->decoded_content;
    close $fh;

    print "PDF created from HTML at $output_path\n";
}

my $html = '<html><body><h1>Hello from Perl</h1><p>Converted with HTML2PDF.</p></body></html>';
html_to_pdf($html, 'perl-html.pdf');

This is useful when you generate the HTML in your Perl code or template system and do not want to expose it as a public URL.

3. Setting conversion options

You can influence the PDF output by adding extra query parameters. Common options include:

  • page_size (for example A4 or Letter)
  • orientation (portrait or landscape)
  • css_media_type (screen or print)
  • lazy_load and wait_time for JavaScript-heavy pages
Tip: Set your default layout options (page size, margins, header/footer, etc.) once in the members area. You can then keep your Perl code very simple and override options only when needed. 
use strict;
use warnings;
use LWP::UserAgent;
use URI::Escape;

my $ENDPOINT    = 'https://api.html2pdf.co.uk/';
my $LICENSE_KEY = 'yourlicensekey';

sub url_to_pdf_with_options {
    my ($source_url, $output_path) = @_;

    my $ua = LWP::UserAgent->new( timeout => 60 );

    my $query = 'license='        . uri_escape($LICENSE_KEY)
              . '&url='            . uri_escape($source_url)
              . '&page_size=A4'
              . '&orientation=landscape'
              . '&css_media_type=print'
              . '&lazy_load=true'
              . '&wait_time=3000';

    my $url = $ENDPOINT . '?' . $query;

    my $response = $ua->get($url);

    if (!$response->is_success) {
        die 'HTML2PDF API error: HTTP ' . $response->code . ' ' . $response->message . "\n";
    }

    open my $fh, '>:raw', $output_path or die "Cannot open $output_path: $!";
    print {$fh} $response->decoded_content;
    close $fh;

    print "PDF created with options at $output_path\n";
}

For a complete list of options, including headers, footers and watermarks, see the HTML2PDF API documentation.

4. Handling Errors

If the API cannot deliver a PDF it returns an HTTP error code instead. Important codes are:

CodeDescription
200 OKConversion succeeded and the response body contains the PDF
400 Bad RequestNo URL or HTML was provided
401 Authorization requiredMissing or invalid license key
429 Too Many RequestsYou exceeded the limits of your plan
504 / 599Timeout or connectivity problems when fetching the URL

In Perl you can inspect $response->code and $response->message and decide whether to log the problem, show an error to the user or retry if the error was temporary.

5. Next Steps

You now have working examples for converting HTML to PDF in Perl with the HTML2PDF API. Next you can: