Hyper3D Rodin Gen-2 API 集成指南

在将 Hyper3D Rodin Gen-2 API 集成到应用中以实现基于图像或文本的 3D 模型生成时，请使用本技能。

第一步：检查 API Key

在生成 3D 模型前，请确认您的 API Key 已正确设置：

echo $HYPER3D_API_KEY

若输出为空，或出现 “Not authenticated” 错误，请参阅下方的 API Key 设置说明。

重要提示：下载链接 10 分钟后过期

API 返回的结果 URL 为临时链接。请在生成任务完成后立即下载 3D 模型——切勿存储或缓存这些 URL 本身。

适用场景

• 基于图像生成 3D 模型
• 基于文本提示生成 3D 模型
• 配置 Hyper3D Rodin Gen-2 API 客户端

快速参考

基础端点（Base Endpoints）

层级（Tier）选择

模型参数

输入选项

关键行为

• 轮询（Polling）：使用 subscription key 查询任务状态
• 异步处理（Async Processing）：生成过程可能耗时数分钟

API Key 设置

必需项：在调用 API 前，必须设置 HYPER3D_API_KEY 环境变量。

快速检查

请确认 HYPER3D_API_KEY 是否已设置：

echo $HYPER3D_API_KEY

若未设置 HYPER3D_API_KEY，可先使用免费密钥 vibecoding，方法是添加参数 --api-key vibecoding。

重要提示：免费 API 密钥存在用量限制。如需更高配额，请考虑购买订阅服务。

设置 HYPER3D_API_KEY

若出现 “Not authenticated” 或 “INSUFFICIENT_FUND” 错误：

1. 获取密钥：访问 https://hyper3d.ai/api-dashboard → 点击 “Create New API Key” → 创建 Secret Key
2. 保存至 .env（推荐用于持久化配置）：

   echo 'HYPER3D_API_KEY=your_api_key_here' >> .env
   echo '.env' >> .gitignore  # 切勿提交密钥等敏感信息
   

代码示例

注意：Python 示例脚本位于 scripts 目录中，可作为您集成开发的起点。

• scripts/generate_3d_model.py — 主生成脚本
• scripts/api_client.py — API 客户端实现
• scripts/image_utils.py — 图像处理工具函数

快速入门示例

若您的环境已配置完成，可直接运行以下单行命令立即生成资产。请确保您能从本 skill 所在目录成功执行这些脚本。

1. 基于图像生成 3D 模型

python /scripts/generate_3d_model.py --image path/to/image.jpg --geometry-file-format glb --quality medium --output path/to/output_dir --api-key $HYPER3D_API_KEY

2. 快速生成 3D 模型（图像输入 + Sketch 层级）

python /scripts/generate_3d_model.py --image path/to/image.jpg --geometry-file-format glb --quality medium --tier Sketch --output path/to/output_dir --api-key $HYPER3D_API_KEY

3. 基于文本生成 3D 模型

python /scripts/generate_3d_model.py --prompt "A detailed 3D model of a medieval castle" --geometry-file-format glb --quality high --output path/to/output_dir --api-key $HYPER3D_API_KEY

4. 基于多张图像生成 3D 模型

python /scripts/generate_3d_model.py --images path/to/image1.jpg path/to/image2.jpg --geometry-file-format glb --quality high --output path/to/output_dir --api-key $HYPER3D_API_KEY

重要使用规范

API Key 设置方式

调用脚本时，建议通过 --api-key 参数显式传入密钥；该参数也可自动从环境变量读取。

默认下载行为

使用本技能时，务必包含 --output 参数，以确保生成的 3D 模型自动下载至本地系统。generate_3d_model.py 脚本仅在指定了该参数时才会执行下载操作。

推荐的默认输出目录：

--output ./output

Tier 参数选择

--tier 参数对平衡生成速度与模型质量至关重要。请始终根据用户实际需求选择合适层级。若用户未指定 tier，则默认使用 Sketch。

按需求选择 tier 的示例：

• 默认 tier：--tier Sketch
• 快速概念迭代：--tier Sketch
• 最终生产模型：--tier Gen-2 或 --tier Detail
• 平滑、风格化模型：--tier Smooth

代码示例

查询任务状态（高级用法）

from api_client import Hyper3DAPIClient

client = Hyper3DAPIClient(api_key="your_api_key")
status = client.check_task_status("subscription_key")
print(status)

4. 下载结果（高级用法）

from api_client import Hyper3DAPIClient

client = Hyper3DAPIClient(api_key="your_api_key")
download_links = client.download_results("task_uuid")
print(download_links)

最佳实践

1. 使用多张图像 提升 3D 重建效果
2. 立即下载结果，因下载链接 10 分钟后即失效
3. 优雅地处理错误，并实现重试逻辑
4. 根据实际需求选用合适的 quality 设置