3DCellForge 开发者扩展指南5 步接入你自己的 Image-to-3D 提供商【免费下载链接】3DCellForgeAI-powered interactive 3D model generation, inspection, and presentation studio.项目地址: https://gitcode.com/gh_mirrors/3d/3DCellForge3DCellForge 是一个 AI 驱动的交互式 3D 模型生成与展示工作台上传一张参考图它就能调用 Image-to-3D 云服务把图片变成可旋转、可检查、可导出的 GLB 模型。目前它已内置 Hyper3D Rodin、Tripo、Fal.ai、Hunyuan3D 四个生成提供商。如果你想接入自己的模型生成服务自建推理服务、公司内部的 Image-to-3D 平台等只需理解它清晰的 Provider 插件架构——本文带你用 5 步完成接入全程几乎没有前端改动。一、先看懂架构一个提供商就是一个模块整个生成后端只有一个入口 server.mjs它通过两个调度函数把请求分发给具体的提供商createGenerationTask(provider, payload) # 创建生成任务 getGenerationTask(provider, taskId) # 轮询任务状态每个提供商都是 server/providers/ 下独立的一个文件并统一导出 3 个函数函数作用createXxxTask(payload)把图片提交给你的生成服务返回任务 IDgetXxxTask(taskId)查询任务进度成功后返回 GLB 地址getXxxHealth()健康检查用于/api/3d/health接口参考实现可以看 server/providers/hunyuan.mjs它是最简单的一个本地服务 两个 HTTP 端点非常适合照抄。二、第 1 步复制模板新建你的提供商模块在 server/providers/ 目录下新建mystudio.mjs模块名即提供商 ID。任务生命周期只有两个阶段你的服务需要能支持创建任务和查询状态两次调用。三、第 2 步实现三个导出函数以 server/providers/hunyuan.mjs 为模板核心逻辑如下概念示意非完整代码createMystudioTask(payload)payload.imageDataUrl是前端传来的图片 Data URL用parseDataUrl()解出二进制后 POST 给你的服务从响应里取出task_id返回{ provider: mystudio, taskId, status: queued, modelUrl: , raw }getMystudioTask(taskId)GET 你的状态接口把原始状态归一化为queued / running / success / failed四种之一参考 normalizeHunyuanStatus成功时通过findModelUrl()提取 GLB 地址并返回。getMystudioHealth()返回{ configured: Boolean(你的密钥) }即可前端用它判断提供商是否可用。两个实用技巧模型本地缓存成功后调用 server/model-store.mjs 中的saveLocalModel()/cacheRemoteModel()把 GLB 缓存到.generated-models/后续访问直接走本地不再消耗你的 API 配额参考 getTripoTask 的缓存逻辑。状态轮询间隔是前端固定的 3.5 秒超时 8 分钟配置在 src/config/appConfig.js无需改动。四、第 3 步在入口注册你的提供商打开 server.mjs做两处最小改动顶部 import 你模块里的三个函数在createGenerationTask()和getGenerationTask()两个函数里各加一行provider mystudio的分发判断。同时把你新提供商的健康检查挂进/api/3d/health的providers对象server.mjs#L36-L49方便前端诊断。五、第 4 步配置环境变量 前端选项密钥放后端。复制 .env.example 为.env.local添加你的密钥变量然后在 server/config.mjs 中导出对应的MYSTUDIO_API_KEY、MYSTUDIO_API_BASE等常量。密钥由 loadLocalEnv() 自动加载永远不会进入前端打包产物。前端加一个选项。在 src/config/appConfig.js 的GENERATION_PROVIDER_OPTIONS和GENERATION_MODE_OPTIONS数组里各加一项{ id: mystudio, label: MyStudio, description: ... }上传面板会自动出现你的提供商。前端调用链src/services/modelApi.js 的create3dGeneration()和waitFor3dModel()完全按provider字符串透传零改动即可工作。六、第 5 步启动并验证npm run dev:api # 启动后端默认 http://127.0.0.1:8787 npm run dev # 启动前端验证清单访问http://127.0.0.1:8787/api/3d/health确认providers.mystudio.configured为true前端 New Upload 中选择MyStudio上传一张参考图左侧 Generation Queue 应显示queued → running → success成功后模型出现在模型库中刷新页面仍可加载IndexedDB 持久化用 npm run test 和npm run test:visual跑一遍回归测试确保新选项没有破坏现有布局。常见问题Q不想走云端可以接纯本地服务吗可以。Hunyuan3D 就是本地模式你的服务只要能响应创建 查状态两个端点甚至直接返回 base64 GLB就能按 hunyuan.mjs 的方式接入。QAuto 模式会用到我的提供商吗Auto 的降级链是rodin → tripo → fal → hunyuan → cinematic见 getProviderPlan。想让 Auto 兜底到你的服务在该函数里把mystudio插入队列即可。Q如何排查任务失败后端每次请求都会写结构化日志/api/3d/logs可查看最近 100 条日志落在.logs/目录由 server/logger.mjs 管理error.detail里会保留你服务返回的原始响应。总结接入一个新 Image-to-3D 提供商 1 个新模块 入口 2 行分发 1 行环境配置 2 行前端选项。得益于 3DCellForge 的 Provider 插件架构你的自定义服务会和 Tripo、Fal 一样享受本地 GLB 缓存、任务队列、健康检查和持久化模型库等全套能力。动手试试吧 【免费下载链接】3DCellForgeAI-powered interactive 3D model generation, inspection, and presentation studio.项目地址: https://gitcode.com/gh_mirrors/3d/3DCellForge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
