{"id":28904817,"url":"https://github.com/nngel/pdf-thumbnail-service","last_synced_at":"2026-05-08T10:31:30.756Z","repository":{"id":297050750,"uuid":"995442951","full_name":"nngel/PDF-thumbnail-service","owner":"nngel","description":"A production-ready FastAPI microservice that functions as a PDF thumbnail generator, converting the first page of PDF files to optimized PNG thumbnails.","archived":false,"fork":false,"pushed_at":"2025-06-05T16:22:54.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T13:02:47.251Z","etag":null,"topics":["fastapi","image","pdf","pymupdf-fitz","python","thumbnail-generator","vercel"],"latest_commit_sha":null,"homepage":"https://lor-service-pdfthumbnail.vercel.app/docs#/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nngel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-03T13:41:33.000Z","updated_at":"2025-06-05T16:22:56.000Z","dependencies_parsed_at":"2025-06-04T01:37:52.478Z","dependency_job_id":null,"html_url":"https://github.com/nngel/PDF-thumbnail-service","commit_stats":null,"previous_names":["nngel/pdf-thumbnail-service"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nngel/PDF-thumbnail-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nngel%2FPDF-thumbnail-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nngel%2FPDF-thumbnail-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nngel%2FPDF-thumbnail-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nngel%2FPDF-thumbnail-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nngel","download_url":"https://codeload.github.com/nngel/PDF-thumbnail-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nngel%2FPDF-thumbnail-service/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261126448,"owners_count":23113312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","image","pdf","pymupdf-fitz","python","thumbnail-generator","vercel"],"created_at":"2025-06-21T13:02:33.845Z","updated_at":"2026-05-08T10:31:30.714Z","avatar_url":"https://github.com/nngel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PDF Thumbnail Service\n\n[![Python](https://img.shields.io/badge/python-3.9%2B-blue?logo=python)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-Swagger-blue?logo=swagger)](https://lor-service-pdfthumbnail.vercel.app/docs)\n[![Vercel](https://img.shields.io/badge/deployed%20on-Vercel-black?logo=vercel)](https://lor-service-pdfhumbnail.vercel.app)\n\nA production-ready FastAPI microservice that functions as a PDF thumbnail generator, converting the first page of PDF files to optimized PNG thumbnails.\n\n🌐 **Live API**: [https://lor-service-pdfhumbnail.vercel.app](https://lor-service-pdfhumbnail.vercel.app) | **API Docs**: [/docs](https://lor-service-pdfthumbnail.vercel.app/docs)\n\n## Features\n- **PDF to Image Conversion**: Converts the first page of any PDF to PNG format\n- **High Quality Output**: 150 DPI rendering for crisp, clear thumbnails\n- **Smart Optimization**: Optional 60% scaling and PNG compression for smaller file sizes\n- **Comprehensive Error Handling**: Validates file type, size, and PDF integrity\n- **CORS Support**: Ready for frontend and cross-origin integration\n- **Serverless Ready**: Optimized for Vercel deployment (Python 3.9 runtime)\n- **No File Storage**: All processing is in-memory; files are cleaned up after processing\n- **Health \u0026 Info Endpoints**: For monitoring and service introspection\n\n## API Reference\n\n#### Convert PDF to PNG\n\n```http\nPOST /pdf\n```\n\n| Parameter   | Type     | Description                                      |\n| :---------- | :------- | :----------------------------------------------- |\n| `file`      | `file`   | **Required**. PDF file to convert                |\n| `optimize`  | `bool`   | Optional. If true, applies scaling/compression   |\n\nConverts the first page of a PDF to a PNG image. Returns the PNG file.\n\n#### Health Check\n\n```http\nGET /health\n```\n\nReturns service health status (to check if the service is online).\n\n#### Service Capabilities\n\n```http\nGET /info\n```\n\nReturns service capabilities and available endpoints.\n\n#### API Documentation\n\n```http\nGET /docs\n```\n\nSwagger/OpenAPI documentation for the API\n\n## Testing the API\n- **Swagger UI**: [https://lor-service-pdfthumbnail.vercel.app/docs](https://lor-service-pdfthumbnail.vercel.app/docs)\n- **Example cURL:**\n  ```bash\n  curl -X POST \\\n    -F \"file=@document.pdf\" \\\n    'https://lor-service-pdfthumbnail.vercel.app/pdf?optimize=true' \\\n    --output thumbnail.png\n  ```\n\n## Local Deployment\n\n1. **Clone the repository:**\n  ```bash\n  git clone https://github.com/nngel/PDF-thumbnail-service.git\n  cd PDF-thumbnail-service\n  ```\n\n2. **Create and activate virtual environment:**\n  ```bash\n  python -m venv venv\n  source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n  ```\n\n3. **Install dependencies:**\n  ```bash\n  pip install -r requirements.txt\n  ```\n4. **Run the development server (change port if needed):**\n  ```bash\n  uvicorn api.main:app --reload --port 8000\n  ```\n\n5. **Test the API locally:**\n  ```bash\n  curl -X POST \\\n    -F \"file=@test.pdf\" \\\n    http://localhost:8000/pdf \\\n    --output thumbnail.png\n  ```\n\n## Tech Stack\n- **FastAPI**: Modern async Python web framework\n- **Uvicorn**: ASGI server for local development\n- **PyMuPDF (fitz)**: Fast PDF rendering and manipulation\n- **Pillow**: Image processing and optimization\n- **Vercel**: Serverless deployment platform\n\n## Error Handling\nThe service includes robust error handling for:\n- Invalid file types (non-PDF uploads)\n- Corrupted or unreadable PDF files\n- Empty PDF files (no pages)\n- Files exceeding the 10MB limit\n- Processing timeouts or memory errors\n- Internal server errors (with logging)\n\n## Security Considerations\n- Strict file type and size validation\n- All processing is performed in-memory (no files are written to disk)\n- No persistent storage: files and images are cleaned up immediately after processing\n- Input sanitization and error handling to prevent abuse\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnngel%2Fpdf-thumbnail-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnngel%2Fpdf-thumbnail-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnngel%2Fpdf-thumbnail-service/lists"}