QUICKSTART.md

Quick Start Guide

Get your OCR API running on Hugging Face Spaces in minutes!

🚀 Deploy in 3 Steps

Step 1: Create Space (2 minutes)

1. Go to https://huggingface.co/new-space
2. Name: handyhome-ocr-api
3. SDK: Docker
4. Click "Create Space"

Step 2: Upload Files (3 minutes)

1. Click "Files" tab → "Add file" → "Upload files"
2. Upload all files from huggingface-ocr folder
3. Click "Commit changes to main"

Step 3: Wait for Build (5-10 minutes)

• Go to "App" tab
• Watch build logs
• When done, you'll see: "Running on http://0.0.0.0:7860"

✅ Test Your API

# Check health
curl https://YOUR-USERNAME-handyhome-ocr-api.hf.space/health

# Test extraction
curl -X POST https://YOUR-USERNAME-handyhome-ocr-api.hf.space/api/extract-national-id \
  -H "Content-Type: application/json" \
  -d '{"document_url": "YOUR_IMAGE_URL"}'

📚 Available Endpoints

Philippine IDs

• /api/extract-national-id - National ID
• /api/extract-drivers-license - Driver's License
• /api/extract-prc - PRC ID
• /api/extract-umid - UMID
• /api/extract-sss - SSS ID
• /api/extract-passport - Passport
• /api/extract-postal - Postal ID
• /api/extract-phic - PhilHealth ID

Clearances

• /api/extract-nbi - NBI Clearance
• /api/extract-police-clearance - Police Clearance
• /api/extract-tesda - TESDA Certificate

Utility

• /api/analyze-document - Identify document type
• /health - Health check
• / - Full API documentation

🔧 Integration Example

import requests

# Your Hugging Face Space URL
API_BASE = "https://YOUR-USERNAME-handyhome-ocr-api.hf.space"

def extract_national_id(image_url):
    response = requests.post(
        f"{API_BASE}/api/extract-national-id",
        json={"document_url": image_url},
        timeout=300
    )
    return response.json()

# Use it
result = extract_national_id("https://example.com/id.jpg")
print(result)

💡 Tips

• First request is slow: PaddleOCR loads models on first use (~30 seconds)
• Image quality matters: Use clear, well-lit photos
• Timeout: Set timeout to 5 minutes for first request
• Free tier: Space sleeps after 48 hours of inactivity

🐛 Troubleshooting

Build fails?

• Wait and retry - first build can timeout
• Check build logs for specific errors

503 Error?

• Space is sleeping - just visit the URL to wake it

Slow responses?

• Normal for first request (loading models)
• Subsequent requests are faster (2-5 seconds)

📖 Full Documentation

• See README.md for complete API documentation
• See DEPLOYMENT_GUIDE.md for detailed deployment steps

🎯 Next Steps

1. Deploy your OCR Space
2. Update your main app to use it
3. Test with real documents
4. Monitor usage in Space settings

---

Need help? Check DEPLOYMENT_GUIDE.md for detailed instructions!