Blame for README.md

---
title: Sisi PDF API
emoji: 🦊
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
app_port: 7860
---

# 🦊 Sisi PDF API

Universal HTML to PDF converter with **perfect** support for:
- ✅ Chinese (Simplified & Traditional): 简体中文、繁體中文
- ✅ Colorful Emoji: 🦊💕✨🎉⭐🌟
- ✅ SVG Graphics: 100% accurate rendering
- ✅ Modern CSS3: Flexbox, Grid, Gradients, Shadows
- ✅ All Unicode symbols: ♈♉♊♋♌♍♎♏♐♑♒♓

## 🚀 Features

- **Powered by Playwright + Chromium**: Industry-leading rendering engine
- **Zero client-side dependencies**: Everything runs on the server
- **Async/concurrent**: Handle multiple requests simultaneously
- **Production-ready**: Used by Sisi Astrology, Astrology Bazi, and more

## 📖 API Endpoints

### `POST /generate-pdf`

Generate PDF from HTML and return as binary file.

**Request Body**:
```json
{
  "html_content": "<html>...</html>",
  "filename": "document.pdf",
  "page_size": "A4",
  "margin_top": "20mm",
  "margin_bottom": "20mm",
  "margin_left": "20mm",
  "margin_right": "20mm",
  "print_background": true,
  "landscape": false,
  "prefer_css_page_size": false,
  "render_timeout_ms": 30000
}
```

For branded multi-page reports, set all API margins to `0`, enable
`prefer_css_page_size`, and define page margins in the HTML `@page` CSS.

## Branded report integration

See [docs/branded-report-pdf-playbook.md](docs/branded-report-pdf-playbook.md)
for the reusable Astrology Bazi workflow: deterministic HTML templates,
Cloudflare server-side proxying, embedded logos, full-bleed covers, pagination,
and visual PDF verification.

**Response**: PDF binary file

### `POST /generate-pdf-base64`

Generate PDF and return as base64 string (useful for JSON APIs).

**Response**:
```json
{
  "success": true,
  "filename": "document.pdf",
  "pdf_base64": "JVBERi0xLjcK...",
  "size_bytes": 123456
}
```

## 🎨 Example Usage

### JavaScript/TypeScript

```typescript
const response = await fetch('https://sisithefox-pdf-api.hf.space/generate-pdf', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    html_content: `
      <!DOCTYPE html>
      <html>
        <head>
          <meta charset="UTF-8">
          <style>
            body { font-family: 'Noto Sans CJK', Arial; }
            h1 { color: purple; }
          </style>
        </head>
        <body>
          <h1>🦊 小鱼的星盘报告</h1>
          <p>简体中文、繁體中文、Emoji 🎉</p>
          <svg>...</svg>
        </body>
      </html>
    `,
    filename: 'natal-chart.pdf'
  })
})

const blob = await response.blob()
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = 'natal-chart.pdf'
a.click()
```

### Python

```python
import requests

response = requests.post(
    'https://sisithefox-pdf-api.hf.space/generate-pdf',
    json={
        'html_content': '<html>...</html>',
        'filename': 'document.pdf'
    }
)

with open('output.pdf', 'wb') as f:
    f.write(response.content)
```

## 🌟 Perfect for

- 📊 Birth Chart Reports (Sisi Astrology)
- 🔮 Bazi Fortune Readings (Astrology Bazi)
- 💝 Healing Reports (SisiTheFox)
- 📄 Invoices, Receipts, Certificates
- 📝 Any document with Chinese/Emoji/SVG

## 🏗️ Deployment

This API is deployed on **Hugging Face Spaces** (free tier):
- URL: `https://sisithefox-pdf-api.hf.space`
- RAM: 16GB (more than enough)
- Storage: 50GB
- Uptime: 99.9% (with UptimeRobot monitoring)

## 💰 Cost

**$0** - Completely free thanks to Hugging Face Spaces!

## 🔒 Security

- CORS enabled for all origins (public API)
- No data stored - PDFs generated on-the-fly
- Stateless architecture

## 📊 Performance

- Generation time: 2-5 seconds per PDF
- Concurrent requests: 5-10 simultaneous
- Max PDF size: ~50MB (more than enough for reports)

---

🦊 Made with love by Sisi for Sparksverse ecosystem