知式图片生成3D模型

概述

Image to 3D（图片生成 3D 模型 · 多平台自动回退）

功能描述

把一张图片（产品照、概念图、角色立绘、实物照片）变成一个带 PBR 贴图的 3D 模型，输出标准 GLB 文件，可直接导入 Blender / Unity / Unreal，或在网页里用 <model-viewer> 预览。

多平台支持 + 自动回退：内置 4 家云端 3D 生成平台，用户自备各自 Key。默认 --provider auto 会按 Tripo → Meshy → 腾讯混元3D → Hyper3D Rodin 顺序，只用已配置 Key 的平台；当某家余额不足 / 鉴权失败时，自动切到下一家——所以像"Tripo 积分用完"这种情况，只要还配了别的平台 Key，就能无缝继续出模型。

适合：产品 3D 预览、游戏道具快速建模、概念图转资产、电商 3D 展示。

不适合：复杂机械结构、透明/半透明材质、极细结构（头发丝）；近看仍有"AI 感"，通常需人工修模。

前置条件

• 本 Skill 是云端 API 型，用户必须用自己的账号：自己注册、自己付费、自己提供 API Key，本 Skill 不代收任何费用。
• 至少配置一个平台的 Key（环境变量）；配得越多，自动回退的兜底能力越强。获取地址见下表：

若用户尚未注册、或报错 401/403，先引导其到对应控制台获取有效 Key，再重试。

输入图片建议：主体清晰、正面、光线均匀、背景简洁。

工作流程

调用生成脚本（Python 标准库，零额外依赖）：

# 默认自动回退：只跑配了 Key 的平台，谁有额度用谁
python scripts/tripo_image_to_3d.py 
  --image "https://example.com/chair.jpg" 
  --output chair.glb

# 指定单一平台
python scripts/tripo_image_to_3d.py 
  --image "https://example.com/chair.jpg" 
  --output chair.glb 
  --provider meshy --api-key "msk_xxxx"

• --image：公开 URL、本地图片路径、或 data:image/...;base64,... 均可
• --output：输出的 .glb 文件路径（必填）
• --provider：auto（默认）/ tripo / meshy / hunyuan / rodin
• --api-key：仅单一平台模式下用（覆盖该平台 Key）；auto 模式请直接用各平台环境变量
• --texture-quality：standard（默认）或 detailed（Tripo，更精细贴图，多耗积分）
• --face-limit：可选，限制面数（如 50000），做轻量资产时设小
• --quad：可选，四边形拓扑（Tripo/Rodin，更适合游戏绑定）
• --hunyuan-model：3.0（默认）或 3.1（腾讯混元3D 模型版本）

脚本运行结束后：

• stderr 打印进度（当前用哪家平台、轮询状态、回退提示）
• stdout 打印一行 JSON 结果，供你解析：

{"provider": "meshy", "provider_label": "Meshy", "glb": "/abs/path/chair.glb"}

让使用者选择平台（交互指引）

脚本支持 --provider 显式指定平台，因此使用者可以指定用哪一家。Agent 按以下规则处理：

• 使用者未指定时：默认不询问，直接 auto（自动回退，谁有额度用谁，最省心）。
• 使用者有偏好时：按对方要求传 --provider，并尊重其选择（不要擅自改回 auto）。

常见诉求与对应平台：

• 想 免费 / 低成本 → hunyuan（混元3D 有免费档）或 meshy（有免费额度）
• 想 最快出图 → tripo 或 hunyuan
• 想 贴图质感最好 → meshy
• 想 影视级最高质量 → rodin（需已申请 API 权限且 Key 有效）
• 主动询问时机：当使用者明显在意费用 / 质量 / 速度，或某次 auto 回退后仍失败时，

可简短询问「你更想用哪一家？tripo / meshy / 混元3D / rodin，还是默认自动」，再把选择传给 --provider。

示例——使用者指定用混元 3D：

python scripts/tripo_image_to_3d.py 
  --image "https://example.com/chair.jpg" 
  --output chair.glb 
  --provider hunyuan

输出与交付

1. 把 --output 指向的 .glb 文件交给用户，并说明可用 Blender / Unity 打开，或丢进

<model-viewer> 网页直接旋转预览。

1. 若用户要网页预览版，可用 references/tripo-api.md 里的 <model-viewer> 片段包一层 HTML。

接口契约

各平台端点与字段见 references/providers.md（Tripo 详情仍见 references/tripo-api.md）。要点：

限制

• 生成耗时约 30 秒~数分钟（视平台与质量参数），脚本已内置轮询与超时（默认 10 分钟）。
• GLB 下载链接有时效，务必及时落地到本地文件。
• 这是云端 API 型 Skill：用户用自己的账号付费，本 Skill 不代收费用。

若以后想把它做成 SkillHub 付费 Skill（别人调一次你收一次），可套用数字人 Skill 的X402 改造模式（前置检查 / 402 / 重试 / 订单号 / 异常处理）。

• auto 模式下只要至少一家平台有可用 Key 与额度即可出图；全部失败才会退出（exit 1）。

安全须知（必读）

• 各平台密钥只会在创建时显示一次，请立即复制到本地安全存储（密码管理器 / 加密文件），关窗后无法找回。
• 密钥只能存在于服务端环境，切勿写入任何客户端 / 前端 / 网页代码，也不要硬编码进会公开的文件。
  • 本 Skill 通过 --api-key 或环境变量传入，由 Agent 在服务端执行脚本时使用，属合规用法。
  • 若以后接 X402 做成付费 Skill，密钥更应只放在商户后端的环境变量里，前端绝不出现明文 Key。
• 注意鉴权格式差异：Tripo / Meshy / Rodin 用 Authorization: Bearer <KEY>；

而腾讯混元3D 用 Authorization: <sk-xxxx>（sk- 前缀，不是 Bearer）——脚本已自动处理，但你配 Key 时无需手加 sk- 前缀，脚本会识别补齐。

• 官方也提供 Tripo Python SDK（pip install tripo3d）。本 Skill 默认用零依赖标准库实现（无需额外安装）以保证可移植性。