PDF to Image in Go

Overview

Convert PDF pages to images with the PDFCrowd Go client. The client handles communication with the API, while conversions run on PDFCrowd's servers.

Installation

Add the Go client to your module with go get, or see other installation options.

go get github.com/pdfcrowd/pdfcrowd-go

Quick Start

Update the input URLs and filenames as needed.

package main

import (
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewPdfToImageClient("demo", "demo")

    client.SetForceZip(true)
    client.SetOutputFormat("png")
    err := client.ConvertUrlToFile(
        "https://your-server.com/invoice.pdf", "invoice.zip",
    )
    if err != nil {
        log.Print(err)
        return
    }
}

package main

import (
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewPdfToImageClient("demo", "demo")

    client.SetForceZip(true)
    client.SetOutputFormat("png")
    err := client.ConvertFileToFile("invoice.pdf", "invoice.zip")
    if err != nil {
        log.Print(err)
        return
    }
}

Configure a Conversion

Authentication

Pass your PDFCrowd username and API key to NewPdfToImageClient. Find your credentials on the API Keys page.

Choose an Input

Send a PDF URL, upload a local file, or pass PDF bytes or a readable binary stream.

Add Conversion Settings

Set conversion options on the client before calling a conversion method. For example, client.SetDpi(150) renders PDF pages at 150 DPI.

Common settings are listed below. See the method reference for all available options or browse Go examples.

Higher DPI produces larger images and files. PNG is the default image format.

The PDF password unlocks the input document; it is separate from your PDFCrowd API key.

Handle the Result

Choose an Output

A single converted page produces an image; multiple pages produce a ZIP archive containing an image for each page. The examples use SetForceZip() to always return a ZIP archive, including for a single page.

The methods below use URL input; local files, bytes, and input streams have corresponding methods.

File-output methods overwrite an existing destination file.

This example converts PDF pages to PNG images in a ZIP archive, receives the result as a []byte and saves it as invoice.zip:

package main

import (
    "log"
    "os"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewPdfToImageClient("demo", "demo")

    client.SetOutputFormat("png")
    client.SetForceZip(true)
    result, err := client.ConvertUrl("https://your-server.com/invoice.pdf")
    if err != nil {
        log.Print(err)
        return
    }
    if err := os.WriteFile("invoice.zip", result, 0644); err != nil {
        log.Print(err)
        return
    }
}

After conversion, IsZippedOutput() indicates whether the result is a ZIP archive. Match the output filename and content type to the result: .zip and application/zip for archives, or .png and image/png for a single PNG.

Handle Errors

Conversion methods return an error. API and validation errors have the type pdfcrowd.Error; local file and connection failures can return other error types. This example converts PDF pages to PNG images in a ZIP archive, logs any error, and uses errors.As to read the HTTP status and reason code when available:

package main

import (
    "errors"
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewPdfToImageClient("demo", "demo")

    client.SetOutputFormat("png")
    client.SetForceZip(true)
    err := client.ConvertUrlToFile(
        "https://your-server.com/invoice.pdf", "invoice.zip",
    )
    if err != nil {
        log.Print(err)
        var apiError pdfcrowd.Error
        if errors.As(err, &apiError) {
            log.Printf("Status: %d; reason: %d",
                apiError.GetStatusCode(), apiError.GetReasonCode())
        }
        return
    }
}

pdfcrowd.Error provides these methods:

Error() returns the complete error message, including available status and reason codes.

Common Status Codes

See all status and reason codes for specific explanations and Limits and Retries for retry behavior.

Read Conversion Information

This information is available after a conversion and describes the client's last conversion.

Limits and Retries

Request rate and concurrency limits depend on your license. Control how quickly your application submits conversions and how many it runs at once. A 429 response concerns request rate; a 430 response concerns requests already in progress. The maximum upload size is 300 MB.

The Go client automatically retries a request once when it receives HTTP 502 or 503. Use SetRetryCount() to change that count, or set it to 0 to disable automatic retries. Account for these retries when adding an application-level retry policy.

Troubleshooting

Inspect a Conversion

This example converts PDF pages to PNG images in a ZIP archive with debug logging enabled and logs the debug log URL when available. Use the input and settings from the conversion you are investigating.

package main

import (
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewPdfToImageClient("demo", "demo")

    client.SetDebugLog(true)
    defer func() {
        if debugLogURL := client.GetDebugLogUrl(); debugLogURL != "" {
            log.Printf("Debug log: %s", debugLogURL)
        }
    }()

    client.SetOutputFormat("png")
    client.SetForceZip(true)
    err := client.ConvertUrlToFile(
        "https://your-server.com/invoice.pdf", "invoice.zip",
    )
    if err != nil {
        log.Print(err)
        return
    }
}

The debug log contains conversion settings and processing details. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.

Common Problems

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