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