rodin3d-skill

What this skill does

# 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](https://hyper3d.ai/api-dashboard)
2. **Python 3.8+**
3. **Dependencies**: Install via `pip install -r requirements.txt`

### Basic Usage

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
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:

```bash
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

```bash
# 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

```python
from api_client import Hyper3DAPIClient

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

# Generate