# Hy 3d Gen

输入文字或图片，通过腾讯混元生3D TokenHub/OpenAI 兼容接口或腾讯云 SDK...

- Repository: https://github.com/kangarooking/kangarooking-skills (694 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-09-07
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add kangarooking/kangarooking-skills --skill hy-3d-gen -g -a claude-code -y`
Codex: `npx skills add kangarooking/kangarooking-skills --skill hy-3d-gen -g -a codex -y`
Cursor: `npx skills add kangarooking/kangarooking-skills --skill hy-3d-gen -g -a cursor -y`
Gemini CLI: `npx skills add kangarooking/kangarooking-skills --skill hy-3d-gen -g -a gemini-cli -y`

## Description

输入文字或图片，通过腾讯混元生3D TokenHub/OpenAI 兼容接口或腾讯云 SDK 生成3D模型。支持文生3D、图生3D、多视图生3D、PBR、白模、草图生3D、智能拓扑生3D；当用户要求生成或查询混元3D模型时使用。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 腾讯混元生3D Skill

本版本基于 ClawHub `@neck-cn/hy-3d-generation` 的本地安装副本改造，发布名为 `hy-3d-gen`。主要改造点是默认走 TokenHub/OpenAI 兼容 HTTP 接口，并保留腾讯云 SDK 作为显式回退后端。

## 本地 Codex 安全说明

此安装副本已做安全化处理：脚本不会自动执行 `pip install`。默认优先使用 TokenHub 的 OpenAI 兼容 HTTP 接口，使用 Python 标准库发起请求，不需要额外依赖；如显式使用 `--provider tencent`，缺少 `tencentcloud-sdk-python` 时脚本会退出并提示用户先在明确选择的 Python 环境中手动安装。生成任务会把 prompt、图片 URL 或 Base64 图片数据发送到腾讯混元生3D接口。

本地测试凭证可放在 skill 根目录的 `.env` 文件中，权限应为 `600`。脚本只会读取 `HY3D_OPENAI_API_KEY`、`TENCENT_MAAS_API_KEY`、`TOKENHUB_API_KEY`、`TENCENTCLOUD_SECRET_ID`、`TENCENTCLOUD_SECRET_KEY`、`TENCENTCLOUD_TOKEN`，并且不会覆盖进程中已经存在的同名环境变量。

## 功能描述

本 Skill 提供**混元生3D**能力，基于腾讯混元大模型，将文本描述或图片智能生成 3D 模型。默认使用 TokenHub OpenAI 兼容协议，可手动回退腾讯云 SDK。支持多视角图片输入、PBR 材质、自定义面数、多种输出格式。

| 场景 | 脚本 | 说明 |
|------|------|------|
| 一站式生成 | `main.py` | 提交任务 + 自动轮询，推荐使用 |
| 仅提交任务 | `submit_job.py` | 仅提交，返回 JobId |
| 仅查询任务 | `query_job.py` | 根据 JobId 查询/轮询结果 |
| 共享客户端 | `hy3d_api.py` | TokenHub + 腾讯云 SDK 双后端封装，不直接手动运行 |

### 🎯 选择规则

```
用户要求生成3D模型  →  main.py（一站式，最简单推荐）
用户要求提交后自行查询  →  submit_job.py + query_job.py（分步操作）
用户已有 JobId 要查结果  →  query_job.py（单独查询）
```

> 如果用户未指定使用哪种模式，Agent 应默认使用 `main.py` 一站式脚本。

### 支持特性

- **文生3D**：支持文本描述生成 3D 模型（最多 1024 字符）
- **图生3D**：支持输入图片 URL 或 Base64 生成 3D 模型
- **多视角图片**：支持 left/right/back/top/bottom/left_front/right_front 多视角输入
- **PBR 材质**：支持开启 PBR 材质生成
- **自定义面数**：支持 10000-1500000 面数范围
- **多种生成类型**：Normal（带纹理）、LowPoly（智能拓扑）、Geometry（白模）、Sketch（草图生成）
- **多种输出格式**：默认 obj+glb，可选 STL、USDZ、FBX
- **模型版本选择**：支持 3.0 和 3.1 版本
- **OpenAI 兼容接口**：优先使用 TokenHub `https://tokenhub.tencentmaas.com/v1/api/3d/submit` 与 `/query`
- **双后端选择**：`--provider auto` 默认优先 TokenHub；`--provider tokenhub` 强制 TokenHub；`--provider tencent` 强制腾讯云 SDK
- **显式安装依赖**：TokenHub 后端无需额外依赖；腾讯云 SDK 后端需要用户在明确选择的 Python 环境中安装所需 SDK
- **智能凭证检测**：优先从环境变量获取密钥，未配置时提示用户开通

## 环境配置指引

### 密钥配置

本 Skill 默认需要 TokenHub OpenAI 兼容 API key；腾讯云 SDK 后端需要腾讯云 API 密钥。

#### TokenHub / OpenAI 兼容接口（默认）

The rest: https://github.com/kangarooking/kangarooking-skills/blob/HEAD/hy-3d-gen/SKILL.md