--- title: HTML to PDF Converter emoji: 📄 colorFrom: purple colorTo: blue sdk: docker app_port: 7860 health_check: path: /health --- # HTML to PDF Converter API 📄 Convert HTML files to PDF with automatic image embedding and page break management. Perfect for generating reports, presentations, and documents from HTML. ## 🚀 Quick Start ### Basic Conversion (HTML only) ```bash curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \ -F "html_file=@your_file.html" \ -o output.pdf ``` ### With Images ```bash curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \ -F "html_file=@report.html" \ -F "images=@image1.png" \ -F "images=@image2.jpg" \ -F "images=@logo.svg" \ -o output.pdf ``` ### Custom Aspect Ratio ```bash curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \ -F "html_file=@presentation.html" \ -F "aspect_ratio=16:9" \ -F "auto_detect=false" \ -o slides.pdf ``` ## 📋 API Endpoints ### `POST /convert` Convert HTML file to PDF with optional images. **Parameters:** - `html_file` (required): HTML file to convert - `images` (optional): Image files referenced in HTML (can upload multiple) - `aspect_ratio` (optional): `16:9`, `1:1`, or `9:16` - `auto_detect` (optional): Auto-detect aspect ratio from HTML (default: `true`) **Response:** - PDF file (application/pdf) - Headers include metadata: aspect ratio, image count, PDF size ### `POST /convert-string` Convert HTML string to PDF (for HTML without external images). **Parameters:** - `html_content` (required): HTML content as string - `aspect_ratio` (optional): `16:9`, `1:1`, or `9:16` - `auto_detect` (optional): Auto-detect aspect ratio (default: `true`) **Example:** ```bash curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert-string \ -F "html_content=

Hello World

" \ -o output.pdf ``` ### `GET /health` Health check endpoint. ```bash curl https://abdallalswaiti-htmlpdfs.hf.space/health ``` ## 🎨 Features ### ✅ Automatic Image Path Normalization The API automatically converts complex image paths to simple filenames: **Before:** ```html ``` **After (automatically):** ```html ``` Just upload your images with the `images` parameter, and they'll work! ### ✅ Aspect Ratio Detection The API automatically detects aspect ratio from: - HTML `` tags - CSS `aspect-ratio` properties - Keywords like "presentation", "slide" Supported ratios: - **16:9** - Landscape (presentations, slides) → A4 Landscape - **9:16** - Portrait (reports, documents) → A4 Portrait - **1:1** - Square (social media posts) → 210mm × 210mm ### ✅ Automatic Page Breaks The API intelligently handles page breaks: - Elements with classes: `.page`, `.slide`, `section.page` - Top-level `
`, `
`, `
` elements - Prevents breaking inside: headings, images, tables, code blocks ### ✅ Color Preservation All colors, backgrounds, and gradients are preserved in the PDF with `print-color-adjust: exact`. ## 💡 Usage Examples ### Example 1: Simple Report ```bash curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \ -F "html_file=@report.html" \ -o report.pdf ``` ### Example 2: Presentation with Images ```bash curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \ -F "html_file=@slides.html" \ -F "images=@chart1.png" \ -F "images=@chart2.png" \ -F "images=@logo.svg" \ -F "aspect_ratio=16:9" \ -o presentation.pdf ``` ### Example 3: Multiple Images from Directory ```bash curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \ -F "html_file=@document.html" \ $(for img in images/*.{png,jpg}; do echo "-F images=@$img"; done) \ -o document.pdf ``` ### Example 4: Python Script ```python import requests # Prepare files files = { 'html_file': open('report.html', 'rb'), } # Add images images = [ ('images', open('image1.png', 'rb')), ('images', open('image2.jpg', 'rb')), ] # Optional parameters data = { 'aspect_ratio': '9:16', 'auto_detect': 'false' } # Make request response = requests.post( 'https://abdallalswaiti-htmlpdfs.hf.space/convert', files=files, data=data, files=files + images ) # Save PDF if response.status_code == 200: with open('output.pdf', 'wb') as f: f.write(response.content) print("PDF generated successfully!") else: print(f"Error: {response.status_code}") print(response.text) ``` ### Example 5: JavaScript/Node.js ```javascript const FormData = require('form-data'); const fs = require('fs'); const fetch = require('node-fetch'); async function convertToPDF() { const form = new FormData(); // Add HTML file form.append('html_file', fs.createReadStream('report.html')); // Add images form.append('images', fs.createReadStream('image1.png')); form.append('images', fs.createReadStream('image2.jpg')); // Optional parameters form.append('aspect_ratio', '9:16'); const response = await fetch( 'https://abdallalswaiti-htmlpdfs.hf.space/convert', { method: 'POST', body: form } ); if (response.ok) { const buffer = await response.arrayBuffer(); fs.writeFileSync('output.pdf', Buffer.from(buffer)); console.log('PDF generated successfully!'); } else { console.error('Error:', await response.text()); } } convertToPDF(); ``` ## 📝 HTML Best Practices ### For Multi-Page Documents Use page classes to control page breaks: ```html

Page 1

Content here...

Page 2

More content...

``` ### For Presentations (16:9) ```html

Slide 1

Chart

Slide 2

Graph
``` ### For Reports (9:16) ```html

Annual Report 2024

Logo

Report content...

``` ## 🎯 Image Handling ### Supported Formats - PNG, JPG/JPEG - GIF, SVG - WebP, BMP ### Image Path Examples Your HTML can have **any** of these formats: ```html
``` Just upload the images: ```bash curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \ -F "html_file=@index.html" \ -F "images=@logo.png" \ -F "images=@bg.jpg" \ -o output.pdf ``` The API automatically: 1. Extracts filenames from paths 2. Normalizes all references to simple filenames 3. Saves images to the same directory as HTML 4. Generates PDF with all images embedded ## 🔧 Troubleshooting ### Images Not Showing - Ensure image filenames match exactly (case-sensitive) - Upload ALL images referenced in your HTML - Check that image paths are normalized (the API does this automatically) ### Wrong Aspect Ratio - Set `auto_detect=false` and specify `aspect_ratio` manually - Check HTML for viewport meta tags that might override ### Page Breaks in Wrong Places - Add `class="no-page-break"` to elements that should stay together - Use `class="page-break"` to force breaks at specific points ### PDF Too Large - Optimize images before uploading (compress, resize) - Use appropriate image formats (WebP for photos, PNG for graphics) ## 📊 Response Headers The API includes useful metadata in response headers: - `X-Aspect-Ratio`: Detected or specified aspect ratio - `X-Path-Replacements`: Number of image paths normalized - `X-PDF-Size`: Size of generated PDF in bytes **Example:** ```bash curl -I -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \ -F "html_file=@test.html" # Response headers: # X-Aspect-Ratio: 9:16 # X-Path-Replacements: 3 # X-PDF-Size: 245678 ``` ## 🛠️ Technical Details - **Engine**: Puppeteer (Chromium-based) - **Backend**: FastAPI (Python) - **Max Timeout**: 60 seconds per conversion - **Page Sizes**: - 16:9 → A4 Landscape (297mm × 210mm) - 9:16 → A4 Portrait (210mm × 297mm) - 1:1 → Square (210mm × 210mm) ## 📄 License This API is provided as-is for public use on Hugging Face Spaces. ## 🤝 Support For issues or questions, please visit the [Space discussion page](https://huggingface.co/spaces/abdallalswaiti/htmlpdfs/discussions). --- **Made with ❤️ using FastAPI and Puppeteer**