README.md

---
title: Text to 3D Backend
emoji: 🎨
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# Text to 3D Model Converter - Backend

This is the backend API for the Text-to-3D Model Converter application. It provides FastAPI endpoints for:

- **Text-to-3D**: Generate 3D models from text descriptions
- **Image-to-3D**: Convert uploaded images to 3D models
- **Progress Tracking**: Real-time job progress monitoring

## Features

- 🎨 **Direct Model Loading**: Stable Diffusion and DPT models loaded locally for fast inference
- ⚡ **Async Processing**: Background job processing with progress tracking
- 🔄 **Job Management**: Cancel jobs, track progress, and get results
- ☁️ **Cloud Storage**: Automatic upload to Cloudinary for results
- 🚀 **FastAPI**: High-performance API with automatic docs

## API Endpoints

- `GET /` - Health check and model status
- `POST /generate` - Generate 3D model from text prompt
- `POST /upload` - Convert uploaded image to 3D model
- `GET /progress/{job_id}` - Get job progress
- `POST /cancel` - Cancel a running job

## Models Used

- **Image Generation**: Stable Diffusion v1.5 (runwayml/stable-diffusion-v1-5)
- **Depth Estimation**: DPT (Intel/dpt-beit-large-512)
- **3D Reconstruction**: Open3D Poisson surface reconstruction

## Environment Variables

Set these in the Space settings:

```
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
```

## Usage

The API is designed to work with the frontend application deployed on Render. CORS is configured to allow requests from the frontend domain.

### Example Request

```python
import requests

# Generate 3D model from text
response = requests.post(
    "https://your-space-url/generate",
    json={"prompt": "a red sports car"}
)

job_id = response.json()["job_id"]

# Check progress
progress = requests.get(f"https://your-space-url/progress/{job_id}")
print(progress.json())
```

## Development

To run locally:

```bash
pip install -r requirements.txt
python app.py
```

The API will be available at `http://localhost:7860`