cURL Integration

Learn how to generate PDFs directly from the command line using cURL. Perfect for testing, automation, and shell scripts.

Why use cURL with PixelToPdf?

cURL is the universal tool for API testing and shell scripting. It's perfect for quickly testing PixelToPdf before integrating into your application, automating PDF generation in CI/CD pipelines, or building simple shell scripts for document processing.

Prerequisites

cURL (pre-installed on macOS, Linux, and Windows 10+)
Optional: jq for JSON processing and proper escaping
A PixelToPdf API key from your dashboard (free tier available)

Basic Example

This is the simplest way to convert a webpage to PDF. Set your API key as an environment variable (export PIXELTOPDF_API_KEY=your_key) before running.

Terminal

Bash

curl -X POST https://api.pixeltopdf.com/convert/pdf \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "https://example.com"}' \
  --output output.pdf

How it works: The -X POST specifies the HTTP method. The -H flags set headers. The -d flag sends the JSON body. Finally, --output saves the response directly to a file.

Convert HTML String

You can pass HTML directly in the JSON body. Note that for inline HTML, you'll need to escape quotes or use single-line HTML.

Terminal

Bash

curl -X POST https://api.pixeltopdf.com/convert/pdf \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "<!DOCTYPE html><html><head><style>body{font-family:Arial;padding:40px}h1{color:#333}</style></head><body><h1>Hello, PixelToPdf!</h1><p>This PDF was generated from HTML.</p></body></html>",
    "format": "A4",
    "margin": {"top": "20mm", "bottom": "20mm", "left": "20mm", "right": "20mm"}
  }' \
  --output output.pdf

Tip: For complex HTML, it's easier to read from a file using jq for proper JSON escaping (see the next example). The margin option accepts values in mm, cm, in, or px.

Convert HTML File

For multi-line HTML, use jq to properly escape the content. This technique handles newlines, quotes, and special characters automatically.

Terminal

Bash

# Create HTML file
cat > template.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: Arial, sans-serif; padding: 40px; }
    h1 { color: #333; }
  </style>
</head>
<body>
  <h1>Hello, PixelToPdf!</h1>
  <p>This PDF was generated from HTML.</p>
</body>
</html>
EOF

# Convert using jq to properly escape the HTML
curl -X POST https://api.pixeltopdf.com/convert/pdf \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg html "$(cat template.html)" '{source: $html}')" \
  --output output.pdf

How it works: The jq -n creates new JSON output. The --arg flag safely escapes the HTML content. This approach is essential when your HTML contains quotes, newlines, or other special characters.

With All Options

This example shows the full range of options: page format, orientation, margins, headers, and footers with dynamic page numbers.

Terminal

Bash

curl -X POST https://api.pixeltopdf.com/convert/pdf \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://example.com",
    "format": "A4",
    "landscape": true,
    "margin": {
      "top": "10mm",
      "right": "10mm",
      "bottom": "10mm",
      "left": "10mm"
    },
    "header": {
      "source": "<div style=\"text-align:center;font-size:10px\">Page Header</div>",
      "height": "20mm"
    },
    "footer": {
      "source": "<div style=\"text-align:center;font-size:10px\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
      "height": "20mm"
    }
  }' \
  --output output.pdf

How it works: Headers and footers are HTML strings with special classes: pageNumber and totalPages are automatically replaced with the current and total page numbers. The height property reserves space for the header/footer content.

Base64 Output

When encode: true is set, the API returns a JSON object with the PDF as a base64-encoded string. This is useful for embedding PDFs in other systems or passing them through JSON APIs.

Terminal

Bash

# Get PDF as base64 encoded string
curl -X POST https://api.pixeltopdf.com/convert/pdf \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://example.com",
    "encode": true
  }' | jq -r '.data' | base64 -d > output.pdf

How it works: The response is JSON with a data field containing the base64-encoded PDF. We use jq -r '.data' to extract it, then base64 -d to decode it back to binary.

Convert to Images

PixelToPdf also supports converting webpages to images. Simply change the endpoint from /convert/pdf to /convert/png, /convert/jpeg, or /convert/webp.

Terminal

Bash

# Convert to PNG
curl -X POST https://api.pixeltopdf.com/convert/png \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "https://example.com"}' \
  --output screenshot.png

# Convert to JPEG
curl -X POST https://api.pixeltopdf.com/convert/jpeg \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "https://example.com"}' \
  --output screenshot.jpg

# Convert to WebP
curl -X POST https://api.pixeltopdf.com/convert/webp \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "https://example.com"}' \
  --output screenshot.webp

Tip: PNG produces the highest quality output but larger files. JPEG is great for photographs. WebP offers the best compression-to-quality ratio for modern browsers. All image endpoints support the same options as PDF conversion.

Error Handling

This shell script demonstrates proper error handling. It captures both the response body and HTTP status code, then handles each case appropriately.

convert.sh

Bash

# With verbose output and error handling
response=$(curl -s -w "\n%{http_code}" -X POST https://api.pixeltopdf.com/convert/pdf \
  -H "X-API-Key: $PIXELTOPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "https://example.com"}')

http_code=$(echo "$response" | tail -n 1)
body=$(echo "$response" | sed '$d')

case $http_code in
  200)
    echo "$body" > output.pdf
    echo "PDF saved to output.pdf"
    ;;
  401)
    echo "Error: Invalid API key"
    ;;
  402)
    echo "Error: No credits remaining"
    ;;
  429)
    echo "Error: Rate limit exceeded"
    ;;
  *)
    echo "Error: PDF generation failed (HTTP $http_code)"
    echo "$body"
    ;;
esac

Important: The API returns different status codes for different error types: 401 for authentication issues, 402 when you need more credits, and 429 when you've hit the rate limit. The -s flag silences progress output, and -w appends the HTTP code.

Next steps

You've mastered the command line! For more complex integrations, check out our language-specific guides or explore all available options in the API documentation.

API Documentation All Guides