Add API endpoints for 3D model generation

- Add /api/generate endpoint for starting 3D generation jobs
- Add /api/status endpoint for checking job progress and results
- Add /api/health endpoint for service health checks
- Implement background job processing with progress tracking
- Add comprehensive API documentation in API_README.md
- Support base64 image encoding and multi-view inputs
- Include proper error handling and validation

API_README.md

@@ -0,0 +1,176 @@
+# Hunyuan3D-2.1 API Documentation
+
+This document describes the REST API endpoints for the Hunyuan3D-2.1 service.
+
+## Base URL
+```
+http://localhost:7860
+```
+
+## Endpoints
+
+### 1. Health Check
+**GET** `/api/health`
+
+Check if the service is running.
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "version": "2.1"
+}
+```
+
+### 2. Generate 3D Model
+**POST** `/api/generate`
+
+Start a 3D model generation job.
+
+**Request Body:**
+```json
+{
+  "images": {
+    "front": "base64_encoded_image",
+    "back": "base64_encoded_image",  // Optional
+    "left": "base64_encoded_image",  // Optional
+    "right": "base64_encoded_image"  // Optional
+  },
+  "options": {
+    "enable_pbr": true,
+    "should_remesh": true,
+    "should_texture": true
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "job_id": "uuid",
+  "status": "queued"
+}
+```
+
+**Notes:**
+- At least one image is required
+- The `front` image is mandatory
+- Images should be base64 encoded
+- The `options` object is optional and will use defaults if not provided
+
+### 3. Check Job Status
+**GET** `/api/status?job_id=uuid`
+
+Check the status of a generation job.
+
+**Response:**
+```json
+{
+  "status": "completed|processing|queued|failed",
+  "progress": 0-100,
+  "model_urls": {
+    "glb": "url_to_glb_file"
+  }
+}
+```
+
+**Status Values:**
+- `queued`: Job is waiting to be processed
+- `processing`: Job is currently being processed
+- `completed`: Job completed successfully
+- `failed`: Job failed with an error
+
+## Usage Examples
+
+### Python Example
+```python
+import requests
+import base64
+
+# Encode image
+with open("image.png", "rb") as f:
+    image_base64 = base64.b64encode(f.read()).decode()
+
+# Start generation
+response = requests.post("http://localhost:7860/api/generate", json={
+    "images": {
+        "front": image_base64
+    },
+    "options": {
+        "enable_pbr": True,
+        "should_texture": True
+    }
+})
+
+job_id = response.json()["job_id"]
+
+# Check status
+while True:
+    status_response = requests.get(f"http://localhost:7860/api/status?job_id={job_id}")
+    data = status_response.json()
+    
+    if data["status"] == "completed":
+        print(f"Model ready: {data['model_urls']['glb']}")
+        break
+    elif data["status"] == "failed":
+        print(f"Generation failed: {data.get('error')}")
+        break
+    
+    print(f"Progress: {data['progress']}%")
+    time.sleep(5)
+```
+
+### cURL Example
+```bash
+# Health check
+curl http://localhost:7860/api/health
+
+# Generate model
+curl -X POST http://localhost:7860/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "images": {
+      "front": "base64_encoded_image_here"
+    },
+    "options": {
+      "enable_pbr": true,
+      "should_texture": true
+    }
+  }'
+
+# Check status
+curl "http://localhost:7860/api/status?job_id=your_job_id"
+```
+
+## Error Handling
+
+The API returns appropriate HTTP status codes:
+
+- `200`: Success
+- `400`: Bad request (invalid input)
+- `404`: Job not found
+- `500`: Internal server error
+
+Error responses include a detail message:
+```json
+{
+  "detail": "Error message here"
+}
+```
+
+## Testing
+
+Use the provided test script to verify the API:
+
+```bash
+python test_api.py
+```
+
+This will test all endpoints using the demo image.
+
+## Notes
+
+- Jobs are processed asynchronously in the background
+- The service maintains job state in memory (jobs are lost on restart)
+- Generated models are served via static file URLs
+- The texture generation step is optional and can be disabled via options 

gradio_app.py

@@ -37,20 +37,184 @@ import subprocess
 import time
 from glob import glob
 from pathlib import Path
+import base64
+import json
+import threading
+from typing import Dict, Optional, Any
+from enum import Enum
 
 import gradio as gr
 import torch
 import trimesh
 import uvicorn
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException, BackgroundTasks
 from fastapi.staticfiles import StaticFiles
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
 import uuid
 import numpy as np
+from PIL import Image
+import io
 
 from hy3dshape.utils import logger
 from hy3dpaint.convert_utils import create_glb_with_pbr_materials
 
 
+# API Models
+class JobStatus(Enum):
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class GenerateRequest(BaseModel):
+    images: Dict[str, str]  # base64 encoded images
+    options: Dict[str, Any] = {
+        "enable_pbr": True,
+        "should_remesh": True,
+        "should_texture": True
+    }
+
+
+class JobInfo:
+    def __init__(self, job_id: str):
+        self.job_id = job_id
+        self.status = JobStatus.QUEUED
+        self.progress = 0
+        self.start_time = time.time()
+        self.end_time = None
+        self.error_message = None
+        self.model_urls = {}
+        self.images = {}
+        self.options = {}
+
+
+# Global job storage
+jobs: Dict[str, JobInfo] = {}
+
+
+def create_job() -> str:
+    """Create a new job and return its ID."""
+    job_id = str(uuid.uuid4())
+    jobs[job_id] = JobInfo(job_id)
+    return job_id
+
+
+def update_job_status(job_id: str, status: JobStatus, progress: int = None, error_message: str = None):
+    """Update job status and progress."""
+    if job_id in jobs:
+        jobs[job_id].status = status
+        if progress is not None:
+            jobs[job_id].progress = progress
+        if error_message is not None:
+            jobs[job_id].error_message = error_message
+        if status in [JobStatus.COMPLETED, JobStatus.FAILED]:
+            jobs[job_id].end_time = time.time()
+
+
+def base64_to_pil_image(base64_string: str) -> Image.Image:
+    """Convert base64 string to PIL Image."""
+    try:
+        # Remove data URL prefix if present
+        if base64_string.startswith('data:image'):
+            base64_string = base64_string.split(',')[1]
+        
+        image_data = base64.b64decode(base64_string)
+        image = Image.open(io.BytesIO(image_data))
+        return image
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Invalid image data: {str(e)}")
+
+
+def process_generation_job(job_id: str, images: Dict[str, str], options: Dict[str, Any]):
+    """Background task to process generation job."""
+    global face_reduce_worker, tex_pipeline, HAS_TEXTUREGEN, SAVE_DIR
+    
+    try:
+        update_job_status(job_id, JobStatus.PROCESSING, progress=10)
+        
+        # Convert base64 images to PIL Images
+        pil_images = {}
+        for view, base64_img in images.items():
+            pil_images[view] = base64_to_pil_image(base64_img)
+        
+        # Extract options
+        enable_pbr = options.get("enable_pbr", True)
+        should_remesh = options.get("should_remesh", True)
+        should_texture = options.get("should_texture", True)
+        
+        update_job_status(job_id, JobStatus.PROCESSING, progress=20)
+        
+        # Generate 3D mesh
+        mesh, main_image, save_folder, stats, seed = _gen_shape(
+            caption=None,
+            image=pil_images,
+            mv_image_front=pil_images.get('front'),
+            mv_image_back=pil_images.get('back'),
+            mv_image_left=pil_images.get('left'),
+            mv_image_right=pil_images.get('right'),
+            steps=30,
+            guidance_scale=7.5,
+            seed=1234,
+            octree_resolution=256,
+            check_box_rembg=True,
+            num_chunks=200000,
+            randomize_seed=False,
+        )
+        
+        update_job_status(job_id, JobStatus.PROCESSING, progress=50)
+        
+        # Export white mesh
+        white_mesh_path = export_mesh(mesh, save_folder, textured=False, type='obj')
+        
+        # Face reduction
+        mesh = face_reduce_worker(mesh)
+        reduced_mesh_path = export_mesh(mesh, save_folder, textured=False, type='obj')
+        
+        update_job_status(job_id, JobStatus.PROCESSING, progress=70)
+        
+        # Texture generation if enabled
+        textured_mesh_path = None
+        if should_texture and HAS_TEXTUREGEN:
+            try:
+                text_path = os.path.join(save_folder, 'textured_mesh.obj')
+                textured_mesh_path = tex_pipeline(
+                    mesh_path=reduced_mesh_path, 
+                    image_path=main_image, 
+                    output_mesh_path=text_path, 
+                    save_glb=False
+                )
+                
+                # Convert to GLB
+                glb_path_textured = os.path.join(save_folder, 'textured_mesh.glb')
+                quick_convert_with_obj2gltf(textured_mesh_path, glb_path_textured)
+                textured_mesh_path = glb_path_textured
+                
+            except Exception as e:
+                logger.error(f"Texture generation failed: {e}")
+                textured_mesh_path = None
+        
+        update_job_status(job_id, JobStatus.PROCESSING, progress=90)
+        
+        # Prepare model URLs
+        model_urls = {}
+        if textured_mesh_path and os.path.exists(textured_mesh_path):
+            model_urls["glb"] = f"/static/{os.path.relpath(textured_mesh_path, SAVE_DIR)}"
+        else:
+            # Fallback to white mesh
+            white_glb_path = export_mesh(mesh, save_folder, textured=False, type='glb')
+            model_urls["glb"] = f"/static/{os.path.relpath(white_glb_path, SAVE_DIR)}"
+        
+        # Update job with results
+        jobs[job_id].model_urls = model_urls
+        update_job_status(job_id, JobStatus.COMPLETED, progress=100)
+        
+    except Exception as e:
+        logger.error(f"Job {job_id} failed: {e}")
+        update_job_status(job_id, JobStatus.FAILED, error_message=str(e))
+
+
 MAX_SEED = 1e7
 ENV = "Huggingface" # "Huggingface"
 if ENV == 'Huggingface':
@@ -907,6 +1071,69 @@ if __name__ == '__main__':
     # create a FastAPI app
     app = FastAPI()
     
+    # API Endpoints
+    @app.post("/api/generate")
+    async def generate_3d_model(request: GenerateRequest, background_tasks: BackgroundTasks):
+        """Generate 3D model from images."""
+        try:
+            # Validate input
+            if not request.images:
+                raise HTTPException(status_code=400, detail="At least one image is required")
+            
+            if 'front' not in request.images:
+                raise HTTPException(status_code=400, detail="Front image is required")
+            
+            # Create job
+            job_id = create_job()
+            
+            # Store job data
+            jobs[job_id].images = request.images
+            jobs[job_id].options = request.options
+            
+            # Start background task
+            background_tasks.add_task(
+                process_generation_job, 
+                job_id, 
+                request.images, 
+                request.options
+            )
+            
+            return JSONResponse({
+                "job_id": job_id,
+                "status": "queued"
+            })
+            
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.get("/api/status")
+    async def get_job_status(job_id: str):
+        """Get job status and results."""
+        if job_id not in jobs:
+            raise HTTPException(status_code=404, detail="Job not found")
+        
+        job = jobs[job_id]
+        
+        response = {
+            "status": job.status.value,
+            "progress": job.progress
+        }
+        
+        if job.status == JobStatus.COMPLETED:
+            response["model_urls"] = job.model_urls
+        elif job.status == JobStatus.FAILED:
+            response["error"] = job.error_message
+        
+        return JSONResponse(response)
+
+    @app.get("/api/health")
+    async def health_check():
+        """Health check endpoint."""
+        return JSONResponse({
+            "status": "ok",
+            "version": "2.1"
+        })
+    
     # create a static directory to store the static files
     static_dir = Path(SAVE_DIR).absolute()
     static_dir.mkdir(parents=True, exist_ok=True)