🔍 Piclets Discovery Server

Backend service for the Piclets discovery game. Each real-world object has ONE canonical Piclet!

🎮 Complete Piclet Generator

Upload an image and provide your HuggingFace token to generate a complete Piclet. This endpoint handles the entire workflow: captioning, concept generation, image creation, and dataset storage.

Upload Image

HuggingFace Token

Generated Piclet Result

🔌 Public API Endpoints

All endpoints return JSON responses. The frontend only needs these 5 endpoints:

1. generate_piclet (Scanner)

Complete Piclet generation workflow.

Input: image (File), hf_token (string)
Output: Generated Piclet with discovery status

2. get_user_piclets (User Collection)

Get user's discovered Piclets and stats.

Input: hf_token (string)
Output: List of Piclets + user stats (total/unique finds, rarity score)

3. get_object_details (Object Data)

Get complete object info (canonical + all variations).

Input: object_name (string)
Output: Canonical + variations + total scans

4. get_recent_activity (Activity Feed)

Recent discoveries across all users.

Input: limit (int, default 20)
Output: Recent discoveries with timestamps

5. get_leaderboard (Top Users)

Top discoverers by rarity score.

Input: limit (int, default 10)
Output: Ranked users with stats

Note: Internal helper functions (search_piclet, create_canonical, etc.) are used by generate_piclet but not exposed to frontend.