Spaces:
Running
Running
| title: PromptAR Backend API | |
| emoji: 🎨 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: docker | |
| pinned: false | |
| license: mit | |
| app_port: 7860 | |
| # PromptAR Backend API | |
| FastAPI backend for generating 3D models from text prompts using AI, optimized for AR applications. | |
| ## Features | |
| - 🎨 **Text-to-3D Generation**: Generate 3D models from text prompts using TRELLIS and Shap-E | |
| - 🚀 **Two Generation Modes**: | |
| - **Advanced Mode** (TRELLIS): High-quality textured models | |
| - **Basic Mode** (Shap-E): Fast generation with basic geometry | |
| - 📦 **GLB Format**: Direct export to GLB format optimized for AR | |
| - 🔧 **AR-Optimized**: Automatic brightness normalization for better AR visibility | |
| - 📊 **Request Logging**: Built-in database for tracking API requests | |
| - 🌐 **CORS Enabled**: Ready for cross-origin requests from mobile and web apps | |
| ## API Endpoints | |
| ### 🏠 Root Endpoints | |
| - **GET `/`** - API information and status | |
| - **GET `/health`** - Health check endpoint | |
| ### 🎨 Model Generation | |
| - **POST `/api/models/generate`** - Generate a 3D model from text | |
| ```json | |
| { | |
| "prompt": "wooden chair", | |
| "mode": "advanced" | |
| } | |
| ``` | |
| - **GET `/api/models/download/{model_id}`** - Download generated model | |
| ## Usage | |
| ### API Documentation | |
| Once deployed, visit: | |
| - Interactive docs: `https://your-space-url.hf.space/docs` | |
| - Alternative docs: `https://your-space-url.hf.space/redoc` | |
| ### Example Request | |
| ```bash | |
| curl -X POST "https://your-space-url.hf.space/api/models/generate" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"prompt": "a red sports car", "mode": "advanced"}' | |
| ``` | |
| ### Response | |
| ```json | |
| { | |
| "status": "success", | |
| "message": "3D model generated successfully using advanced mode", | |
| "model_id": "abc123-456def-789ghi", | |
| "download_url": "/api/models/download/abc123-456def-789ghi" | |
| } | |
| ``` | |
| ## Configuration | |
| The backend uses environment variables for configuration. In Hugging Face Spaces, set these in the **Settings > Repository Secrets**: | |
| ### Required | |
| - `HF_TOKEN` - Your Hugging Face API token (get it from [Settings](https://huggingface.co/settings/tokens)) | |
| ### Optional | |
| - `ALLOWED_ORIGINS` - CORS allowed origins (default: "*") | |
| - `MODEL_STORAGE_PATH` - Path for storing models (default: "./models") | |
| ## Architecture | |
| The backend is built with: | |
| - **FastAPI**: Modern Python web framework | |
| - **Gradio Client**: Integration with HF Spaces (TRELLIS, Shap-E) | |
| - **Pydantic**: Data validation | |
| - **SQLite**: Request logging database | |
| - **pygltflib**: 3D model processing | |
| ### Project Structure | |
| ``` | |
| backend/ | |
| ├── app/ # Application factory | |
| │ └── app.py # FastAPI app creation | |
| ├── routers/ # API route handlers | |
| │ ├── root.py # Root endpoints | |
| │ └── models.py # Model generation endpoints | |
| ├── services/ # Business logic | |
| │ ├── huggingface_service.py # AI model integration | |
| │ ├── storage_service.py # Model storage | |
| │ ├── ar_material_service.py # AR optimization | |
| │ └── database_service.py # Request logging | |
| ├── schemas/ # Request/response models | |
| ├── middleware/ # Custom middleware | |
| ├── utils/ # Utilities | |
| ├── config.py # Configuration | |
| └── main.py # Entry point | |
| ``` | |
| ## 3D Model Generation | |
| ### Advanced Mode (TRELLIS) | |
| - High-quality textured 3D models | |
| - ~10-30 seconds generation time | |
| - Uses Microsoft's TRELLIS model | |
| - Optimized for AR applications | |
| ### Basic Mode (Shap-E) | |
| - Fast generation | |
| - ~5-10 seconds generation time | |
| - Uses OpenAI's Shap-E model | |
| - Basic geometry without textures | |
| ## Development | |
| To run locally: | |
| ```bash | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Set environment variables | |
| export HF_TOKEN=your_token_here | |
| # Run the server | |
| python main.py | |
| ``` | |
| Visit `http://localhost:8000/docs` for API documentation. | |
| ## License | |
| MIT License - See LICENSE file for details | |
| ## Links | |
| - 🏠 [Project Repository](https://github.com/yourusername/prompt_ar) | |
| - 📱 [Flutter Frontend](https://github.com/yourusername/prompt_ar/tree/main/frontend_prompt_ar) | |
| - 📖 [Full Documentation](https://github.com/yourusername/prompt_ar/blob/main/README.md) | |