Spaces:
Running
on
Zero
Running
on
Zero
File size: 3,425 Bytes
e060ab5 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 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 |