API_README.md

# Hunyuan3D-2.1 API Documentation

This document describes the REST API endpoints for the Hunyuan3D-2.1 service.

## Base URL

For the deployed Hugging Face Space:
```
https://asimfayaz-hunyuan3d-2-1.hf.space
```

For local development:
```
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 Format:**
Multipart/form-data with the following fields:

- `front`: (Required) Front view image file
- `back`: (Optional) Back view image file
- `left`: (Optional) Left view image file
- `right`: (Optional) Right view image file
- `options`: (Optional) JSON string with generation options

**Options JSON Format:**
```json
{
  "enable_pbr": true,
  "should_remesh": true,
  "should_texture": true
}
```

**Response:**
```json
{
  "job_id": "uuid",
  "status": "queued"
}
```

**Notes:**
- The `front` image is mandatory
- Images should be uploaded as files in multipart/form-data format
- The `options` field is optional and will use defaults if not provided
- **Texture generation is enabled by default for high-quality 3D models**

### 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,
  "stage": "current_processing_stage",
  "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

**Stage Values:**
- `queued`: Job is waiting to be processed
- `initializing`: Setting up job and converting images
- `preprocessing`: Preparing images and options
- `shape_generation`: Generating 3D mesh from images
- `face_reduction`: Optimizing mesh geometry
- `texture_generation`: Creating textures for the 3D model
- `completed`: Job finished successfully
- `failed`: Job failed with an error

## Usage Examples

### Python Example
```python
import requests
import json
import time

# Prepare files and options
files = {
    'front': ('front.png', open('front.png', 'rb'), 'image/png'),
    # Optional additional views
    # 'back': ('back.png', open('back.png', 'rb'), 'image/png'),
    # 'left': ('left.png', open('left.png', 'rb'), 'image/png'),
    # 'right': ('right.png', open('right.png', 'rb'), 'image/png'),
}

options = {
    "enable_pbr": True,
    "should_texture": True,  # Critical for 3D model quality
    "should_remesh": True
}

# Start generation
response = requests.post(
    "http://localhost:7860/api/generate",
    files=files,
    data={'options': json.dumps(options)}
)

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']}% - Stage: {data['stage']}")
    time.sleep(5)
```

### cURL Example
```bash
# Health check
curl http://localhost:7860/api/health

# Generate model
curl -X POST http://localhost:7860/api/generate \
  -F "[email protected]" \
  -F '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