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:

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

{
  "enable_pbr": true,
  "should_remesh": true,
  "should_texture": true
}

Response:

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

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

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

# Health check
curl http://localhost:7860/api/health

# Generate model
curl -X POST http://localhost:7860/api/generate \
  -F "front=@front.png" \
  -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:

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