Hugging Face's logo

Spaces:
xnikkon
/
prmpt-ar-be
Running

App Files Community
prmpt-ar-be / README.md
Nikkon
Deploy PromptAR backend to HF Spaces
c840ad0
preview code
|
raw
history blame contribute delete
4.25 kB
metadata
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

    {
  "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 

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 

{
  "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)

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:

# 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