跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

hy-3d-gen

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

kangarooking · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add kangarooking/kangarooking-skills --skill hy-3d-gen

技能说明


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

腾讯混元生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.pyTokenHub + 腾讯云 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 兼容接口(默认)

export HY3D_OPENAI_API_KEY="你的 TokenHub API key"

也可使用 TENCENT_MAAS_API_KEY 或 TOKENHUB_API_KEY。不要把 key 写进脚本源码。

腾讯云 SDK 后端(可选回退)

Step 1: 开通混元3D服务

🔗 腾讯云3D视觉创作控制台

Step 2: 获取 API 密钥

🔗 腾讯云 API 密钥管理

Step 3: 设置环境变量

Linux / macOS:

export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"

如需持久化:

echo 'export TENCENTCLOUD_SECRET_ID="你的SecretId"' >> ~/.zshrc
echo 'export TENCENTCLOUD_SECRET_KEY="你的SecretKey"' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell):

$env:TENCENTCLOUD_SECRET_ID = "你的SecretId"
$env:TENCENTCLOUD_SECRET_KEY = "你的SecretKey"

⚠️ 安全提示:切勿将密钥硬编码在代码中。

Agent 执行指令(必读)

本节是 Agent(AI 模型)的核心执行规范。当用户请求生成 3D 模型时,Agent 必须严格按照以下步骤执行。依赖安装、持久化环境变量、上传敏感图片或扩大本机环境改动前,需要用户明确确认。

🔑 通用执行规则

  1. 触发条件:用户提供了文本描述或图片,且意图为生成 3D 模型。
  2. 受控执行原则:依赖与凭证已经配置、且用户明确要生成 3D 模型时,Agent 可直接执行脚本;不得自动安装依赖或改写 shell 配置。
  3. 自动选择脚本:默认使用 main.py(一站式),除非用户明确要求分步操作。默认 --provider auto,如果存在 TokenHub key 会优先走 OpenAI 兼容接口。
  4. ⛔ 禁止使用大模型自身能力替代 3D 生成(最高优先级规则):
    • Agent 严禁自行编造 3D 文件 URL 或描述生成结果。
    • 如果调用失败,Agent 必须向用户返回清晰的错误说明。

📌 脚本一:一站式生成 main.py(推荐)

适用场景:用户请求生成 3D 模型,自动提交并等待结果

# 文生3D
python3 <SKILL_DIR>/scripts/main.py --prompt "文本描述"

# 图生3D
python3 <SKILL_DIR>/scripts/main.py --image-url "https://example.com/image.jpg"

# 强制使用 TokenHub OpenAI 兼容接口
python3 <SKILL_DIR>/scripts/main.py --provider tokenhub --model hy-3d-3.0 --prompt "一只小狗"

# 强制使用腾讯云 SDK 回退
python3 <SKILL_DIR>/scripts/main.py --provider tencent --model 3.0 --prompt "一只小狗"

可选参数:

  • --prompt <TEXT>:文本描述,中文推荐,最多 1024 字符(与 image-url/image-base64 二选一)
  • --image-url <URL>:输入图片 URL(与 prompt 二选一)
  • --image-base64 <BASE64>:输入图片 Base64 数据(与 prompt 二选一)
  • --multi-view <JSON>:多视角图片 JSON,如 '[{"ViewType":"back","ViewImageUrl":"https://..."}]'
  • --model <VERSION>:模型版本,默认 hy-3d-3.0,可选 3.0 / 3.1 / hy-3d-3.0 / hy-3d-3.1
  • --enable-pbr:开启 PBR 材质生成
  • --face-count <N>:面数,默认 500000,范围 10000-1500000
  • --generate-type <TYPE>:生成类型:Normal / LowPoly / Geometry / Sketch
  • --polygon-type <TYPE>:多边形类型(仅 LowPoly):triangle / quadrilateral
  • --result-format <FMT>:输出格式:STL / USDZ / FBX(默认 obj+glb)
  • --provider <auto|tokenhub|tencent>:后端选择,默认 auto
  • --no-poll:仅提交任务不等待结果(返回 JobId)

输出示例:

{
  "job_id": "job-xxxxxxxxxxxx",
  "status": "success",
  "result_files": [
    {
      "type": "glb",
      "url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.glb",
      "preview_image_url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.png"
    },
    {
      "type": "obj",
      "url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.obj"
    }
  ]
}

注意:生成的文件 URL 有效期为 24 小时,请及时保存。3D 生成通常需要 1~5 分钟。


📌 脚本二:仅提交任务 submit_job.py

适用场景:仅需提交任务获取 JobId,后续手动查询

python3 <SKILL_DIR>/scripts/submit_job.py --prompt "文本描述"

可选参数:与 main.py 相同(除 --poll-interval、--max-poll-time、--no-poll 外)

输出示例:

{
  "job_id": "job-xxxxxxxxxxxx",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "message": "Task submitted successfully. Use query_job.py to poll for results."
}

📌 脚本三:查询任务 query_job.py

适用场景:根据 JobId 查询任务状态和结果

python3 <SKILL_DIR>/scripts/query_job.py "job-xxxxxxxxxxxx" --model hy-3d-3.0

可选参数:

  • --poll-interval <N>:轮询间隔秒数,默认 10
  • --max-poll-time <N>:最大轮询时间秒数,默认 600(10min)
  • --no-poll:仅查询一次,不轮询
  • --provider <auto|tokenhub|tencent>:后端选择,默认 auto
  • --model <VERSION>:TokenHub 查询需要与提交时一致的模型,默认 hy-3d-3.0

输出示例:

{
  "job_id": "job-xxxxxxxxxxxx",
  "status": "success",
  "result_files": [
    {
      "type": "glb",
      "url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.glb",
      "previe
阅读完整来源 ↗