Convert one or more images to a PDF document. Each image becomes a separate page in the output PDF. Supports common image formats including PNG, JPEG, GIF, and BMP.

Endpoint

POST /imageToPdf

Authentication

Requires a valid API key or OAuth token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Request Body

Content-Type: application/json or multipart/form-data

JSON Input

Multipart Form Data

Field Details

images_base64 (required for JSON)

An array of base64-encoded image strings. Each image becomes a separate page in the PDF. Images are processed in order, so the first image in the array becomes page 1, and so on.

Supported image formats:

• PNG (including transparent images)
• JPEG / JPG
• GIF (first frame only for animated GIFs)
• BMP
• TIFF

files (required for multipart)

Multiple image file uploads. Each file is processed as a separate page in the resulting PDF.

filename (optional)

The filename for the downloaded PDF. If not provided, defaults to document.pdf. The .pdf extension is automatically appended if not present.

Storage Options

Control how the generated PDF is stored and returned.

Storage Modes:

• memory: Return PDF bytes directly in response (no persistence). This is the default for REST API calls.
• default: Store in pdf-mcp S3 bucket, return JSON with document metadata and signed URL.
• byob: Store in your own S3 bucket (requires BYOB configuration).

Example Request

Single Image (JSON)

curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images_base64": ["iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="],
    "filename": "single-image.pdf"
  }' \
  --output single-image.pdf

Multiple Images (JSON)

curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images_base64": [
      "BASE64_ENCODED_IMAGE_1",
      "BASE64_ENCODED_IMAGE_2",
      "BASE64_ENCODED_IMAGE_3"
    ],
    "filename": "photo-album.pdf"
  }' \
  --output photo-album.pdf

Single File Upload

curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@/path/to/image.png" \
  -F "filename=uploaded-image.pdf" \
  --output uploaded-image.pdf

Multiple File Uploads

curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@/path/to/page1.jpg" \
  -F "files=@/path/to/page2.jpg" \
  -F "files=@/path/to/page3.jpg" \
  -F "filename=multi-page-document.pdf" \
  --output multi-page-document.pdf

With Storage (Persistent PDF)

curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images_base64": ["BASE64_ENCODED_IMAGE_1", "BASE64_ENCODED_IMAGE_2"],
    "storage": {
      "mode": "default",
      "filename": "photo-album.pdf",
      "expires_in": 86400,
      "retention_days": 30
    }
  }'

Response

Success (memory mode)

When storage.mode is memory or not provided, returns the PDF as a binary file download.

Headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"

Success (with storage)

When storage.mode is default or byob, returns JSON with document metadata and a signed download URL:

{
  "success": true,
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://s3.eu-central-1.amazonaws.com/...",
  "filename": "photo-album.pdf",
  "file_size_bytes": 2456789,
  "page_count": 5,
  "storage_mode": "default",
  "expires_at": "2024-02-15T10:30:00Z",
  "signed_url_expires_at": "2024-01-15T12:00:00Z"
}

Error

{
  "error": "Failed to convert images to PDF",
  "message": "Error description"
}

Status Codes:

Image Processing

RGBA to RGB Conversion

Images with transparency (RGBA mode) are automatically converted to RGB before being added to the PDF. This ensures compatibility with the PDF format, which does not support transparency in the same way as PNG.

PNG with transparency -> RGB (white background assumed)

If you need to preserve specific background colors, consider adding a background layer to your images before conversion.

Image Ordering

Images are added to the PDF in the order they are provided:

• JSON: Order of elements in the images_base64 array
• Multipart: Order of files fields in the request

Page Sizing

Each image is rendered at its original dimensions. The PDF page size adapts to fit each image, so pages may have different sizes if images have different dimensions.

Use Cases

Photo Album

Create a PDF photo album from multiple images:

curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@photo1.jpg" \
  -F "files=@photo2.jpg" \
  -F "files=@photo3.jpg" \
  -F "filename=vacation-photos.pdf" \
  --output vacation-photos.pdf

Document Scanning

Convert scanned document images to a single PDF:

curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@scan-page1.png" \
  -F "files=@scan-page2.png" \
  -F "filename=scanned-document.pdf" \
  --output scanned-document.pdf

Screenshot Archive

Archive multiple screenshots as a PDF:

curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images_base64": ["SCREENSHOT_1_BASE64", "SCREENSHOT_2_BASE64"],
    "filename": "screenshots.pdf"
  }' \
  --output screenshots.pdf

Example: Python Integration

import requests
import base64

API_KEY = "YOUR_API_KEY"
API_URL = "https://api.pdf-mcp.io/imageToPdf"

# Read and encode image to base64
with open("image.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    API_URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "images_base64": [image_base64],
        "filename": "python-output.pdf"
    }
)

if response.status_code == 200:
    with open("output.pdf", "wb") as f:
        f.write(response.content)
    print("PDF saved successfully!")
else:
    print(f"Error: {response.status_code}")

Using File Upload (Multipart Form)

import requests

API_KEY = "YOUR_API_KEY"
API_URL = "https://api.pdf-mcp.io/imageToPdf"

# Upload multiple images directly
with open("page1.jpg", "rb") as f1, open("page2.jpg", "rb") as f2:
    response = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        files=[
            ("files", ("page1.jpg", f1, "image/jpeg")),
            ("files", ("page2.jpg", f2, "image/jpeg"))
        ],
        data={"filename": "multi-page.pdf"}
    )

if response.status_code == 200:
    with open("output.pdf", "wb") as f:
        f.write(response.content)
    print("PDF saved successfully!")
else:
    print(f"Error: {response.status_code}")

Example: Node.js Integration

const fs = require('fs');

const API_KEY = 'YOUR_API_KEY';
const API_URL = 'https://api.pdf-mcp.io/imageToPdf';

async function generatePdf() {
  // Read and encode image to base64
  const imageBase64 = fs.readFileSync('image.png').toString('base64');

  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      images_base64: [imageBase64],
      filename: 'nodejs-output.pdf'
    })
  });

  if (response.ok) {
    const buffer = await response.arrayBuffer();
    fs.writeFileSync('output.pdf', Buffer.from(buffer));
    console.log('PDF saved successfully!');
  } else {
    console.error('Error:', response.status);
  }
}

generatePdf();

Using File Upload (FormData)

const fs = require('fs');
const FormData = require('form-data');

const API_KEY = 'YOUR_API_KEY';
const API_URL = 'https://api.pdf-mcp.io/imageToPdf';

async function generatePdf() {
  const form = new FormData();
  form.append('files', fs.createReadStream('page1.jpg'));
  form.append('files', fs.createReadStream('page2.jpg'));
  form.append('filename', 'multi-page.pdf');

  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      ...form.getHeaders()
    },
    body: form
  });

  if (response.ok) {
    const buffer = await response.arrayBuffer();
    fs.writeFileSync('output.pdf', Buffer.from(buffer));
    console.log('PDF saved successfully!');
  } else {
    console.error('Error:', response.status);
  }
}

generatePdf();

Tips and Best Practices

Image Preparation

• Consistent sizing: For a uniform look, resize images to the same dimensions before conversion
• Orientation: Rotate images to the correct orientation before uploading
• Compression: Pre-compress large images to reduce API payload size and processing time

Base64 Encoding

When using the JSON input method, encode your images to base64:

Python:

import base64

with open("image.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

Node.js:

const fs = require('fs');
const imageBase64 = fs.readFileSync('image.png').toString('base64');

Bash:

base64 -i image.png

File Size Limits

• Keep individual images under 10MB for optimal performance
• For large batches, consider splitting into multiple requests
• Use JPEG format for photos (smaller file size)
• Use PNG for screenshots or images with text (better quality)

Related Endpoints

• HTML to PDF - Convert HTML with full styling control
• Text to PDF - Convert plain text to PDF
• PDF to Image - Convert PDF pages to images
• Merge PDFs - Combine multiple PDFs

Credit Usage

Approximately 1 credit per page generated.