Converts input images or prompt to 3D models using Hyper3D Rodin Gen-2 API. Use this skill when users want to generate 3D models from images or text, such as product designs, architectural elements, or object reconstructions.

version
1.0.0
GitHub stars
20

Install

/plugin install rodin3d-skill@rodin3d-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add DeemosTech/rodin3d-skills.

Contents

Discovered from source

Skills 1

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

EndpointMethodPurpose
/api/v2/rodinPOSTSubmit generation task
/api/v2/statusPOSTCheck task status
/api/v2/downloadPOSTRetrieve 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

TierDescriptionCredit CostRecommended Use Case
Gen-2.5-Extreme-LowRapid generation for simple assets0.5Prototyping, quick iterations
Gen-2.5-LowClean assets, small hardsurface props0.5Basic models, low-poly assets
Gen-2.5-MediumBalanced structure and detail0.5Default - general purpose
Gen-2.5-HighRich structural representation, smooth surfaces0.5Production-ready assets
Gen-2.5-Extreme-HighHigh-frequency detail reproduction1.0Premium quality, final renders
Gen-2Legacy tier0.5Backward compatibility
Detail/Regular/Smooth/SketchLegacy tiers0.5Deprecated, use Gen-2.5

Quality Levels (Face Count)

QualityRaw ModeQuad ModeUse Case
high1M faces50k facesProduction, close-ups
medium500k faces18k facesDefault - balanced
low60k faces8k facesReal-time applications
extra-low20k faces4k facesMobile, VR/AR

Material Types

MaterialDescription
PBRPhysically Based Rendering (base color, metallic, normal, roughness maps)
ShadedBase color texture with baked lighting
AllBoth PBR and Shaded materials
NoneGeometry only, no materials

Gen-2.5 Exclusive Features

ParameterTypeDescriptionDefault
hd_textureboolEnable 4K texture generationfalse
texture_delightboolEnhance texture quality and detailfalse
texture_modestringAdvanced texture generation modeNone
is_microboolOptimize for micro-scale objectsfalse
geometry_instruct_modestringGeometry generation guidancefaithful

Mesh Mode Comparison

ModeDescriptionRecommended For
RawTriangle mesh, maximum detail preservationGen-2.5 tiers
QuadQuadrilateral mesh, cleaner topologyLegacy tiers

Addons

AddonCostDescription
HighPack+1 credit4K 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:

ParameterValueDescription
tierGen-2.5-LowUse low tier for faster generation
materialShadedSimplified material output
mesh_modeRawTriangle mesh for faster processing
quality_override20000Reduced polygon count
texture_modelowLow 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

ErrorCauseResolution
Not authenticatedInvalid or missing API keyVerify HYPER3D_API_KEY is set correctly
INSUFFICIENT_FUNDInsufficient creditsAdd funds via Hyper3D dashboard
Invalid tierUnknown tier valueUse valid Gen-2.5 tier (see Tier Selection)
Invalid imageImage format/size errorUse JPEG/PNG/WebP, max 16MB, 512x512-4096x4096
TimeoutGeneration took too longIncrease --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

ScenarioRecommended Settings
Fast iterationGen-2.5-Extreme-Low, quality=extra-low
Preview rendersGen-2.5-Low, quality=low
Production assetsGen-2.5-High, quality=high, hd_texture
Archival qualityGen-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 VersionAPI VersionNotes
2.0.0Gen-2.5Full Gen-2.5 feature support
1.0.0Gen-2Legacy support maintained

Support & Resources

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)

Sponsors

Details

Marketplace
DeemosTech/rodin3d-skills
Source
skills/rodin3d-skill
Author
Deemos Hyper3D
Category
3d Generation
License
MIT
Keywords
3d, 3d-model, image-to-3d, text-to-3d, hyper3d, rodin, api, generation