deemostech/rodin3d-skill

Hyper3D Rodin Gen-2.5 Skill Documentation

Overview

This skill provides a comprehensive integration with the Hyper3D Rodin Gen-2.5 API, enabling developers to generate production-ready 3D models from images or text prompts. The skill handles API authentication, task submission, status polling, and result retrieval with enterprise-grade reliability.

Key Capabilities:

• Image-to-3D reconstruction (up to 5 input images)
• Text-to-3D generation
• Advanced geometry and texture controls
• Multi-format output support (glb, usdz, fbx, obj, stl)
• Asynchronous task management with automatic polling

Quick Start

Prerequisites

1. API Key:
   • Free Test Key: vibecoding (automatically used when no key is provided)
   • Production Key: Obtain from Hyper3D API Dashboard
2. Python 3.8+
3. Dependencies: Install via pip install -r requirements.txt

Basic Usage

# Quick start with free test key (no API key required)
python scripts/generate_3d_model.py \
  --image input.jpg \
  --tier Gen-2.5-Medium \
  --output ./output

# Generate from image with your API key
python scripts/generate_3d_model.py \
  --image input.jpg \
  --tier Gen-2.5-High \
  --geometry-file-format glb \
  --quality medium \
  --output ./output \
  --api-key $HYPER3D_API_KEY

# Generate from text
python scripts/generate_3d_model.py \
  --prompt "A detailed 3D model of a vintage camera" \
  --tier Gen-2.5-Medium \
  --output ./output

Core Concepts

API Endpoints

| Endpoint | Method | Purpose | |----------|--------|---------| | /api/v2/rodin | POST | Submit generation task | | /api/v2/status | POST | Check task status | | /api/v2/download | POST | Retrieve download links |

Task Lifecycle

1. Submit: POST to /api/v2/rodin → Returns subscription_key and task_uuid
2. Poll: POST to /api/v2/status with subscription_key → Check job status
3. Download: POST to /api/v2/download with task_uuid → Get result URLs (expire in 10 minutes)

Parameter Reference

Tier Selection

| Tier | Description | Credit Cost | Recommended Use Case | |------|-------------|-------------|---------------------| | Gen-2.5-Extreme-Low | Rapid generation for simple assets | 0.5 | Prototyping, quick iterations | | Gen-2.5-Low | Clean assets, small hardsurface props | 0.5 | Basic models, low-poly assets | | Gen-2.5-Medium | Balanced structure and detail | 0.5 | Default - general purpose | | Gen-2.5-High | Rich structural representation, smooth surfaces | 0.5 | Production-ready assets | | Gen-2.5-Extreme-High | High-frequency detail reproduction | 1.0 | Premium quality, final renders | | Gen-2 | Legacy tier | 0.5 | Backward compatibility | | Detail/Regular/Smooth/Sketch | Legacy tiers | 0.5 | Deprecated, use Gen-2.5 |

Quality Levels (Face Count)

| Quality | Raw Mode | Quad Mode | Use Case | |---------|----------|-----------|----------| | high | 1M faces | 50k faces | Production, close-ups | | medium | 500k faces | 18k faces | Default - balanced | | low | 60k faces | 8k faces | Real-time applications | | extra-low | 20k faces | 4k faces | Mobile, VR/AR |

Material Types

| Material | Description | |----------|-------------| | PBR | Physically Based Rendering (base color, metallic, normal, roughness maps) | | Shaded | Base color texture with baked lighting | | All | Both PBR and Shaded materials | | None | Geometry only, no materials |

Gen-2.5 Exclusive Features

| Parameter | Type | Description | Default | |-----------|------|-------------|---------| | hd_texture | bool | Enable 4K texture generation | false | | texture_delight | bool | Enhance texture quality and detail | false | | texture_mode | string | Advanced texture generation mode | None | | is_micro | bool | Optimize for micro-scale objects | false | | geometry_instruct_mode | string | Geometry generation guidance | faithful |

Mesh Mode Comparison

| Mode | Description | Recommended For | |------|-------------|----------------| | Raw | Triangle mesh, maximum detail preservation | Gen-2.5 tiers | | Quad | Quadrilateral mesh, cleaner topology | Legacy tiers |

Addons

| Addon | Cost | Description | |-------|------|-------------| | HighPack | +1 credit | 4K texture resolution upgrade |

Command Line Interface

Required Arguments

# Image input (required for Image-to-3D)
--image path/to/image1.jpg [path/to/image2.jpg ...]

# OR Text input (required for Text-to-3D)
--prompt "Your text description"

Optional Arguments

# Core settings
--tier Gen-2.5-Medium              # Generation tier
--geometry-file-format glb          # Output format: glb, usdz, fbx, obj, stl
--quality medium                    # Face count: high, medium, low, extra-low
--material PBR                      # Material type: PBR, Shaded, All

# Advanced geometry
--mesh-mode Raw                     # Raw or Quad
--quality-override 500000          # Custom polygon count
--bbox-condition 100 100 100       # Bounding box [Width, Height, Length]
--tapose                           # Generate T/A pose for humanoids

# Texture enhancements (Gen-2.5)
--hd-texture                       # Enable HD textures
--texture-delight                  # Enhance texture quality
--texture-mode <mode>              # Advanced texture mode

# Object properties (Gen-2.5)
--is-micro                         # Micro-scale optimization

# Generation control
--seed 12345                       # Random seed (0-65535)
--geometry-instruct-mode faithful  # Geometry guidance mode

# Output options
--preview-render                   # Generate preview image
--addons HighPack                  # Additional features
--output ./output                  # Download directory
--api-key $HYPER3D_API_KEY         # Authentication

# Polling configuration
--poll-interval 10                 # Status check interval (seconds)
--max-retries 60                   # Maximum polling attempts

Usage Recipes

Recipe 1: Production-Quality Asset

python scripts/generate_3d_model.py \
  --image product.jpg \
  --tier Gen-2.5-High \
  --geometry-file-format glb \
  --quality high \
  --material PBR \
  --mesh-mode Raw \
  --hd-texture \
  --texture-delight \
  --addons HighPack \
  --output ./production

Recipe 2: Rapid Prototyping

python scripts/generate_3d_model.py \
  --prompt "A futuristic smartphone" \
  --tier Gen-2.5-Extreme-Low \
  --geometry-file-format glb \
  --quality low \
  --output ./prototypes

Recipe 3: Fast Generation Mode

Fast generation mode is triggered by a specific combination of parameters optimized for speed:

python scripts/generate_3d_model.py \
  --image product.jpg \
  --tier Gen-2.5-Low \
  --material Shaded \
  --mesh-mode Raw \
  --quality-override 20000 \
  --texture-mode low \
  --output ./quick-preview

Fast Mode Parameters:

| Parameter | Value | Description | |-----------|-------|-------------| | tier | Gen-2.5-Low | Use low tier for faster generation | | material | Shaded | Simplified material output | | mesh_mode | Raw | Triangle mesh for faster processing | | quality_override | 20000 | Reduced polygon count | | texture_mode | low | Low resolution textures |

Trigger Condition: Fast mode is automatically activated when all of the above parameters are set together. This combination provides the quickest generation time for rapid prototyping and preview purposes.

Recipe 4: Batch Processing Workflow

# Process multiple images sequentially
for img in ./input/*.jpg; do
  python scripts/generate_3d_model.py \
    --image "$img" \
    --tier Gen-2.5-Medium \
    --output ./output/$(basename "$img" .jpg)
done

Python API Integration

Basic Client Usage

from api_client import Hyper3DAPIClient

# Initialize client
client = Hyper3DAPIClient(api_key="your_api_key")

# Generate from image
task_uuid, result = client.generate_3d_model(
    images=["input.jpg"],
    tier="Gen-2.5-High",
    geometry_file_format="glb",
    quality="high",
    material="PBR",
    mesh_mode="Raw",
    hd_texture=True,
    texture_delight=True,
    poll_interval=15,
    max_retries=40
)

# Process results
print(f"Task completed: {task_uuid}")
for file_info in result.get("list", []):
    print(f"File: {file_info['name']} - URL: {file_info['url']}")

Advanced Configuration

from api_client import Hyper3DAPIClient

client = Hyper3DAPIClient(api_key="your_api_key")

# Custom generation with all parameters
task_uuid, result = client.generate_3d_model(
    images=["front.jpg", "side.jpg", "top.jpg"],
    prompt="A vintage pocket watch with intricate details",
    tier="Gen-2.5-Extreme-High",
    geometry_file_format="fbx",
    quality="high",
    material="All",
    mesh_mode="Raw",
    use_original_alpha=True,
    seed=42,
    TAPose=False,
    bbox_condition=[100, 100, 50],
    addons=["HighPack"],
    preview_render=True,
    hd_texture=True,
    texture_delight=True,
    is_micro=False,

    geometry_instruct_mode="faithful"
)

Manual Task Management

# Submit task
submit_result = client.submit_generation_task(
    images=["input.jpg"],
    tier="Gen-2.5-Medium"
)

subscription_key = submit_result["jobs"]["subscription_key"]
task_uuid = submit_result["uuid"]

# Manual polling
import time
for _ in range(60):
    status = client.check_task_status(subscription_key)
    jobs = status.get("jobs", [])
    
    if all(job["status"] == "Done" for job in jobs):
        break
    elif any(job["status"] == "Failed" for job in jobs):
        raise Exception("Task failed")
    
    time.sleep(10)

# Get download links
download_result = client.download_results(task_uuid)

Error Handling & Troubleshooting

Common Error Codes

| Error | Cause | Resolution | |-------|-------|------------| | Not authenticated | Invalid or missing API key | Verify HYPER3D_API_KEY is set correctly | | INSUFFICIENT_FUND | Insufficient credits | Add funds via Hyper3D dashboard | | Invalid tier | Unknown tier value | Use valid Gen-2.5 tier (see Tier Selection) | | Invalid image | Image format/size error | Use JPEG/PNG/WebP, max 16MB, 512x512-4096x4096 | | Timeout | Generation took too long | Increase --max-retries, check API status |

Best Practices

1. Validate Inputs: Use ImageUtils.validate_image() before submission
2. Handle Rate Limits: Implement exponential backoff for retries
3. Store Results: Download models immediately - URLs expire in 10 minutes
4. Log Everything: Track task UUIDs and status for debugging
5. Use Appropriate Tier: Match tier to use case to optimize cost/quality

Debug Mode

# Enable verbose output
python scripts/generate_3d_model.py \
  --image input.jpg \
  --tier Gen-2.5-Medium \
  --output ./output \
  --api-key $HYPER3D_API_KEY 2>&1 | tee generation.log

Performance Optimization

Speed vs Quality Tradeoffs

| Scenario | Recommended Settings | |----------|---------------------| | Fast iteration | Gen-2.5-Extreme-Low, quality=extra-low | | Preview renders | Gen-2.5-Low, quality=low | | Production assets | Gen-2.5-High, quality=high, hd_texture | | Archival quality | Gen-2.5-Extreme-High, quality=high, HighPack |

Batch Processing Tips

• Process sequentially to avoid API rate limits
• Use consistent seeds for reproducibility
• Parallelize across multiple API keys if available

API Key Management

API Key Priority

The skill uses API keys in the following priority order:

1. Command Line: --api-key argument (highest priority)
2. Environment Variable: HYPER3D_API_KEY
3. Free Test Key: vibecoding (automatically used when no key is provided)

Free Test Key

A free test API key (vibecoding) is built-in for evaluation purposes:

• Usage: Automatically used when no API key is specified
• Limitations: Has usage restrictions and rate limits
• Recommendation: Use for testing only; obtain a production key for regular use

Production Key Setup

1. Obtain Key: Visit Hyper3D API Dashboard
2. Set Environment Variable:

   export HYPER3D_API_KEY="your_production_key_here"
   

3. Persistent Storage (recommended):

   echo 'HYPER3D_API_KEY=your_production_key_here' >> ~/.bashrc
   source ~/.bashrc
   

Security Considerations

1. API Key Protection: Never commit keys to version control
2. Environment Variables: Use HYPER3D_API_KEY environment variable for production
3. HTTPS Only: All API communications use TLS 1.2+
4. Input Sanitization: Validate image paths before processing
5. Free Key Limitations: The built-in test key has usage limits; use production keys for critical workflows

Version Compatibility

| Skill Version | API Version | Notes | |---------------|-------------|-------| | 2.0.0 | Gen-2.5 | Full Gen-2.5 feature support | | 1.0.0 | Gen-2 | Legacy support maintained |

Support & Resources

• API Documentation: developer.hyper3d.ai/api-specification/rodin-gen2.5
• Dashboard: hyper3d.ai/api-dashboard
• Support: [email protected]

Changelog

v2.1.0 (Fast Generation Mode)

• Added documentation for Fast Generation Mode with specific parameter combinations

v2.0.0 (Gen-2.5 Upgrade)

• Added Gen-2.5 tier support (Extreme-Low, Low, Medium, High, Extreme-High)
• Added HD texture generation (--hd-texture)
• Added texture delight enhancement (--texture-delight)
• Added micro-object optimization (--is-micro)
• Added geometry instruction mode (--geometry-instruct-mode)
• Updated default tier to Gen-2.5-Medium
• Updated default mesh mode to Raw
• Enhanced error handling and logging

v1.0.0

• Initial release with Gen-2 API support
• Image-to-3D and Text-to-3D generation
• Basic tier selection (Gen-2, Detail, Regular, Smooth, Sketch)