核心用法
Hitem3D 是一款面向生产环境的图像转 3D 模型自动化工具，通过 scripts/hitem3d.sh 脚本封装完整的 submit→wait→download 工作流。用户仅需提供单张产品图、概念图、人像照片或多视角图像组，即可生成可下载的 3D 资产。
关键操作模式：
- 单图通用对象：默认使用
hitem3dv2.0模型，1536 分辨率，GLB 格式（约 50 credits） - 人像/胸像生成：切换至
scene-portraitv2.1+ 1536pro，优化面部细节 - 多视角重建：支持 2-4 张不同角度图像，通过 4-bit bitmap（如
1010表示正面+左侧）指定视角组合 - 批量处理：独立任务并行提交，自动汇总成败状态与输出路径
- 3D 打印：优先输出 STL（格式 3），可调高面数至 500k 提升光滑度
- AR 预览：输出 USDZ 格式（5）适配 Apple Quick Look / Vision Pro
完整工作流示例：
# 一键生成（提交→等待→下载） scripts/hitem3d.sh run product.png --model hitem3dv2.0 --resolution 1536 # 多视角高精度重建 scripts/hitem3d.sh run-multi front.png back.png left.png right.png --views 1111 --timeout-seconds 3600 # 批量文件夹处理 scripts/hitem3d.sh batch ./images --glob '*.png' --download-dir ./output/
显著优点
1. 端到端自动化：封装轮询等待、超时处理、下载重试，无需手动管理任务状态
2. 成本透明：内置信用预估机制，批量作业或高消耗任务（>100 credits）强制确认
3. 智能模式推断：根据输入类型自动选择最优模型（人像/通用）、分辨率与格式
4. 多格式原生支持：GLB（Web/展示）、USDZ（Apple AR）、STL（3D 打印）无需后期转换
5. 企业级容错：令牌过期自动刷新、下载 URL 失效自动重查、API 错误码映射为用户友好提示
潜在缺点与局限性
- 成本敏感：高质量输出（1536pro 人像）单任务约 70 credits，批量 30 张可达 2000+ credits
- 前置依赖严格：必须配置
HITEM3D_AK/HITEM3D_SK环境变量，无交互式认证降级方案 - 输入约束：不支持 >20MB 图像，多视角模式强制要求正面视图，否则可能失败
- 异步心智负担：虽封装轮询，超长任务（>1 小时）仍需用户理解
--timeout-seconds调参 - 无实时预览：任务提交后仅返回 ID，无渐进式生成进度可视化
适合人群
- 电商产品经理：快速生成商品 3D 展示资产
- 3D 打印爱好者：从照片直接获取可打印 STL
- AR/VR 开发者：批量生产 USDZ/GLB 内容
- 概念艺术家：将 2D 设计稿转化为可交互 3D 草稿
常规风险
- 密钥泄露：脚本需访问 AK/SK，共享环境变量或日志可能意外暴露凭证
- 信用透支：默认参数成本不低，未确认的大批量作业可能导致账户欠费
- 生成失败不退费盲区：虽文档称错误码
50010001自动退费，但用户难以实时追踪信用变动 - 多视角误用：用户易混淆"批量处理多文件"与"多视角重建单物体"，导致资源浪费