如何调用Modly的/generate/from-image接口？图像转3D生成接口完整示例

如何调用Modly的/generate/from-image接口图像转3D生成接口完整示例【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modlyModly 是一款完全本地运行的 AI 桌面应用可以在你的 GPU 上通过图片生成 3D 模型图像转3D。它的后端是一个本地 FastAPI 服务核心入口就是POST /generate/from-image这个图像转3D生成接口。本文给出该接口的完整调用流程发起生成任务、轮询状态、取消任务直到拿到最终的 3D 模型文件。一、Modly 与它的本地 API 服务Modly 的架构是「Electron 前端 本地 Python API」。应用启动时会自动拉起一个监听127.0.0.1:8765的 FastAPI 服务端口定义见 electron/main/python-bridge.ts所有 AI 推理都发生在这台服务里图片与模型权重不出本机。接口注册在 api/main.py 中生成相关的路由统一挂在/generate前缀下。 如果你想在开发环境下手动启动这个服务只需两步cd api pip install -r requirements.txt uvicorn main:app --host 127.0.0.1 --port 8765 --reload启动后可先访问GET /health做健康检查返回{status: ok}即表示服务就绪实现见 api/routers/status.py。二、/generate/from-image 接口参数一览这是一个multipart/form-data请求参数定义在 api/routers/generation.py#L35-L45字段类型必填默认值说明image文件✅—输入图片Content-Type 必须为image/*model_idForm❌sf3d模型 ID必须在模型注册表中存在collectionForm❌Default输出集合名结果存到 workspace 对应子目录remeshForm❌quad重网格化方式quad/triangle/noneenable_textureForm❌false是否烘焙纹理texture_resolutionForm❌1024纹理分辨率paramsForm❌{}模型专属参数传 JSON 字符串⚠️ 接口会做三项校验文件必须是图片、remesh必须合法、model_id必须存在否则直接返回 400。三、完整示例一条 curl 发起图像转3D任务curl -X POST http://127.0.0.1:8765/generate/from-image \ -F imagecat.jpg;typeimage/jpeg \ -F model_idsf3d \ -F collectionDefault \ -F remeshquad \ -F enable_texturetrue \ -F texture_resolution1024请求成功后立即返回任务 ID这是异步任务模式不会阻塞等待推理完成{ job_id: 3f2c9a1e-8b4d-4f6a-9c1d-7e5b2a8f0c31 }拿到job_id后后面所有的进度查询、取消、结果获取都围绕它进行。四、轮询任务状态/generate/status/{job_id}用job_id轮询状态接口直到status变为done或errorcurl http://127.0.0.1:8765/generate/status/job_id返回结构定义在 api/schemas/generation.py字段如下字段说明statuspending→running→done/error/cancelledprogress0–100 的进度百分比step当前步骤的人类可读描述如 Loading sf3d…output_url生成完成后的 3D 模型文件相对地址error出错时的完整错误堆栈完成时的典型响应{ job_id: 3f2c9a1e-…, status: done, progress: 100, step: Done, output_url: /workspace/Default/2026-08-29-03-12-00.glb } 首次使用某个模型时step会先显示下载/加载进度因为模型权重会在首次生成时自动下载到~/.modly/models/目录。五、取消任务与获取生成的 3D 模型取消任务推理过程中随时可调用实现会立即杀掉推理子进程curl -X POST http://127.0.0.1:8765/generate/cancel/job_id获取结果output_url是相对地址拼上服务地址即可下载模型文件curl -OJ http://127.0.0.1:8765/workspace/Default/2026-08-29-03-12-00.glb如果格式不合适比如 3D 打印需要 STL还可以用内置的转换接口按需转码支持glb / stl / obj / ply见 api/routers/export.pycurl -o model.stl http://127.0.0.1:8765/export/stl?pathDefault/2026-08-29-03-12-00.glb六、常见问题排查400 File must be an image-F上传时没有带图片 Content-Typecurl 记得写;typeimage/jpeg。400 Unknown model IDmodel_id写错了。可先调GET /model/all查看当前可用模型及其显存需求。任务长时间停在 0%大概率在首次下载模型权重属于正常现象耐心等待或检查网络。404 Job not found任务记录在服务端只保留 30 分钟见 api/routers/generation.py#L22超时后会被清理。前端对这套接口的封装可以直接参考 src/shared/hooks/useApi.ts它就是应用内上传图片 → 生成 3D按钮背后的调用逻辑。Modly 还支持工作流编排与模型优化去噪、减面、修复等等能力可继续查看 api/README.md 与 docs/running-on-jetson.md 了解更多部署方式。七、相关源码路径速查接口实现api/routers/generation.py发起 / 状态 / 取消返回结构api/schemas/generation.py服务入口与路由注册api/main.py模型下载与状态api/routers/model.py格式转换导出api/routers/export.py扩展子进程运行器api/runner.py【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考