Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
248 lines (185 loc) · 6.59 KB

API_DOCUMENTATION.md

File metadata and controls

248 lines (185 loc) · 6.59 KB

Hunyuan3D API Documentation

This document explains how the FastAPI documentation has been enhanced to provide comprehensive parameter documentation for the Hunyuan3D API server.

Overview

The API server now uses Pydantic models to automatically generate interactive documentation that includes:

  • Parameter descriptions and types
  • Default values and constraints
  • Example requests and responses
  • Organized endpoint groups
  • Interactive testing interface

Key Improvements

1. Pydantic Models

The API now uses structured Pydantic models instead of raw JSON requests:

class GenerationRequest(BaseModel):
    """Request model for 3D generation API"""
    image: str = Field(
        ..., 
        description="Base64 encoded input image for 3D generation",
        example="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
    )
    texture: bool = Field(
        False,
        description="Whether to generate textures for the 3D model"
    )
    seed: int = Field(
        1234,
        description="Random seed for reproducible generation",
        ge=0,
        le=2**32-1
    )
    # ... more parameters

2. Parameter Documentation

Each parameter includes:

  • Description: What the parameter does
  • Type: Data type (str, int, float, bool, etc.)
  • Constraints: Min/max values, allowed values
  • Default values: What happens if not provided
  • Examples: Sample values for testing

3. API Organization

Endpoints are organized into logical groups using tags:

  • generation: 3D model generation endpoints
  • status: Task status and health check endpoints

4. Comprehensive Metadata

The FastAPI app includes:

  • Title and version
  • Detailed description
  • Contact information
  • License information
  • Feature overview

Available Endpoints

Generation Endpoints

POST /generate

Generate a 3D model from an input image.

Parameters:

  • image (required): Base64 encoded input image
  • remove_background (optional): Auto-remove background (default: true)
  • texture (optional): Generate textures (default: false)
  • seed (optional): Random seed (default: 1234)
  • octree_resolution (optional): Mesh resolution (default: 256)
  • num_inference_steps (optional): Generation steps (default: 5)
  • guidance_scale (optional): Generation guidance (default: 5.0)
  • num_chunks (optional): Processing chunks (default: 8000)
  • face_count (optional): Max faces for textures (default: 40000)
  • type (optional): Output format (default: "glb")

POST /send

Start asynchronous 3D generation task.

Parameters: Same as /generate Returns: Task ID for status tracking

Status Endpoints

GET /health

Check service health status.

GET /status/{uid}

Check task status and retrieve results.

Accessing the Documentation

Interactive Documentation

  1. Start the API server:

    python api_server.py

  2. Open your browser to:

    • Swagger UI: http://localhost:8081/docs
    • ReDoc: http://localhost:8081/redoc

Features of the Interactive Docs

  • Try it out: Test endpoints directly from the browser
  • Parameter validation: Automatic validation of input parameters
  • Response examples: See expected response formats
  • Error handling: Understand possible error responses
  • Authentication: Configure if needed (currently not required)

Example Usage

Basic 3D Generation

import requests
import base64

# Load and encode image
with open("input_image.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

# Prepare request
request_data = {
    "image": image_data,
    "texture": True,
    "seed": 42,
    "type": "glb"
}

# Send request
response = requests.post("http://localhost:8081/generate", json=request_data)

if response.status_code == 200:
    # Save the generated 3D model
    with open("output_model.glb", "wb") as f:
        f.write(response.content)

Asynchronous Generation

# Start async task
response = requests.post("http://localhost:8081/send", json=request_data)
task_id = response.json()["uid"]

# Check status
status_response = requests.get(f"http://localhost:8081/status/{task_id}")
status = status_response.json()

if status["status"] == "completed":
    # Decode and save the model
    model_data = base64.b64decode(status["model_base64"])
    with open("async_model.glb", "wb") as f:
        f.write(model_data)

Testing

Use the provided test script to verify the API:

python test_api_docs.py

This script demonstrates:

  • Parameter validation
  • Request formatting
  • Response handling
  • Error scenarios

Benefits

For Developers

  • Self-documenting API: Parameters are clearly defined
  • Type safety: Automatic validation prevents errors
  • Interactive testing: Try endpoints without writing code
  • Clear examples: See exactly what to send and expect

For Users

  • Easy integration: Clear parameter documentation
  • Error prevention: Validation catches issues early
  • Quick testing: Interactive interface for exploration
  • Comprehensive examples: Working code samples

Technical Details

Dependencies

  • fastapi: Web framework with automatic documentation
  • pydantic: Data validation and serialization
  • uvicorn: ASGI server

File Structure

api_server.py          # Main API server with Pydantic models
test_api_docs.py       # Test script demonstrating usage
API_DOCUMENTATION.md   # This documentation file

Customization

To add new parameters or endpoints:

  1. Add to Pydantic model:

    new_param: str = Field(
    "default_value",
    description="Parameter description"
)

  2. Update endpoint function:

    @app.post("/new_endpoint", tags=["category"])
async def new_endpoint(request: RequestModel):
    """Endpoint description"""
    # Implementation

  3. Documentation updates automatically!

Troubleshooting

Common Issues

  1. Import errors: Ensure all dependencies are installed
  2. Port conflicts: Change port in api_server.py if needed
  3. Model loading: Check model paths and GPU availability

Getting Help

  • Check the interactive documentation at /docs
  • Review the test script for working examples
  • Examine the Pydantic models for parameter details

Conclusion

The enhanced API documentation provides a professional, user-friendly interface for the Hunyuan3D API. Users can now understand all parameters, test endpoints interactively, and integrate the API more easily into their applications.