PDF to Image APIs - Convert PDF to JPG, PNG, TIFF, BMP & GIF

API Endpoints

Select an image format to view its specific endpoint, parameters, and examples:

API Endpoint

$ pip install requests

API Request

All PDF to image endpoints accept the same common parameters with additional format-specific controls for color profiles and quality.

Common Query Parameters

These parameters are supported by all PDF to image endpoints. All parameters must be included as query parameters.

Format-Specific Parameters

PDF to JPG

Endpoint: https://api.apifreaks.com/v1.0/pdf/jpg

Best For: Photographs, small file sizes, general viewing

Webhook Support

API Response

Explore detailed response fields including field names, data types, requirements, and descriptions in the interactive Response Table below. For complete response documentation click here.

HTTP Error Codes

All PDF to Image endpoints return consistent error codes:

Task Processing Error Messages

These errors might appear in the task-status response if the background job fails.

Optimizing Your Image Conversion

Use this quick reference to tune the API parameters for your specific needs.

• Resolution (resolution):

  • 72 - 150 DPI: Best for standard screens and web thumbnails (fastest processing).
  • 300 DPI: Standard for high-res displays, OCR processing, and general printing.
  • 600+ DPI: Required for professional offset printing or architectural blueprints.

• Color Profiles (profile):

  • rgb: The standard for all digital screens (Web, Mobile, Email).
  • rgba: Adds an alpha channel for transparency (Available for PNG and GIF only).
  • cmyk: Essential for commercial printing workflows (Available for TIFF and JPG).
  • bw / gray: Use bw (1-bit) for fax/archiving to get the absolute smallest file size. Use gray (8-bit) for standard black & white documents.

• JPG Quality (quality):

  • JPG Only. Scale from 1 to 100.
  • We recommend 75-85 for a balance of sharp details and small file size. Use 90+ only for photography portfolios where size doesn't matter.

• Image Smoothing (image_smoothing):

  • none: Default. Fastest performance.
  • text: Best for documents. Smooths jagged edges on fonts for better readability.
  • line: Best for blueprints and diagrams.
  • image: Best for PDFs containing photos.
  • all: Applies smoothing to everything. Recommended for high-quality outputs.

Converting PDFs to Images

Follow these examples to convert PDF files to images using different formats and configurations. Choose the format and settings that best match your use case.

Step 1: Convert PDF to Images

1. High-Quality Web & Display Assets (JPG & PNG)

Use these examples to generate crisp images for websites, apps, or emails.

• JPG: Ideal for general viewing. We use quality=85 and resolution=150 for sharp text without bloating the file size.
• PNG: Ideal for design assets. We use profile=rgba to preserve transparency and image_smoothing=text to ensure crisp fonts on any background.

Example 1: Web-Ready JPG (Balanced Quality)

curl -X 'POST' \
  'https://api.apifreaks.com/v1.0/pdf/jpg?resolution=150&quality=85&profile=rgb&output=web_images' \
  -H 'X-apiKey: YOUR_API_KEY' \
  -F 'file=@/path/to/brochure.pdf'

# Standard Response
{
    "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d",
    "inputIds": [
        "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f"
    ]
}

Example 2: Transparent PNG (Selected pages only)

curl -X 'POST' \
  'https://api.apifreaks.com/v1.0/pdf/png?pages=1,5-8&profile=rgba&image_smoothing=text&output=transparent_assets' \
  -H 'X-apiKey: YOUR_API_KEY' \
  -F 'file=@/path/to/design_draft.pdf'

# Standard Response
{
    "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d",
    "inputIds": [
        "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f"
    ]
}

2. Professional Print & Archival Scans (TIFF & BMP)

Use these configurations for enterprise workflows, physical printing, or fax archives.

• TIFF (Print Ready): Converts the file using the cmyk color profile and maximum 600 DPI resolution, required for offset printing.
• BMP (Archival): Simulates a scanned document by converting to 1-bit Black & White (bw). This creates extremely small files perfect for faxing or long-term database storage.

Example 1: Print-Ready TIFF (CMYK, 600 DPI)

curl -X 'POST' \
  'https://api.apifreaks.com/v1.0/pdf/tif?resolution=600&profile=cmyk&image_smoothing=all&output=print_master' \
  -H 'X-apiKey: YOUR_API_KEY' \
  -F 'file=@/path/to/marketing.pdf'

# Standard Response
{
    "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d",
    "inputIds": [
        "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f"
    ]
}

Example 2: B&W Document Scan (Smallest size for Archiving)

curl -X 'POST' \
  'https://api.apifreaks.com/v1.0/pdf/bmp?resolution=300&profile=bw&image_smoothing=text&output=archive_scan&destroy=true' \
  -H 'X-apiKey: YOUR_API_KEY' \
  -F 'file=@/path/to/invoice.pdf'

# Response with destroy=true (No File IDs as they are deleted right away)
{
    "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d"
}

3. Thumbnails & Low-Bandwidth Previews (GIF)

Use this configuration to generate lightweight thumbnails or simple previews that load instantly on slower connections.

• GIF: Ideal for simple graphics or document previews. We use resolution=72 (standard screen DPI) and profile=8-bit (256 colors) to keep the file size extremely small while maintaining readability for large headers and diagrams.

Example: Generate Lightweight Thumbnails (First Page Only)

curl -X 'POST' \
  'https://api.apifreaks.com/v1.0/pdf/gif?pages=1&resolution=72&profile=8-bit&output=thumbnail_preview' \
  -H 'X-apiKey: YOUR_API_KEY' \
  -F 'file=@/path/to/report.pdf'

# Standard Response
{
    "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d",
    "inputIds": [
        "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f"
    ]
}

Step 2: Check Task Status

After submitting a pdf to image conversion task, check its progress using the Task Status API with your taskId. The task goes through these statuses: queued, processing, completed, and failed. Monitor your task to know when the image task has finished and images are ready for download.

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/pdf/task-status?task_id=04a06cd5-158d-4191-a45b-6f58249c599d' \
  -H 'X-apiKey: YOUR_API_KEY'

# Response (completed)
{
    "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d",
    "status": "completed",
    "createdAt": "2026-01-26 13:30:00",
    "zipFileUrl": "https://api.apifreaks.com/v1.0/pdf/resource/download?resource_id=9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f",
    "zipFileId": "9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f",
    "inputIds": [
        "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f"
    ],
    "expiresAt": "2026-01-26 23:59:59"
}

# Response (failed)
{
  "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d",
  "status": "failed",
  "createdAt": "2025-01-26 10:30:00",
  "inputIds": [
    "566dc743-d8fe-4943-8cef-61e5d3d6096c"
  ],
  "error": "Invalid PDF File",
  "message": "The provided file is not a valid PDF file.",
  "expiresAt": "2025-01-27 10:30:00"
}

Step 3: Download Converted Images

Once the task status shows "completed", download your converted images as a zip file using the File Download API. The zip contains one image file per converted page, named sequentially.

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/pdf/download?resource_id=9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f' \
  -H 'X-apiKey: YOUR_API_KEY' \
  -o high_quality_images.zip

Webhook Support

Get automatic notifications when your task completes instead of polling the task status endpoint. Good for event-driven applications and real-time document processing.

Add webhook_url to your request. We'll send a POST request to this URL when the task finishes (either completed or failed).

Example Request:

curl -X 'POST' \
  'https://api.apifreaks.com/v1.0/pdf/jpg?webhook_url=https://yourdomain.com/webhook/pdf-to-jpg&webhook_failure_notification=true&resolution=150&quality=85&profile=rgb&output=web_images' \
  -H 'X-apiKey: YOUR_API_KEY' \
  -F 'file=@/path/to/file.pdf'

# Response
{
    "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d",
    "inputIds": [
        "566dc743-d8fe-4943-8cef-61e5d3d6096c"
    ]
}

Webhook Delivery

Webhook delivery will be attempted up to 3 times. If all retries fail and webhook_failure_notification is enabled, we'll send an email notification to the requesting user or their organization admin.

Custom Authorization Header

Use X-Webhook-Authorization to add a custom header to webhook requests for endpoint security.

Format: Key:Value

Example: If you send Authorization:Bearer token123, the webhook request will include: Authorization: Bearer token123

Example with custom authorization:

curl -X 'POST' \
  'https://api.apifreaks.com/v1.0/pdf/jpg?webhook_url=https://yourdomain.com/webhook/pdf-to-image&webhook_failure_notification=true' \
  -H 'X-apiKey: YOUR_API_KEY' \
  -H 'X-Webhook-Authorization: Authorization:Bearer token123' \
  -F 'file=@/path/to/document.pdf'

Webhook Request Format

When your task completes, we send a POST request to your webhook_url with these headers:

Webhook Response

The webhook payload contains the same response structure as the Task Status API endpoint when checked for the task ID. For a comprehensive view of the webhook response structure and detailed field descriptions, explore the interactive Response Table.

Verifying Webhook Authenticity

Use the X-Signature header to verify webhook requests actually came from API Freaks and weren't tampered with.

How the signature works:

1. We compute an HMAC-SHA256 hash of the request body using your API key as the secret
2. We Base64-encode the result
3. We send this as the X-Signature header value

To verify the webhook:

1. Take the raw payload body (JSON string exactly as received without parsing it)
2. Compute HMAC-SHA256 of the payload using your API key as the secret
3. Base64-encode the result of the hash
4. Compare with the X-Signature header value

Important: Don't transform or process the raw request body before verification. Adding whitespace or other formatting creates a different signature and verification will fail.