API_README.md

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:

{
  "status": "ok",
  "version": "2.1"
}

2. Generate 3D Model

POST /api/generate

Start a 3D model generation job.

Request Body:

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

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

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

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

# 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:

{
  "detail": "Error message here"
}

Testing

Use the provided test script to verify the API:

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