Deploy PromptAR backend to HF Spaces

.dockerignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Documentation and scripts
+*.md
+!README.md
+*.sh
+
+# Local development files
+.env
+*.db
+
+# Model files (will be generated on the fly)
+models/*.glb
+
+# Temporary files
+temp/
+tmp/
+
+# Logs
+*.log
+
+# Testing
+test/
+tests/
+*.pytest_cache/

Dockerfile

@@ -0,0 +1,34 @@
+# Use Python 3.11 slim image for smaller size
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements file
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create models directory and data directory for persistent storage
+RUN mkdir -p /app/models /data
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV HOST=0.0.0.0
+ENV PORT=7860
+ENV MODEL_STORAGE_PATH=/app/models
+
+# Expose port 7860 (HF Spaces default)
+EXPOSE 7860
+
+# Run the application
+CMD ["python", "main.py"]

README.md

@@ -1,12 +1,154 @@
 ---
-title: Prmpt Ar Be
-emoji: 📊
-colorFrom: pink
-colorTo: blue
+title: PromptAR Backend API
+emoji: 🎨
+colorFrom: blue
+colorTo: purple
 sdk: docker
 pinned: false
-license: creativeml-openrail-m
-short_description: Back end for Prompt AR application
+license: mit
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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)
+

app/__init__.py

@@ -0,0 +1,2 @@
+"""Application package for FastAPI app configuration."""
+

app/app.py

@@ -0,0 +1,115 @@
+"""Application factory for creating and configuring the FastAPI application."""
+
+import logging
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from config import (
+    API_TITLE,
+    API_DESCRIPTION,
+    API_VERSION,
+    ALLOWED_ORIGINS,
+    DB_PATH,
+)
+from routers import models_router, root_router
+from services.database_service import DatabaseService
+from middleware.request_logging import RequestLoggingMiddleware
+
+logger = logging.getLogger(__name__)
+
+# Global service instances
+hf_service = None
+database_service = None
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Returns:
+        Configured FastAPI application instance
+    """
+    # Create FastAPI app
+    app = FastAPI(
+        title=API_TITLE,
+        description=API_DESCRIPTION,
+        version=API_VERSION,
+    )
+
+    # Initialize database service
+    _initialize_database_service()
+
+    # Add middleware
+    _setup_middleware(app)
+
+    # Include routers
+    _setup_routers(app)
+
+    return app
+
+
+def _initialize_database_service():
+    """Initialize the database service for request logging."""
+    global database_service
+
+    try:
+        logger.info(f"Initializing database service for request logging (path: {DB_PATH})")
+        database_service = DatabaseService(db_path=DB_PATH)
+        logger.info(f"✓ Database service initialized successfully at {DB_PATH}")
+    except Exception as e:
+        logger.error(f"❌ Failed to initialize database service: {e}")
+        database_service = None
+
+
+def _setup_middleware(app: FastAPI):
+    """Configure middleware for the application.
+
+    Args:
+        app: FastAPI application instance
+    """
+    # Add request logging middleware (must be before CORS middleware to capture all requests)
+    if database_service:
+        app.add_middleware(RequestLoggingMiddleware, database_service=database_service)
+        logger.info("✓ Request logging middleware added")
+    else:
+        logger.warning(
+            "⚠️  Request logging middleware not added - database service not initialized"
+        )
+
+    # Configure CORS (needed for Flutter web and mobile apps)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=ALLOWED_ORIGINS,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+def _setup_routers(app: FastAPI):
+    """Register routers with the application.
+
+    Args:
+        app: FastAPI application instance
+    """
+    app.include_router(root_router)
+    app.include_router(models_router)
+
+
+def get_hf_service():
+    """Get the global HuggingFaceService instance.
+
+    Returns:
+        HuggingFaceService instance or None if not initialized
+    """
+    return hf_service
+
+
+def set_hf_service(service):
+    """Set the global HuggingFaceService instance.
+
+    Args:
+        service: HuggingFaceService instance
+    """
+    global hf_service
+    hf_service = service
+

config.py

@@ -0,0 +1,73 @@
+"""Application configuration.
+
+Loads configuration from .env file.
+Environment variables take precedence over .env file values.
+"""
+
+import os
+from pathlib import Path
+from typing import List
+
+from dotenv import dotenv_values
+
+# Load environment variables from .env file
+# Look for .env file in the backend directory
+env_path = Path(__file__).parent / ".env"
+if env_path.exists():
+    env_vars = dotenv_values(dotenv_path=env_path)
+    print(f"Loaded configuration from {env_path}")
+else:
+    # Try loading from current directory as fallback
+    env_vars = dotenv_values()
+    print("Loaded configuration from .env file in current directory")
+
+
+# Helper function to get config value (env vars override .env file)
+def get_config(key: str, default: str = "") -> str:
+    """Get configuration value from environment variable or .env file.
+
+    Environment variables take precedence over .env file values.
+    """
+    return os.getenv(key, env_vars.get(key, default))
+
+
+# API Configuration
+API_TITLE = "PromptAR Backend API"
+API_VERSION = "1.0.0"
+API_DESCRIPTION = "API for generating 3D models from text prompts and serving them for AR visualization"
+
+# Server Configuration
+HOST = get_config("HOST", "0.0.0.0")
+PORT = int(get_config("PORT", "8000"))
+
+# CORS Configuration
+allowed_origins_value = get_config("ALLOWED_ORIGINS", "*")
+ALLOWED_ORIGINS: List[str] = (
+    allowed_origins_value.split(",") if allowed_origins_value != "*" else ["*"]
+)
+
+# Model Configuration
+MODEL_STORAGE_PATH = get_config("MODEL_STORAGE_PATH", "./models")
+
+# Database Configuration
+# Use persistent storage on Hugging Face Spaces (/data), otherwise use local path
+# /data is persistent storage on Hugging Face Spaces that survives restarts
+_default_db_path = (
+    "/data/api_requests.db" if Path("/data").exists() else "./api_requests.db"
+)
+DB_PATH = get_config("DB_PATH", _default_db_path)
+
+# Hugging Face Configuration (Required)
+HF_TOKEN = get_config("HF_TOKEN", "")
+if not HF_TOKEN:
+    import warnings
+
+    warnings.warn(
+        "HF_TOKEN is not configured. Set HF_TOKEN in .env file or environment variable to enable model generation.",
+        UserWarning,
+    )
+
+# 3D Model Generation Configuration
+# Using TRELLIS: https://huggingface.co/spaces/dkatz2391/TRELLIS_TextTo3D_Try2
+# Generates textured GLB files directly from text prompts
+# Uses texture_size parameter to ensure textures are embedded in GLB files

main.py

@@ -0,0 +1,48 @@
+"""Main application entry point for PromptAR Backend API."""
+
+import logging
+
+from utils.logging_config import setup_colored_logging
+from app.app import create_app, set_hf_service
+from config import HOST, PORT, HF_TOKEN
+
+# Setup colored logging before creating app
+setup_colored_logging()
+logger = logging.getLogger(__name__)
+
+# Create FastAPI application
+app = create_app()
+
+
+async def startup_event():
+    """Handle application startup events."""
+    # Initialize HuggingFaceService (works with or without HF_TOKEN)
+    try:
+        from services.huggingface_service import HuggingFaceService
+
+        logger.info("Initializing HuggingFaceService")
+        hf_service = HuggingFaceService()
+        set_hf_service(hf_service)
+        logger.info("✓ HuggingFaceService initialized successfully")
+    except Exception as e:
+        logger.error(f"❌ Failed to initialize HuggingFaceService: {e}")
+        set_hf_service(None)
+
+    if not HF_TOKEN:
+        logger.warning(
+            "⚠️  HF_TOKEN not configured - Some Spaces may require authentication"
+        )
+
+    logger.info(
+        "API server started. Visit http://localhost:8000/docs for API documentation"
+    )
+
+
+# Register startup event
+app.on_event("startup")(startup_event)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host=HOST, port=PORT)

middleware/__init__.py

@@ -0,0 +1,2 @@
+"""Middleware package for request logging."""
+

middleware/request_logging.py

@@ -0,0 +1,80 @@
+"""Middleware for logging all API requests to SQLite database."""
+
+import logging
+from fastapi import Request
+from starlette.middleware.base import BaseHTTPMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """Middleware to log all API requests to SQLite database immediately on receipt."""
+
+    def __init__(self, app, database_service):
+        """Initialize the middleware.
+
+        Args:
+            app: FastAPI application instance
+            database_service: DatabaseService instance for logging requests
+        """
+        super().__init__(app)
+        self.database_service = database_service
+
+    async def dispatch(self, request: Request, call_next):
+        """Log the request immediately when received, then process it.
+
+        Args:
+            request: FastAPI request object
+            call_next: Next middleware/handler in the chain
+
+        Returns:
+            Response object
+        """
+        # Get client IP address
+        client_ip = self._get_client_ip(request)
+
+        # Get user agent
+        user_agent = request.headers.get("user-agent")
+
+        # Log the request immediately when received (before processing)
+        try:
+            self.database_service.log_request(
+                method=request.method,
+                path=request.url.path,
+                client_ip=client_ip,
+                user_agent=user_agent,
+            )
+        except Exception as e:
+            # Don't fail the request if logging fails
+            logger.error(f"Failed to log request: {e}")
+
+        # Process the request
+        response = await call_next(request)
+        return response
+
+    def _get_client_ip(self, request: Request) -> str:
+        """Extract client IP address from request.
+
+        Checks various headers for the real client IP, accounting for proxies.
+
+        Args:
+            request: FastAPI request object
+
+        Returns:
+            Client IP address as string
+        """
+        # Check for forwarded IP headers (common in proxy/load balancer setups)
+        forwarded_for = request.headers.get("x-forwarded-for")
+        if forwarded_for:
+            # X-Forwarded-For can contain multiple IPs, take the first one
+            return forwarded_for.split(",")[0].strip()
+
+        real_ip = request.headers.get("x-real-ip")
+        if real_ip:
+            return real_ip.strip()
+
+        # Fallback to direct client IP
+        if request.client:
+            return request.client.host
+
+        return "unknown"

requirements.txt

@@ -0,0 +1,26 @@
+# Core web framework - using versions compatible with Python 3.12 and Android/ARM
+# FastAPI 0.104.1 works with Pydantic v1 (no Rust compilation needed)
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-multipart==0.0.6
+
+# HTTP clients
+requests==2.31.0
+httpx==0.25.2
+
+# Configuration
+python-dotenv==1.0.0
+
+# Hugging Face integration
+gradio_client==1.13.3
+huggingface_hub>=0.19.3
+
+# Image processing
+Pillow==10.2.0
+
+# 3D model processing
+pygltflib==1.16.0
+
+# Data validation - Pydantic v1 (no Rust compilation required, works on Android)
+pydantic==1.10.13
+

routers/__init__.py

@@ -0,0 +1,4 @@
+from routers.models import router as models_router
+from routers.root import router as root_router
+
+__all__ = ["models_router", "root_router"]

routers/models.py

@@ -0,0 +1,424 @@
+"""Router for model generation and download endpoints."""
+
+import logging
+import asyncio
+import uuid
+import tempfile
+import shutil
+from pathlib import Path
+from fastapi import APIRouter, HTTPException, BackgroundTasks, File, UploadFile
+from fastapi.responses import Response
+
+from schemas.models import PromptRequest, GenerationResponse
+from services.storage_service import StorageService
+from services.ar_material_service import normalize_materials_for_ar
+from config import MODEL_STORAGE_PATH
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/models", tags=["Models"])
+
+# Initialize storage service
+storage_service = StorageService()
+
+
+def sanitize_error_message(error: Exception) -> str:
+    """Sanitize error messages for frontend - hide technical details.
+
+    Returns user-friendly error messages instead of exposing:
+    - GPU quota details
+    - Internal error messages
+    - Technical stack traces
+    """
+    error_str = str(error).lower()
+
+    # GPU quota errors
+    if "gpu quota" in error_str or "exceeded" in error_str:
+        return "The AI service is currently busy. Please try again in a few minutes."
+
+    # Timeout errors
+    if "timeout" in error_str or "timed out" in error_str:
+        return "The request took too long. Please try again with a simpler prompt."
+
+    # Space/service unavailable
+    if "space" in error_str and ("sleeping" in error_str or "unavailable" in error_str):
+        return "The AI service is temporarily unavailable. Please try again later."
+
+    # Queue/busy errors
+    if "queue" in error_str or "busy" in error_str:
+        return "The service is busy. Please try again in a moment."
+
+    # Network errors
+    if "network" in error_str or "connection" in error_str:
+        return "Network error occurred. Please check your connection and try again."
+
+    # Generic fallback for other errors
+    return "Model generation failed. Please try again or use a different prompt."
+
+
+def get_hf_service():
+    """Get HuggingFaceService instance from app."""
+    from app.app import get_hf_service as _get_hf_service
+
+    hf_service = _get_hf_service()
+
+    if not hf_service:
+        raise HTTPException(
+            status_code=503,
+            detail="HuggingFaceService not initialized. Check HF_TOKEN configuration.",
+        )
+    return hf_service
+
+
+def cleanup_model_file(glb_path: Path):
+    """Cleanup function to delete model file after download.
+
+    This runs as a background task after the response is sent to the client.
+
+    Args:
+        glb_path: Path to the GLB file to delete
+    """
+    try:
+        if glb_path.exists():
+            glb_path.unlink()
+            logger.info(f"✓ Deleted GLB file after download: {glb_path}")
+        else:
+            logger.warning(f"GLB file not found for deletion: {glb_path}")
+    except Exception as delete_error:
+        logger.warning(f"Failed to delete GLB file after download: {delete_error}")
+
+
+@router.post("/generate", response_model=GenerationResponse)
+async def generate_model(request: PromptRequest):
+    """Generate a 3D model from a text prompt.
+
+    Mode options:
+    - "basic": Uses Shap-E for 3D model generation
+    - "advanced": Uses TRELLIS for 3D model generation with textures
+
+    Args:
+        request: PromptRequest with prompt and mode ("basic" or "advanced")
+
+    Returns:
+        GenerationResponse with model_id and download_url
+    """
+    hf_service = get_hf_service()
+
+    # Validate mode parameter
+    mode = request.mode.lower() if request.mode else None
+    if not mode or mode not in ["basic", "advanced"]:
+        raise HTTPException(status_code=400, detail=f"Invalid mode: '{request.mode}'.")
+
+    # Create model record
+    model_id = storage_service.create_model_record(request.prompt)
+
+    logger.info(
+        f"Generating 3D model for prompt: '{request.prompt[:50]}...' "
+        f"(ID: {model_id}, Mode: {mode})"
+    )
+
+    try:
+        # Generate 3D model based on mode
+        # Combine logic for Shap-E and TRELLIS generation
+        hf_clients = {
+            "basic": ("shap_e_client", hf_service.text_to_3d_shap_e, "Shap-E"),
+            "advanced": ("trellis_client", hf_service.text_to_3d, "TRELLIS"),
+        }
+
+        client_attr, gen_func, mode_name = hf_clients[mode]
+
+        if not getattr(hf_service, client_attr):
+            raise HTTPException(
+                status_code=503,
+                detail=f"{mode_name} client not initialized. {mode_name} features are not available.",
+            )
+
+        logger.info(f"Using {mode_name} ({mode} mode) for generation...")
+        glb_path = await asyncio.to_thread(gen_func, request.prompt, model_id)
+
+        logger.info(f"3D model generated: {glb_path}")
+
+        # Update storage with model file
+        storage_service.set_model_file(model_id, glb_path, fmt="glb")
+        storage_service.update_model_status(model_id, "completed")
+
+        logger.info(f"✓ 3D model generation completed for {model_id} (mode: {mode})")
+
+        resp = GenerationResponse(
+            status="success",
+            message=f"3D model generated successfully using {mode} mode",
+            model_id=model_id,
+            download_url=f"/api/models/download/{model_id}",
+        )
+        logger.info(f"Generation response: {resp}")
+        return resp
+
+    except HTTPException:
+        # Re-raise HTTP exceptions as-is
+        raise
+    except RuntimeError as e:
+        error_msg = str(e)
+        logger.error(f"Generation failed: {error_msg}")
+        storage_service.update_model_status(model_id, "failed")
+        # Return sanitized error message to frontend
+        user_friendly_msg = sanitize_error_message(e)
+        raise HTTPException(status_code=503, detail=user_friendly_msg)
+    except Exception as e:
+        error_msg = str(e)
+        logger.error(f"Unexpected error: {error_msg}", exc_info=True)
+        storage_service.update_model_status(model_id, "failed")
+        # Return sanitized error message to frontend
+        user_friendly_msg = sanitize_error_message(e)
+        raise HTTPException(status_code=500, detail=user_friendly_msg)
+
+
+@router.get("/download/{model_id}")
+async def download_model(model_id: str, background_tasks: BackgroundTasks):
+    """Download GLB model file with brightness normalization applied on download.
+
+    This endpoint:
+    1. Loads the GLB file
+    2. Applies brightness normalization for AR visibility
+    3. Returns the normalized GLB file as a single binary file
+    4. Deletes the file and clears memory after client downloads
+
+    Benefits:
+    - Single file download (faster, simpler)
+    - Smaller size (no zip overhead)
+    - Brightness normalization applied on-demand (always uses latest settings)
+    - Works directly with AR plugins (NodeType.fileSystemAppFolderGLB)
+    - Automatic cleanup after download (saves storage space)
+    """
+    hf_service = get_hf_service()
+
+    logger.info(f"Preparing GLB file for download (model ID: {model_id})")
+    glb_path = Path(MODEL_STORAGE_PATH) / f"{model_id}.glb"
+
+    # Check if GLB file exists
+    if not glb_path.exists():
+        logger.error(f"GLB file not found: {glb_path}")
+        raise HTTPException(status_code=404, detail="Model file not found")
+
+    try:
+        # Apply brightness normalization to GLB file before serving
+        logger.info("Applying brightness normalization to GLB file...")
+        # normalize_materials_for_ar(glb_path)
+        logger.info("✓ Brightness normalization applied to GLB")
+
+        # Read normalized GLB file content
+        with open(glb_path, "rb") as f:
+            glb_content = f.read()
+
+        logger.info(
+            f"Serving normalized GLB file: {glb_path} ({len(glb_content)} bytes)"
+        )
+
+        # Schedule cleanup task to run after response is sent
+        # background_tasks.add_task(cleanup_model_file, glb_path)
+
+        # Create response
+        response = Response(
+            content=glb_content,
+            media_type="model/gltf-binary",
+            headers={
+                "Content-Type": "model/gltf-binary",
+                "Content-Disposition": f'attachment; filename="{model_id}.glb"',
+                "Access-Control-Allow-Origin": "*",
+                "Access-Control-Allow-Methods": "GET, OPTIONS",
+                "Access-Control-Allow-Headers": "*",
+                "Cache-Control": "public, max-age=3600",
+            },
+        )
+
+        # Clear memory reference (will be garbage collected after response is sent)
+        del glb_content
+
+        return response
+    except Exception as e:
+        logger.error(f"Failed to prepare/serve GLB file: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to prepare/serve GLB file: {str(e)}"
+        )
+
+
+@router.post("/generate-from-image", response_model=GenerationResponse)
+async def generate_model_from_image(image: UploadFile = File(...)):
+    """Generate a 3D model from an uploaded image using Hunyuan3D.
+
+    This endpoint:
+    1. Accepts an image file upload
+    2. Uses Hunyuan3D to convert the image to a 3D GLB model with textures and colors
+    3. Returns a model_id and download_url for the generated model
+
+    Args:
+        image: Uploaded image file (JPEG, PNG, etc.)
+
+    Returns:
+        GenerationResponse with model_id and download_url
+    """
+    hf_service = get_hf_service()
+
+    if not hf_service.hunyuan_client:
+        raise HTTPException(
+            status_code=503,
+            detail="Hunyuan3D-2 client not initialized. Hunyuan3D-2 is required for image-to-3D features.",
+        )
+
+    # Create model record with descriptive prompt
+    model_id = storage_service.create_model_record(f"image_to_3d_{image.filename}")
+
+    logger.info(f"Generating 3D model from image: {image.filename} (ID: {model_id})")
+
+    # Create temporary directory for uploaded image
+    temp_dir = Path(tempfile.gettempdir()) / "prompt_ar_uploads"
+    temp_dir.mkdir(parents=True, exist_ok=True)
+
+    # Save uploaded image to temporary file
+    temp_image_path = temp_dir / f"{model_id}_{image.filename}"
+
+    try:
+        # Save uploaded file
+        with open(temp_image_path, "wb") as buffer:
+            shutil.copyfileobj(image.file, buffer)
+
+        logger.info(f"Saved uploaded image to: {temp_image_path}")
+
+        # Generate 3D model from image
+        logger.info("Using Hunyuan3D-2 for image-to-3D generation...")
+        glb_path = await asyncio.to_thread(
+            hf_service.image_to_3d_hunyuan, str(temp_image_path), model_id
+        )
+
+        logger.info(f"3D model generated: {glb_path}")
+
+        # Update storage with model file
+        storage_service.set_model_file(model_id, glb_path, fmt="glb")
+        storage_service.update_model_status(model_id, "completed")
+
+        logger.info(f"✓ 3D model generation from image completed for {model_id}")
+
+        resp = GenerationResponse(
+            status="success",
+            message="3D model generated successfully from image using Hunyuan3D-2",
+            model_id=model_id,
+            download_url=f"/api/models/download/{model_id}",
+        )
+        logger.info(f"Generation response: {resp}")
+        return resp
+
+    except HTTPException:
+        # Re-raise HTTP exceptions as-is
+        raise
+    except RuntimeError as e:
+        error_msg = str(e)
+        logger.error(f"Generation from image failed: {error_msg}")
+        storage_service.update_model_status(model_id, "failed")
+        # Return sanitized error message to frontend
+        user_friendly_msg = sanitize_error_message(e)
+        raise HTTPException(status_code=503, detail=user_friendly_msg)
+    except Exception as e:
+        error_msg = str(e)
+        logger.error(f"Unexpected error: {error_msg}", exc_info=True)
+        storage_service.update_model_status(model_id, "failed")
+        # Return sanitized error message to frontend
+        user_friendly_msg = sanitize_error_message(e)
+        raise HTTPException(status_code=500, detail=user_friendly_msg)
+    finally:
+        # Clean up temporary image file
+        try:
+            if temp_image_path.exists():
+                temp_image_path.unlink()
+                logger.debug(f"Cleaned up temporary image file: {temp_image_path}")
+        except Exception as cleanup_error:
+            logger.warning(f"Failed to cleanup temporary image file: {cleanup_error}")
+
+
+@router.post("/generate-from-image2", response_model=GenerationResponse)
+async def generate_model_from_image2(image: UploadFile = File(...)):
+    """Generate a 3D model from an uploaded image using TRELLIS.
+
+    This endpoint:
+    1. Accepts an image file upload
+    2. Uses TRELLIS 2 to convert the image to a 3D GLB model with textures and colors
+    3. Returns a model_id and download_url for the generated model
+
+    Args:
+        image: Uploaded image file (JPEG, PNG, etc.)
+
+    Returns:
+        GenerationResponse with model_id and download_url
+    """
+    hf_service = get_hf_service()
+
+    if not hf_service.trellis_client2:
+        raise HTTPException(
+            status_code=503,
+            detail="TRELLIS 2  client not initialized. TRELLIS 2 is required for image-to-3D features.",
+        )
+
+    # Create model record with descriptive prompt
+    model_id = storage_service.create_model_record(f"image_to_3d_{image.filename}")
+
+    logger.info(f"Generating 3D model from image: {image.filename} (ID: {model_id})")
+
+    # Create temporary directory for uploaded image
+    temp_dir = Path(tempfile.gettempdir()) / "prompt_ar_uploads"
+    temp_dir.mkdir(parents=True, exist_ok=True)
+
+    # Save uploaded image to temporary file
+    temp_image_path = temp_dir / f"{model_id}_{image.filename}"
+
+    try:
+        # Save uploaded file
+        with open(temp_image_path, "wb") as buffer:
+            shutil.copyfileobj(image.file, buffer)
+
+        logger.info(f"Saved uploaded image to: {temp_image_path}")
+
+        # Generate 3D model from image
+        logger.info("Using TRELLIS 2 for image-to-3D generation...")
+        glb_path = await asyncio.to_thread(
+            hf_service.image_to_3d_TRELLIS, str(temp_image_path), model_id
+        )
+
+        logger.info(f"3D model generated: {glb_path}")
+
+        # Update storage with model file
+        storage_service.set_model_file(model_id, glb_path, fmt="glb")
+        storage_service.update_model_status(model_id, "completed")
+
+        logger.info(f"✓ 3D model generation from image completed for {model_id}")
+
+        resp = GenerationResponse(
+            status="success",
+            message="3D model generated successfully from image using TRELLIS 2",
+            model_id=model_id,
+            download_url=f"/api/models/download/{model_id}",
+        )
+        logger.info(f"Generation response: {resp}")
+        return resp
+
+    except HTTPException:
+        # Re-raise HTTP exceptions as-is
+        raise
+    except RuntimeError as e:
+        error_msg = str(e)
+        logger.error(f"Generation from image failed: {error_msg}")
+        storage_service.update_model_status(model_id, "failed")
+        # Return sanitized error message to frontend
+        user_friendly_msg = sanitize_error_message(e)
+        raise HTTPException(status_code=503, detail=user_friendly_msg)
+    except Exception as e:
+        error_msg = str(e)
+        logger.error(f"Unexpected error: {error_msg}", exc_info=True)
+        storage_service.update_model_status(model_id, "failed")
+        # Return sanitized error message to frontend
+        user_friendly_msg = sanitize_error_message(e)
+        raise HTTPException(status_code=500, detail=user_friendly_msg)
+    finally:
+        # Clean up temporary image file
+        try:
+            if temp_image_path.exists():
+                temp_image_path.unlink()
+                logger.debug(f"Cleaned up temporary image file: {temp_image_path}")
+        except Exception as cleanup_error:
+            logger.warning(f"Failed to cleanup temporary image file: {cleanup_error}")

routers/root.py

@@ -0,0 +1,26 @@
+"""Root router for API information and health checks."""
+from fastapi import APIRouter
+
+router = APIRouter(tags=["Root"])
+
+
+@router.get("/")
+async def root():
+    """Root endpoint providing API information."""
+    return {
+        "message": "PromptAR Backend API",
+        "version": "1.0.0",
+        "endpoints": {
+            "generate": "POST /api/models/generate",
+            "download": "GET /api/models/download/{model_id}"
+        }
+    }
+
+
+@router.get("/health")
+async def health_check():
+    """Health check endpoint."""
+    return {
+        "status": "healthy",
+        "service": "PromptAR Backend"
+    }

schemas/__init__.py

@@ -0,0 +1,3 @@
+from .models import PromptRequest, GenerationResponse
+
+__all__ = ["PromptRequest", "GenerationResponse"]

schemas/models.py

@@ -0,0 +1,33 @@
+from pydantic import BaseModel
+
+
+class PromptRequest(BaseModel):
+    """Request schema for model generation."""
+    prompt: str
+    mode: str  # "basic" for Shap-E, "advanced" for TRELLIS
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "prompt": "wooden chair",
+                "mode": "basic"
+            }
+        }
+
+
+class GenerationResponse(BaseModel):
+    """Response schema for model generation."""
+    status: str
+    message: str
+    model_id: str
+    download_url: str
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "status": "success",
+                "message": "3D model generated successfully",
+                "model_id": "abc123-456def-789ghi",
+                "download_url": "/api/models/download/abc123-456def-789ghi"
+            }
+        }

services/__init__.py

@@ -0,0 +1,3 @@
+from services.storage_service import StorageService
+
+__all__ = ["StorageService"]

services/ar_material_service.py

@@ -0,0 +1,175 @@
+"""AR Material Processing Service for normalizing 3D model materials for AR visibility."""
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pygltflib import GLTF2
+
+logger = logging.getLogger(__name__)
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+# Material brightness configuration for AR visibility
+# Adjust these values to control model brightness:
+# - Higher emissive = brighter glow (0.0-1.0, typical: 0.2-0.5)
+# - Higher baseColor boost = brighter colors (1.0 = no change, 1.5 = 50% brighter)
+# - Lower metallic threshold = more materials become non-metallic (0.0-1.0)
+# - Higher roughness min = more matte surface (0.0-1.0, typical: 0.7-1.0)
+BRIGHTNESS_CONFIG = {
+    "metallic_threshold": 0.1,  # Any metallicFactor > this becomes 0.0
+    "metallic_target": 0.0,  # Target metallicFactor for bright materials
+    "roughness_min": 0.9,  # Minimum roughnessFactor (higher = more matte)
+    "base_color_boost": 1.5,  # Multiplier for baseColorFactor (1.5 = 50% brighter)
+    "emissive_base": 0.3,  # Base emissive glow (0.0-1.0)
+    "emissive_max": 0.5,  # Maximum emissive glow (0.0-1.0)
+}
+
+# ============================================================================
+# Core Material Normalization Functions
+# ============================================================================
+
+
+def normalize_gltf_materials(gltf: "GLTF2") -> None:
+    """Normalize materials in a GLTF object (in-memory) for AR visibility.
+
+    This function works on a GLTF object that's already loaded in memory.
+    It adjusts material properties to ensure models appear bright in AR.
+
+    Args:
+        gltf: GLTF2 object to normalize
+    """
+    # Normalize materials to ensure they render correctly in AR
+    # High metallicFactor can cause models to appear dark/black
+    # BoxTextured works because it has metallicFactor=0.0 (non-metallic)
+    if gltf.materials:
+        for i, material in enumerate(gltf.materials):
+            if (
+                hasattr(material, "pbrMetallicRoughness")
+                and material.pbrMetallicRoughness
+            ):
+                pbr = material.pbrMetallicRoughness
+
+                # If metallicFactor is too high, reduce it to target value
+                # High metallic = mirrors environment, needs strong lighting
+                # Non-metallic (0.0) = uses base color/texture, works better in AR
+                if hasattr(pbr, "metallicFactor") and pbr.metallicFactor is not None:
+                    original_metallic = pbr.metallicFactor
+                    if original_metallic > BRIGHTNESS_CONFIG["metallic_threshold"]:
+                        pbr.metallicFactor = BRIGHTNESS_CONFIG["metallic_target"]
+                        logger.info(
+                            f"Normalized material {i}: metallicFactor {original_metallic} -> {pbr.metallicFactor} "
+                            f"(threshold: {BRIGHTNESS_CONFIG['metallic_threshold']}, target: {BRIGHTNESS_CONFIG['metallic_target']})"
+                        )
+
+                # Ensure roughnessFactor is reasonable (0.0-1.0)
+                # Lower roughness = more shiny, but can also appear darker
+                # Higher roughness = more matte, better visibility
+                if hasattr(pbr, "roughnessFactor") and pbr.roughnessFactor is not None:
+                    if pbr.roughnessFactor < BRIGHTNESS_CONFIG["roughness_min"]:
+                        # Increase roughness to minimum for maximum visibility
+                        pbr.roughnessFactor = max(
+                            pbr.roughnessFactor,
+                            BRIGHTNESS_CONFIG["roughness_min"],
+                        )
+                        logger.info(
+                            f"Normalized material {i}: roughnessFactor -> {pbr.roughnessFactor} "
+                            f"(min: {BRIGHTNESS_CONFIG['roughness_min']})"
+                        )
+
+                # Ensure baseColorFactor is set (white if missing)
+                if not hasattr(pbr, "baseColorFactor") or pbr.baseColorFactor is None:
+                    pbr.baseColorFactor = [1.0, 1.0, 1.0, 1.0]
+                    logger.info(f"Added baseColorFactor to material {i} (white)")
+                else:
+                    # Boost baseColorFactor to increase brightness
+                    base_color = pbr.baseColorFactor
+                    if isinstance(base_color, list) and len(base_color) >= 3:
+                        # Apply brightness boost multiplier
+                        boost = BRIGHTNESS_CONFIG["base_color_boost"]
+                        boosted_color = [
+                            min(1.0, base_color[0] * boost),
+                            min(1.0, base_color[1] * boost),
+                            min(1.0, base_color[2] * boost),
+                            base_color[3] if len(base_color) > 3 else 1.0,
+                        ]
+                        if boosted_color != base_color:
+                            pbr.baseColorFactor = boosted_color
+                            boost_percent = int((boost - 1.0) * 100)
+                            logger.info(
+                                f"Boosted baseColorFactor for material {i} "
+                                f"({boost_percent}% brightness increase, multiplier: {boost})"
+                            )
+
+            # Add emissive factor to make models super bright and visible
+            if (
+                not hasattr(material, "emissiveFactor")
+                or material.emissiveFactor is None
+            ):
+                emissive_value = BRIGHTNESS_CONFIG["emissive_base"]
+                material.emissiveFactor = [
+                    emissive_value,
+                    emissive_value,
+                    emissive_value,
+                ]
+                logger.info(
+                    f"Added emissiveFactor to material {i} "
+                    f"(glow: {emissive_value}, config: {BRIGHTNESS_CONFIG['emissive_base']})"
+                )
+            else:
+                # Boost existing emissive
+                emissive = material.emissiveFactor
+                if isinstance(emissive, list) and len(emissive) >= 3:
+                    emissive_max = BRIGHTNESS_CONFIG["emissive_max"]
+                    emissive_base = BRIGHTNESS_CONFIG["emissive_base"]
+                    boosted_emissive = [
+                        min(emissive_max, emissive[0] + emissive_base),
+                        min(emissive_max, emissive[1] + emissive_base),
+                        min(emissive_max, emissive[2] + emissive_base),
+                    ]
+                    material.emissiveFactor = boosted_emissive
+                    logger.info(
+                        f"Boosted emissiveFactor for material {i} "
+                        f"(glow: {boosted_emissive}, max: {emissive_max})"
+                    )
+
+
+# ============================================================================
+# File-based Material Normalization
+# ============================================================================
+
+
+def normalize_materials_for_ar(glb_path: Path) -> None:
+    """Normalize materials in GLB/GLTF file for AR visibility.
+
+    This function can be applied to both GLB and GLTF files directly.
+    It adjusts material properties to ensure models appear bright in AR.
+
+    Args:
+        glb_path: Path to the GLB or GLTF file to modify
+    """
+    try:
+        from pygltflib import GLTF2
+
+        logger.info(f"Loading GLB/GLTF for brightness normalization: {glb_path}")
+        gltf = GLTF2.load(str(glb_path))
+
+        # Normalize materials using the shared function
+        normalize_gltf_materials(gltf)
+
+        # Save the modified GLB/GLTF file
+        gltf.save(str(glb_path))
+        logger.info(f"✓ Brightness normalization saved to: {glb_path}")
+
+    except ImportError:
+        logger.error("pygltflib not available - cannot normalize materials")
+        raise RuntimeError("pygltflib required for material normalization")
+    except Exception as e:
+        logger.error(f"Failed to normalize materials: {e}")
+        import traceback
+
+        logger.error(f"Material normalization traceback: {traceback.format_exc()}")
+        raise RuntimeError(f"Failed to normalize materials: {e}") from e

services/database_service.py

@@ -0,0 +1,196 @@
+"""Database service for SQLite operations to store API request logs."""
+
+import sqlite3
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, Dict, Any
+from contextlib import contextmanager
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseService:
+    """Service for managing SQLite database operations for API request logging."""
+
+    def __init__(self, db_path: str = "api_requests.db"):
+        """Initialize the database service.
+
+        Args:
+            db_path: Path to the SQLite database file
+        """
+        self.db_path = Path(db_path)
+        self._ensure_db_directory()
+        self._initialize_database()
+
+    def _ensure_db_directory(self):
+        """Ensure the directory for the database file exists."""
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _initialize_database(self):
+        """Initialize the database and create tables if they don't exist."""
+        try:
+            with self._get_connection() as conn:
+                cursor = conn.cursor()
+                cursor.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS api_requests (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        timestamp_utc TEXT NOT NULL,
+                        method TEXT NOT NULL,
+                        path TEXT NOT NULL,
+                        client_ip TEXT,
+                        user_agent TEXT,
+                        created_at TEXT NOT NULL DEFAULT (datetime('now', 'utc'))
+                    )
+                """
+                )
+
+                # Create index on timestamp for faster queries
+                cursor.execute(
+                    """
+                    CREATE INDEX IF NOT EXISTS idx_timestamp_utc 
+                    ON api_requests(timestamp_utc)
+                """
+                )
+
+                # Create index on client_ip for faster queries
+                cursor.execute(
+                    """
+                    CREATE INDEX IF NOT EXISTS idx_client_ip 
+                    ON api_requests(client_ip)
+                """
+                )
+
+                conn.commit()
+                logger.info(f"✓ Database initialized: {self.db_path}")
+        except Exception as e:
+            logger.error(f"Failed to initialize database: {e}")
+            raise
+
+    @contextmanager
+    def _get_connection(self):
+        """Get a database connection with proper error handling."""
+        conn = None
+        try:
+            conn = sqlite3.connect(str(self.db_path), timeout=10.0)
+            conn.row_factory = sqlite3.Row  # Return rows as dictionaries
+            yield conn
+        except sqlite3.Error as e:
+            logger.error(f"Database error: {e}")
+            if conn:
+                conn.rollback()
+            raise
+        finally:
+            if conn:
+                conn.close()
+
+    def log_request(
+        self,
+        method: str,
+        path: str,
+        client_ip: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ):
+        """Log an API request to the database immediately when received.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: Request path
+            client_ip: Client IP address
+            user_agent: User agent string
+        """
+        try:
+            # Get UTC timestamp
+            timestamp_utc = datetime.now(timezone.utc).isoformat()
+
+            with self._get_connection() as conn:
+                cursor = conn.cursor()
+                cursor.execute(
+                    """
+                    INSERT INTO api_requests 
+                    (timestamp_utc, method, path, client_ip, user_agent)
+                    VALUES (?, ?, ?, ?, ?)
+                """,
+                    (
+                        timestamp_utc,
+                        method,
+                        path,
+                        client_ip,
+                        user_agent,
+                    ),
+                )
+                conn.commit()
+        except Exception as e:
+            # Log error but don't fail the request
+            logger.error(f"Failed to log request to database: {e}")
+
+    def get_requests(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+        client_ip: Optional[str] = None,
+        method: Optional[str] = None,
+    ) -> list[Dict[str, Any]]:
+        """Get API requests from the database.
+
+        Args:
+            limit: Maximum number of requests to return
+            offset: Number of requests to skip
+            client_ip: Filter by client IP (optional)
+            method: Filter by HTTP method (optional)
+
+        Returns:
+            List of request dictionaries
+        """
+        try:
+            with self._get_connection() as conn:
+                cursor = conn.cursor()
+
+                query = "SELECT * FROM api_requests WHERE 1=1"
+                params = []
+
+                if client_ip:
+                    query += " AND client_ip = ?"
+                    params.append(client_ip)
+
+                if method:
+                    query += " AND method = ?"
+                    params.append(method)
+
+                query += " ORDER BY timestamp_utc DESC LIMIT ? OFFSET ?"
+                params.extend([limit, offset])
+
+                cursor.execute(query, params)
+                rows = cursor.fetchall()
+
+                return [dict(row) for row in rows]
+        except Exception as e:
+            logger.error(f"Failed to get requests from database: {e}")
+            return []
+
+    def get_request_count(self, client_ip: Optional[str] = None) -> int:
+        """Get total count of requests.
+
+        Args:
+            client_ip: Filter by client IP (optional)
+
+        Returns:
+            Total count of requests
+        """
+        try:
+            with self._get_connection() as conn:
+                cursor = conn.cursor()
+
+                if client_ip:
+                    cursor.execute(
+                        "SELECT COUNT(*) FROM api_requests WHERE client_ip = ?",
+                        (client_ip,),
+                    )
+                else:
+                    cursor.execute("SELECT COUNT(*) FROM api_requests")
+
+                return cursor.fetchone()[0]
+        except Exception as e:
+            logger.error(f"Failed to get request count from database: {e}")
+            return 0

services/huggingface_service.py

@@ -0,0 +1,807 @@
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import uuid
+import time
+from pathlib import Path
+from gradio_client import Client, handle_file
+from gradio_client import exceptions as gradio_exceptions
+import httpx
+
+
+from config import (
+    HF_TOKEN,
+    MODEL_STORAGE_PATH,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class HuggingFaceService:
+    """Handles 3D model generation via Hugging Face Spaces."""
+
+    # ============================================================================
+    # Initialization
+    # ============================================================================
+
+    def __init__(self):
+        """Initializes all Gradio Clients.
+
+        Note: HF_TOKEN is optional. If not provided, Spaces will use their own quota.
+        If provided, authenticated calls may consume your GPU quota.
+        """
+        # HF_TOKEN is optional - we'll try without it first to avoid consuming your quota
+
+        self.trellis_client: Client | None = None
+        self.shap_e_client: Client | None = None
+        self.hunyuan_client: Client | None = None
+        self.trellis_client2: Client | None = None
+
+        # Ensure model storage directory exists
+        self.storage_path = Path(MODEL_STORAGE_PATH)
+        self.storage_path.mkdir(parents=True, exist_ok=True)
+
+        # Initialize TRELLIS client (non-blocking - text-to-3D features will be unavailable if this fails)
+        # Hugging Face Spaces can be slow or sleeping (free tier), so we retry with backoff
+        self.trellis_client = self._initialize_client_with_retry(
+            "dkatz2391/TRELLIS_TextTo3D_Try2",
+            "TRELLIS",
+            max_retries=2,
+        )
+
+        # Initialize Shap-E client (non-blocking)
+        self.shap_e_client = self._initialize_client_with_retry(
+            "hysts/Shap-E",
+            "Shap-E",
+            max_retries=2,
+        )
+
+        # Initialize Hunyuan3D-2 client for image-to-3D (non-blocking)
+        self.hunyuan_client = self._initialize_client_with_retry(
+            "tencent/Hunyuan3D-2.1",
+            "Hunyuan3D-2",
+            max_retries=2,
+        )
+        self.trellis_client2 = self._initialize_client_with_retry(
+            "trellis-community/TRELLIS",
+            "TRELLIS-2",
+            max_retries=2,
+        )
+
+    def _initialize_client_with_retry(
+        self, space_id: str, service_name: str, max_retries: int = 2
+    ) -> Client | None:
+        """Initialize a Gradio Client with retry logic and exponential backoff.
+
+        Hugging Face Spaces on the free tier can be slow to respond or sleeping,
+        so we retry with increasing delays.
+
+        Args:
+            space_id: Hugging Face Space ID (e.g., "username/space-name")
+            service_name: Human-readable name for logging
+            max_retries: Maximum number of retry attempts
+
+        Returns:
+            Client instance if successful, None if all retries failed
+        """
+        for attempt in range(max_retries + 1):
+            try:
+                if attempt > 0:
+                    # Exponential backoff: 5s, 10s
+                    wait_time = 5 * (2 ** (attempt - 1))
+                    logger.info(
+                        f"Retrying {service_name} initialization (attempt {attempt + 1}/{max_retries + 1}) "
+                        f"after {wait_time}s delay..."
+                    )
+                    time.sleep(wait_time)
+
+                logger.info(
+                    f"Initializing {service_name} Client (attempt {attempt + 1}/{max_retries + 1})..."
+                )
+                # Try without token first to avoid consuming your GPU quota
+                # Most public Spaces work without authentication and use their own quota
+                try:
+                    client = Client(space_id)  # No token - uses Space owner's quota
+                    logger.info(
+                        f"✓ {service_name} Gradio Client initialized (no token - using Space owner's quota)"
+                    )
+                    return client
+                except Exception as no_token_error:
+                    # If that fails, try with token (may consume your GPU quota)
+                    if HF_TOKEN:
+                        logger.warning(
+                            f"{service_name} requires authentication. Using HF_TOKEN (may consume your GPU quota)"
+                        )
+                        client = Client(space_id, hf_token=HF_TOKEN)
+                        logger.info(
+                            f"✓ {service_name} Gradio Client initialized (with token)"
+                        )
+                        return client
+                    else:
+                        # Re-raise the original error if no token available
+                        raise no_token_error
+
+            except Exception as e:
+                error_msg = str(e).lower()
+                is_timeout = "timeout" in error_msg or "timed out" in error_msg
+
+                if attempt < max_retries:
+                    logger.warning(
+                        f"{service_name} initialization attempt {attempt + 1} failed: {e}. "
+                        f"Will retry..."
+                    )
+                else:
+                    # Final attempt failed
+                    if is_timeout:
+                        logger.warning(
+                            f"Failed to initialize {service_name} Client after {max_retries + 1} attempts: {e}. "
+                            f"This is likely because the Hugging Face Space is sleeping (free tier) or slow to respond. "
+                            f"{service_name} features will not be available. "
+                            f"The Space will wake up automatically when first used, but initialization may take longer."
+                        )
+                    else:
+                        logger.warning(
+                            f"Failed to initialize {service_name} Client after {max_retries + 1} attempts: {e}. "
+                            f"{service_name} features will not be available."
+                        )
+                    return None
+
+        return None
+
+    # ============================================================================
+    # Public API - Model Generation
+    # ============================================================================
+
+    def text_to_3d(self, prompt: str, model_id: str | None = None) -> str:
+        """Generate a 3D model directly from a text prompt using TRELLIS.
+
+        Uses the /generate_and_extract_glb endpoint which:
+        - Generates 3D model from text
+        - Extracts GLB with textures
+        - Returns GLB file path directly
+
+        Args:
+            prompt: Text prompt for 3D model generation
+            model_id: Optional model ID to use for the filename. If not provided, generates a new UUID.
+
+        Returns:
+            Path to the generated GLB file
+        """
+        if not self.trellis_client:
+            raise RuntimeError("TRELLIS Client not initialized.")
+
+        logger.info(f"Generating 3D model from text prompt: '{prompt[:60]}...'")
+
+        filename = model_id if model_id else str(uuid.uuid4())
+        glb_path = self.storage_path / f"{filename}.glb"
+
+        try:
+            # TRELLIS API Endpoint Comparison:
+            # - /generate_and_extract_glb: Returns GLB file directly with textures
+            #   Includes mesh_simplify and texture_size parameters for AR optimization
+            # - /text_to_3d: Basic endpoint, may return raw 3D data (needs testing)
+            #   Missing mesh_simplify and texture_size parameters
+            #
+            # We use /generate_and_extract_glb because:
+            # 1. Returns GLB file path/URL directly (no additional extraction step)
+            # 2. Includes texture_size parameter (critical for texture export)
+            # 3. Includes mesh_simplify parameter (optimizes for AR performance)
+            # 4. One-step process - generates and extracts in single call
+            logger.info("Generating 3D model with TRELLIS...")
+
+            try:
+                result = self.trellis_client.predict(
+                    prompt=prompt,
+                    seed=0,  # Fixed seed for reproducibility
+                    ss_guidance_strength=7.5,
+                    ss_sampling_steps=25,
+                    slat_guidance_strength=7.5,
+                    slat_sampling_steps=25,
+                    mesh_simplify=0.95,  # Slight simplification for AR
+                    texture_size=1024,  # Texture size - key for texture export!
+                    api_name="/generate_and_extract_glb",  # Returns GLB directly
+                )
+
+                logger.debug(f"TRELLIS result type: {type(result)}")
+                logger.debug(f"TRELLIS result: {result}")
+
+            except gradio_exceptions.AppError as app_error:
+                logger.error(f"TRELLIS AppError: {app_error}")
+                raise RuntimeError(
+                    f"TRELLIS Space returned an error: {app_error}. "
+                    f"This might mean: 1) The Space is busy or has queue limits, "
+                    f"2) The prompt is invalid, 3) The Space is experiencing issues."
+                ) from app_error
+
+            except Exception as api_error:
+                logger.error(f"TRELLIS API call failed: {api_error}")
+                import traceback
+
+                logger.error(f"Full traceback: {traceback.format_exc()}")
+                raise RuntimeError(
+                    f"TRELLIS API call failed: {api_error}"
+                ) from api_error
+
+            # TRELLIS returns a string (file path or URL) directly
+            if isinstance(result, str):
+                glb_file_path = result
+            elif isinstance(result, dict) and "value" in result:
+                # Sometimes Gradio returns dict with 'value' key
+                glb_file_path = result["value"]
+            else:
+                logger.error(
+                    f"Unexpected TRELLIS result format: {type(result)}, value: {result}"
+                )
+                raise RuntimeError(f"Unexpected TRELLIS result format: {type(result)}")
+
+            if not glb_file_path or not isinstance(glb_file_path, str):
+                raise RuntimeError(
+                    f"TRELLIS returned invalid file path: {glb_file_path}"
+                )
+
+            # TRELLIS may return a URL instead of a local file path
+            if glb_file_path.startswith("http://") or glb_file_path.startswith(
+                "https://"
+            ):
+                # Download the GLB file from the URL
+                logger.info(f"TRELLIS returned URL, downloading GLB: {glb_file_path}")
+
+                try:
+                    with httpx.Client(timeout=60.0) as client:
+                        response = client.get(glb_file_path)
+                        response.raise_for_status()
+
+                        # Ensure parent directory exists before saving
+                        glb_path.parent.mkdir(parents=True, exist_ok=True)
+
+                        # Save to our storage
+                        with open(glb_path, "wb") as f:
+                            f.write(response.content)
+
+                        logger.info(
+                            f"✓ Downloaded TRELLIS GLB: {glb_path} ({os.path.getsize(glb_path)} bytes)"
+                        )
+                except Exception as download_error:
+                    logger.error(f"Failed to download GLB from URL: {download_error}")
+                    raise RuntimeError(
+                        f"Failed to download GLB from TRELLIS URL: {download_error}"
+                    )
+            else:
+                # Local file path - check if it exists and copy it
+                if not Path(glb_file_path).exists():
+                    raise RuntimeError(
+                        f"Generated GLB file not found: {glb_file_path}. "
+                        f"TRELLIS may have failed to generate the model."
+                    )
+
+                # Ensure parent directory exists before copying
+                glb_path.parent.mkdir(parents=True, exist_ok=True)
+
+                # Copy the generated GLB to our storage
+                shutil.copy(glb_file_path, glb_path)
+                logger.info(
+                    f"✓ TRELLIS GLB generated: {glb_path} ({os.path.getsize(glb_path)} bytes)"
+                )
+
+            return str(glb_path)
+
+        except Exception as e:
+            logger.error(f"TRELLIS text-to-3D generation failed: {e}")
+            raise RuntimeError(f"3D model generation failed: {e}")
+
+    def text_to_3d_shap_e(self, prompt: str, model_id: str | None = None) -> str:
+        """Generate a 3D model from text prompt using Shap-E.
+
+        Uses Shap-E for advanced 3D model generation from text prompts.
+        Uses the /text_to_3d endpoint with the prompt parameter for text-to-3D.
+        API Reference: https://huggingface.co/spaces/hysts/Shap-E
+
+        Args:
+            prompt: Text prompt for 3D model generation
+            model_id: Optional model ID to use for the filename. If not provided, generates a new UUID.
+
+        Returns:
+            Path to the generated GLB file
+        """
+        if not self.shap_e_client:
+            raise RuntimeError("Shap-E Client not initialized.")
+
+        logger.info(
+            f"Generating 3D model with Shap-E from text prompt: '{prompt[:60]}...'"
+        )
+
+        filename = model_id if model_id else str(uuid.uuid4())
+        glb_path = self.storage_path / f"{filename}.glb"
+
+        try:
+            logger.info("Generating 3D model with Shap-E...")
+
+            try:
+                DEFAULT_SEED = 0
+                DEFAULT_GUIDANCE_SCALE = 20.0
+                DEFAULT_STEPS = 100
+                # Shap-E /text-to-3d endpoint typically accepts:
+                # - prompt (str)
+                # - seed (int/float)
+                # - guidance_scale (float)
+                # - num_inference_steps (int) - not "steps"
+                result = self.shap_e_client.predict(
+                    prompt=prompt,
+                    seed=DEFAULT_SEED,
+                    guidance_scale=DEFAULT_GUIDANCE_SCALE,
+                    num_inference_steps=DEFAULT_STEPS,  # This value is correctly mapped to 'num_inference_steps'
+                    api_name="/text-to-3d",
+                )
+
+                logger.debug(f"Shap-E result type: {type(result)}")
+                logger.debug(f"Shap-E result: {result}")
+
+            except gradio_exceptions.AppError as app_error:
+                logger.error(f"Shap-E AppError: {app_error}")
+                raise RuntimeError(
+                    f"Shap-E Space returned an error: {app_error}. "
+                    f"This might mean: 1) The Space is busy or has queue limits, "
+                    f"2) The prompt is invalid, 3) The Space is experiencing issues."
+                ) from app_error
+
+            except Exception as api_error:
+                logger.error(f"Shap-E API call failed: {api_error}")
+                import traceback
+
+                logger.error(f"Full traceback: {traceback.format_exc()}")
+                raise RuntimeError(
+                    f"Shap-E API call failed: {api_error}"
+                ) from api_error
+
+            # Handle result - format depends on the actual endpoint response
+            if isinstance(result, str):
+                temp_file_path = result
+            elif isinstance(result, (list, tuple)) and len(result) > 0:
+                # Shap-E may return a tuple/list with file path as first element
+                temp_file_path = result[0]
+            elif isinstance(result, dict):
+                # Check for common keys that might contain file path
+                if "file" in result:
+                    temp_file_path = result["file"]
+                elif "value" in result:
+                    temp_file_path = result["value"]
+                else:
+                    logger.error(
+                        f"Unexpected Shap-E result format: {type(result)}, value: {result}"
+                    )
+                    raise RuntimeError(
+                        f"Unexpected Shap-E result format: {type(result)}"
+                    )
+            else:
+                logger.error(
+                    f"Unexpected Shap-E result format: {type(result)}, value: {result}"
+                )
+                raise RuntimeError(f"Unexpected Shap-E result format: {type(result)}")
+
+            if not temp_file_path or not isinstance(temp_file_path, str):
+                raise RuntimeError(
+                    f"Shap-E returned invalid file path: {temp_file_path}"
+                )
+
+            # Shap-E may return a URL instead of a local file path
+            if temp_file_path.startswith("http://") or temp_file_path.startswith(
+                "https://"
+            ):
+                # Download the GLB file from the URL
+                logger.info(f"Shap-E returned URL, downloading GLB: {temp_file_path}")
+
+                try:
+                    with httpx.Client(timeout=120.0) as client:
+                        response = client.get(temp_file_path)
+                        response.raise_for_status()
+
+                        # Ensure parent directory exists before saving
+                        glb_path.parent.mkdir(parents=True, exist_ok=True)
+
+                        # Save to our storage
+                        with open(glb_path, "wb") as f:
+                            f.write(response.content)
+
+                        logger.info(
+                            f"✓ Downloaded Shap-E GLB: {glb_path} ({os.path.getsize(glb_path)} bytes)"
+                        )
+                except Exception as download_error:
+                    logger.error(f"Failed to download GLB from URL: {download_error}")
+                    raise RuntimeError(
+                        f"Failed to download GLB from Shap-E URL: {download_error}"
+                    )
+            else:
+                # Local file path - check if it exists and copy it
+                if not Path(temp_file_path).exists():
+                    raise RuntimeError(
+                        f"Generated GLB file not found: {temp_file_path}. "
+                        f"Shap-E may have failed to generate the model."
+                    )
+
+                # Ensure parent directory exists before copying
+                glb_path.parent.mkdir(parents=True, exist_ok=True)
+
+                # Note: Shap-E might return a .ply, but we save it as .glb
+                # as requested by the function signature.
+                shutil.copy(temp_file_path, glb_path)
+                logger.info(
+                    f"✓ Shap-E GLB generated: {glb_path} ({os.path.getsize(glb_path)} bytes)"
+                )
+
+            return str(glb_path)
+
+        except Exception as e:
+            logger.error(f"Shap-E text-to-3D generation failed: {e}")
+            raise RuntimeError(f"3D model generation failed: {e}")
+
+    def image_to_3d_hunyuan(
+        self, image_file_path: str, model_id: str | None = None
+    ) -> str:
+        """
+        Generate a 3D model from a 2D image using Hunyuan3D.
+
+        This optimized version performs remote chaining of the /generation_all and
+        /on_export_click steps to avoid slow local download/re-upload cycles of intermediary files.
+        """
+        if not self.hunyuan_client:
+            raise RuntimeError("Hunyuan3D Client not initialized.")
+
+        if not Path(image_file_path).exists():
+            logger.error(f"Input image file not found at: {image_file_path}")
+            raise FileNotFoundError(f"Input image file not found: {image_file_path}")
+
+        logger.info(
+            f"Generating 3D model with Hunyuan3D from image file: '{image_file_path}'"
+        )
+
+        filename = model_id if model_id else str(uuid.uuid4())
+        glb_path = self.storage_path / f"{filename}.glb"
+
+        # Default parameters - Tuned for faster generation time and to avoid GPU quota limits
+        DEFAULT_STEPS = 15  # Further reduced from 20 to decrease generation time and avoid GPU quota limits (Job requested 180s vs 75s left)
+        DEFAULT_GUIDANCE = 5.0
+        DEFAULT_SEED = 1234
+        RANDOMIZE_SEED = True
+        DEFAULT_OCTREE_RES = 128  # Further reduced from 192 to decrease generation time and avoid GPU quota limits
+        REMOVE_BG = True
+        DEFAULT_NUM_CHUNKS = (
+            4000  # Further reduced from 5000 to decrease generation time
+        )
+
+        # Helper function to extract file path, handling Gradio's inconsistent wrapping
+        def extract_path(result_part):
+            if isinstance(result_part, dict):
+                # Check for 'value' (from previous API return) or 'path'/'name' (if pre-wrapped)
+                if "value" in result_part:
+                    return result_part["value"]
+                if "path" in result_part:
+                    return result_part["path"]
+                if "name" in result_part:
+                    return result_part["name"]
+            return result_part
+
+        # Helper function to wrap a remote path into the required dictionary format for the next API call
+        # CRITICAL: Use 'path' as the key to satisfy the downstream Gradio component's FileData validation.
+        def format_for_remote_api(path: str) -> dict:
+            return {"path": path}
+
+        try:
+            # --- Step 1: Call /generation_all to get mesh and texture ---
+            logger.info("Hunyuan3D Step 1/2: Calling /generation_all...")
+            try:
+                gen_result = self.hunyuan_client.predict(
+                    image=handle_file(image_file_path),
+                    mv_image_front=None,
+                    mv_image_back=None,
+                    mv_image_left=None,
+                    mv_image_right=None,
+                    steps=DEFAULT_STEPS,
+                    guidance_scale=DEFAULT_GUIDANCE,
+                    seed=DEFAULT_SEED,
+                    octree_resolution=DEFAULT_OCTREE_RES,
+                    check_box_rembg=REMOVE_BG,
+                    num_chunks=DEFAULT_NUM_CHUNKS,
+                    randomize_seed=RANDOMIZE_SEED,
+                    api_name="/generation_all",
+                )
+
+                logger.debug(f"Hunyuan3D /generation_all result: {gen_result}")
+
+            except gradio_exceptions.AppError as app_error:
+                logger.error(f"Hunyuan3D /generation_all AppError: {app_error}")
+                raise RuntimeError(
+                    f"Hunyuan3D Space (generation) returned an error: {app_error}."
+                ) from app_error
+            except Exception as api_error:
+                logger.error(f"Hunyuan3D /generation_all API call failed: {api_error}")
+                import traceback
+
+                logger.error(f"Full traceback: {traceback.format_exc()}")
+                raise RuntimeError(
+                    f"Hunyuan3D /generation_all API call failed: {api_error}"
+                ) from api_error
+
+            # /generation_all returns a tuple of 5 elements
+            if not isinstance(gen_result, (list, tuple)) or len(gen_result) < 2:
+                raise RuntimeError(
+                    f"Unexpected result from Hunyuan3D /generation_all: {gen_result}"
+                )
+
+            # Extract raw remote paths (strings)
+            mesh_raw_path = extract_path(gen_result[0])
+            texture_raw_path = extract_path(gen_result[1])
+
+            if not mesh_raw_path:
+                raise RuntimeError(
+                    f"Hunyuan3D /generation_all did not return a mesh file path."
+                )
+
+            logger.info(f"Hunyuan3D generated mesh: {mesh_raw_path}")
+            logger.info(f"Hunyuan3D generated texture: {texture_raw_path}")
+
+            # Check if /generation_all already returned a GLB file (rare, but possible)
+            if isinstance(texture_raw_path, str) and texture_raw_path.endswith(".glb"):
+                logger.info(
+                    "Hunyuan3D /generation_all already returned a GLB file, skipping export step."
+                )
+                temp_file_path = texture_raw_path
+            else:
+                # --- Step 2: Call /on_export_click to convert to GLB (Remote Chaining) ---
+                logger.info(
+                    "Hunyuan3D Step 2/2: Calling /on_export_click to export GLB (Remote Chaining)..."
+                )
+
+                # Pass remote paths directly, formatted in the exact structure Gradio needs: {"path": path}.
+                file_out_param = format_for_remote_api(mesh_raw_path)
+
+                if texture_raw_path:
+                    file_out2_param = format_for_remote_api(texture_raw_path)
+                    export_texture_flag = True
+                else:
+                    # Use mesh for file_out2 if texture is missing
+                    file_out2_param = format_for_remote_api(mesh_raw_path)
+                    export_texture_flag = False
+                    logger.info(
+                        "No texture file generated, using mesh file for both file_out parameters"
+                    )
+
+                try:
+                    export_result = self.hunyuan_client.predict(
+                        file_out=file_out_param,  # Optimized: {"path": "/remote/path"}
+                        file_out2=file_out2_param,  # Optimized: {"path": "/remote/path"}
+                        file_type="glb",
+                        reduce_face=False,
+                        export_texture=export_texture_flag,
+                        target_face_num=10000,
+                        api_name="/on_export_click",
+                    )
+
+                    logger.debug(f"Hunyuan3D /on_export_click result: {export_result}")
+
+                except gradio_exceptions.AppError as app_error:
+                    logger.error(f"Hunyuan3D /on_export_click AppError: {app_error}")
+                    raise RuntimeError(
+                        f"Hunyuan3D Space (export) returned an error: {app_error}."
+                    ) from app_error
+                except Exception as api_error:
+                    logger.error(
+                        f"Hunyuan3D /on_export_click API call failed: {api_error}"
+                    )
+
+                    import traceback
+
+                    logger.error(f"Full traceback: {traceback.format_exc()}")
+                    raise RuntimeError(
+                        f"Hunyuan3D /on_export_click API call failed: {api_error}"
+                    ) from api_error
+
+                # /on_export_click returns a tuple of 2 elements
+                if (
+                    not isinstance(export_result, (list, tuple))
+                    or len(export_result) < 2
+                ):
+                    raise RuntimeError(
+                        f"Unexpected result from Hunyuan3D /on_export_click: {export_result}"
+                    )
+
+                # Final result is the downloaded GLB URL/path
+                temp_file_path = extract_path(export_result[1])
+
+            if not temp_file_path or not isinstance(temp_file_path, str):
+                raise RuntimeError(
+                    f"Hunyuan3D /on_export_click returned invalid file path: {temp_file_path}"
+                )
+
+            # --- Step 3: Handle the final GLB file (download or copy) ---
+            # The final GLB URL is the only file we need to download locally
+            if temp_file_path.startswith("http://") or temp_file_path.startswith(
+                "https://"
+            ):
+                logger.info(
+                    f"Hunyuan3D returned URL, downloading GLB: {temp_file_path}"
+                )
+                try:
+                    with httpx.Client(timeout=120.0) as client:
+                        response = client.get(temp_file_path)
+                        response.raise_for_status()
+
+                        glb_path.parent.mkdir(parents=True, exist_ok=True)
+
+                        with open(glb_path, "wb") as f:
+                            f.write(response.content)
+                        logger.info(
+                            f"✓ Downloaded Hunyuan3D GLB: {glb_path} ({os.path.getsize(glb_path)} bytes)"
+                        )
+                except Exception as download_error:
+                    logger.error(f"Failed to download GLB from URL: {download_error}")
+                    raise RuntimeError(
+                        f"Failed to download GLB from Hunyuan3D URL: {download_error}"
+                    )
+            else:
+                if not Path(temp_file_path).exists():
+                    raise RuntimeError(
+                        f"Generated GLB file not found: {temp_file_path}. "
+                    )
+
+                glb_path.parent.mkdir(parents=True, exist_ok=True)
+
+                shutil.copy(temp_file_path, glb_path)
+                logger.info(
+                    f"✓ Hunyuan3D GLB generated: {glb_path} ({os.path.getsize(glb_path)} bytes)"
+                )
+
+            return str(glb_path)
+
+        except Exception as e:
+            logger.error(f"Hunyuan3D image-to-3D generation failed: {e}")
+            raise RuntimeError(f"3D model generation failed: {e}")
+
+    def image_to_3d_TRELLIS(
+        self, image_file_path: str, model_id: str | None = None
+    ) -> str:
+        """
+        Generate a 3D model from a 2D image using the TRELLIS API endpoint.
+
+        This function has been streamlined to use the single-step TRELLIS API
+        endpoint (`/generate_and_extract_glb`) for faster, simpler generation,
+        assuming the client (self.trellis_client2) is configured for the TRELLIS Space.
+
+        Args:
+            image_file_path: Local file path to the input 2D image.
+            model_id: Optional model ID to use for the output filename.
+
+        Returns:
+            Path to the generated GLB file (local storage path).
+        """
+        # NOTE: Assuming self.trellis_client is now used for the TRELLIS-style generation.
+        if not self.trellis_client2:
+            raise RuntimeError(
+                "3D Generation Client not initialized (using TRELLIS single-step API)."
+            )
+
+        input_path = Path(image_file_path)
+        if not input_path.exists():
+            logger.error(f"Input image file not found at: {image_file_path}")
+            raise FileNotFoundError(f"Input image file not found: {image_file_path}")
+
+        logger.info(
+            f"Generating 3D model with TRELLIS (single-step) from image file: '{image_file_path}'"
+        )
+
+        filename = model_id if model_id else str(uuid.uuid4())
+        glb_path = self.storage_path / f"{filename}.glb"
+
+        # Helper function to extract file path, handling Gradio's inconsistent wrapping
+        def extract_path(result_part):
+            if isinstance(result_part, dict):
+                if "value" in result_part:
+                    return result_part["value"]
+                if "path" in result_part:
+                    return result_part["path"]
+                if "name" in result_part:
+                    return result_part["name"]
+            return result_part
+
+        try:
+            # --- Step 1: Call /generate_and_extract_glb (TRELLIS single-step API) ---
+            logger.info("TRELLIS Step 1/1: Calling /generate_and_extract_glb...")
+
+            # Parameters derived from the TRELLIS Gradio API example
+            # Using self.trellis_client2 as the client for this operation
+            gen_result = self.trellis_client2.predict(
+                image=handle_file(image_file_path),
+                multiimages=[],
+                seed=0,
+                ss_guidance_strength=7.5,
+                ss_sampling_steps=12,
+                slat_guidance_strength=3,
+                slat_sampling_steps=12,
+                multiimage_algo="stochastic",
+                mesh_simplify=0.95,
+                texture_size=1024,
+                api_name="/generate_and_extract_glb",
+            )
+
+            logger.debug(f"TRELLIS /generate_and_extract_glb result: {gen_result}")
+
+            if not isinstance(gen_result, (list, tuple)) or not gen_result:
+                raise RuntimeError(
+                    f"Unexpected result from TRELLIS /generate_and_extract_glb: {gen_result}"
+                )
+
+            # The TRELLIS endpoint returns a tuple of 3 elements: [video, glb/gaussian, download_glb]
+            # The second element (index [1]) is the file path for the Litmodel3d component (glb/gaussian).
+            # We check the first element ([0]) which is the video component, as it often contains the file path first.
+
+            # The TRELLIS API documentation shows the video component (index 0) is the first return element.
+            # We need the path to the downloaded GLB file. Let's assume the first element path or the second element path.
+            # Based on the API doc:
+            # Returns tuple of 3 elements:
+            # [0] dict(video: filepath, subtitles: filepath | None) -> The Video component path
+            # [1] filepath -> The Litmodel3d component path (GLB/Gaussian)
+            # [2] filepath -> The Downloadbutton path (GLB)
+
+            # The most reliable path to the output file is often the second element [1] or third [2],
+            # but the original TRELLIS function used [0]. We will update to use [1] for the Litmodel3d path
+            # as it is more likely to contain the actual GLB data path when running remotely.
+
+            # Let's use index [1] or [2] if available, falling back to [0].
+            temp_file_path = (
+                extract_path(gen_result[1]) if len(gen_result) > 1 else None
+            )
+
+            if not temp_file_path:
+                temp_file_path = extract_path(gen_result[0])
+
+            if not temp_file_path or not isinstance(temp_file_path, str):
+                raise RuntimeError(
+                    f"TRELLIS returned invalid file path: {temp_file_path}"
+                )
+
+            # --- Step 2: Handle the final GLB file (download or copy) ---
+            if temp_file_path.startswith("http://") or temp_file_path.startswith(
+                "https://"
+            ):
+                logger.info(f"TRELLIS returned URL, downloading GLB: {temp_file_path}")
+                try:
+                    with httpx.Client(timeout=120.0) as http_client:
+                        response = http_client.get(temp_file_path)
+                        response.raise_for_status()
+
+                        glb_path.parent.mkdir(parents=True, exist_ok=True)
+
+                        with open(glb_path, "wb") as f:
+                            f.write(response.content)
+                        logger.info(
+                            f"✓ Downloaded TRELLIS GLB: {glb_path} ({os.path.getsize(glb_path)} bytes)"
+                        )
+                except Exception as download_error:
+                    logger.error(f"Failed to download GLB from URL: {download_error}")
+                    raise RuntimeError(
+                        f"Failed to download GLB from TRELLIS URL: {download_error}"
+                    )
+            else:
+                if not Path(temp_file_path).exists():
+                    raise RuntimeError(
+                        f"Generated GLB file not found: {temp_file_path}. "
+                    )
+
+                glb_path.parent.mkdir(parents=True, exist_ok=True)
+
+                shutil.copy(temp_file_path, glb_path)
+                logger.info(
+                    f"✓ TRELLIS GLB generated: {glb_path} ({os.path.getsize(glb_path)} bytes)"
+                )
+
+            return str(glb_path)
+
+        except gradio_exceptions.AppError as app_error:
+            logger.error(f"TRELLIS AppError: {app_error}")
+            raise RuntimeError(
+                f"TRELLIS Space returned an error during generation: {app_error}."
+            ) from app_error
+        except Exception as e:
+            logger.error(f"TRELLIS image-to-3D generation failed: {e}")
+            raise RuntimeError(f"3D model generation failed: {e}")

services/storage_service.py

@@ -0,0 +1,45 @@
+"""Storage service for managing generated models."""
+from typing import Dict, Optional
+from datetime import datetime
+import uuid
+
+
+class StorageService:
+    """In-memory storage service for generated models.
+    
+    In production, this would be replaced with a database like PostgreSQL or MongoDB.
+    """
+    
+    def __init__(self):
+        self._models: Dict[str, dict] = {}
+    
+    def create_model_record(self, prompt: str) -> str:
+        """Create a new model record and return its ID."""
+        model_id = str(uuid.uuid4())
+        self._models[model_id] = {
+            "model_id": model_id,
+            "prompt": prompt,
+            "created_at": datetime.now().isoformat(),
+            "status": "processing",
+            "file_path": None,
+            "available_formats": []
+        }
+        return model_id
+    
+    def get_model(self, model_id: str) -> Optional[dict]:
+        """Get a model by ID."""
+        return self._models.get(model_id)
+    
+    def update_model_status(self, model_id: str, status: str):
+        """Update the status of a model."""
+        if model_id in self._models:
+            self._models[model_id]["status"] = status
+
+    def set_model_file(self, model_id: str, file_path: str, fmt: str = "glb"):
+        """Set the file path and available format for a model."""
+        if model_id in self._models:
+            self._models[model_id]["file_path"] = file_path
+            formats = set(self._models[model_id].get("available_formats", []))
+            formats.add(fmt)
+            self._models[model_id]["available_formats"] = list(formats)
+

utils/__init__.py

@@ -0,0 +1,2 @@
+"""Utility modules for the backend application."""
+

utils/logging_config.py

@@ -0,0 +1,67 @@
+"""Logging configuration with colored output."""
+
+import logging
+import sys
+
+
+class ColoredFormatter(logging.Formatter):
+    """Custom formatter with colored output for different log levels."""
+
+    # ANSI color codes
+    COLORS = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[0m",  # White/Reset
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+    }
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+
+    def format(self, record):
+        """Format log record with colors."""
+        # Get the color for this log level
+        color = self.COLORS.get(record.levelname, self.RESET)
+
+        # Format the base message
+        log_message = super().format(record)
+
+        # For ERROR and CRITICAL, color the entire message
+        if record.levelname in ["ERROR", "CRITICAL"]:
+            # Color the whole message, with bold levelname
+            levelname_colored = (
+                f"{self.BOLD}{color}{record.levelname}{self.RESET}{color}"
+            )
+            log_message = log_message.replace(record.levelname, levelname_colored)
+            log_message = f"{color}{log_message}{self.RESET}"
+        else:
+            # For other levels, just color the levelname (bold)
+            levelname_colored = f"{self.BOLD}{color}{record.levelname}{self.RESET}"
+            log_message = log_message.replace(record.levelname, levelname_colored)
+
+        return log_message
+
+
+def setup_colored_logging():
+    """Set up colored logging configuration."""
+    # Create console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(logging.INFO)
+
+    # Create formatter with colors
+    formatter = ColoredFormatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    console_handler.setFormatter(formatter)
+
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(logging.INFO)
+    root_logger.handlers = []  # Clear existing handlers
+    root_logger.addHandler(console_handler)
+
+    # Suppress noisy loggers
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    logging.getLogger("uvicorn").setLevel(logging.INFO)
+