# Spawn Workshop **Repository Path**: sqdaxiang/spawn-workshop ## Basic Information - **Project Name**: Spawn Workshop - **Description**: No description available - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-06-20 - **Last Updated**: 2025-06-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 生成工坊 - 项目文档 ## 目录 - 项目简介 - 技术架构 - 项目特点 - 项目结构 - 环境搭建 - 后端环境配置 - 前端环境配置 - 服务启动 - API 接口说明 - 图片生成接口 - 图片风格转换接口 - 3D 模型生成接口 - 图片转 3D 模型接口 - 使用示例 - 生成图片 - 转换图片风格 - 生成 3D 模型 - 图片转 3D 模型 - 常见问题 ## 项目简介 生成工坊是一个集成多模态内容生成的应用平台，通过 Python 后端与微信小程序前端的协同，实现了图片生成、图片风格转换和 3D 模型生成等功能。平台通过调用专业 API 服务，为用户提供便捷的内容创作工具，适用于创意设计、数字艺术、教育展示等多种场景，解决平时用户找图片难、图片质量不行和3D模型不会设计等问题。 ## 技术架构 ### 后端 - **框架**：FastAPI（高性能 Python Web 框架，支持异步处理和自动 API 文档生成） - **依赖管理**：conda/pip（支持环境隔离和依赖版本控制） - API 集成 - 图片生成：硅基流动 API（支持文本生成高质量图片） - 3D 模型生成：Meshy API（支持文本 / 图片生成 3D 模型，包含多种艺术风格） ### 前端 - **框架**：微信小程序（原生开发，支持跨设备运行） - **开发语言**：WXML（页面结构）/WXSS（样式）/JavaScript（逻辑） - **UI 设计**：组件化设计，支持响应式布局和交互反馈 ## 项目特点 - **多模态生成**：支持文本生成图片、图片风格转换、文本 / 图片生成 3D 模型 - **高质量输出**：集成专业 API，生成效果达到行业标准 - **用户友好**：简洁的微信小程序界面，降低使用门槛 - **灵活配置**：支持参数调整（如生成步数、引导强度等），满足不同场景需求 - **任务追踪**：支持 3D 模型生成任务的进度查询和结果获取 ## 项目结构 ```plaintext backend/ # 后端服务目录 ├── main.py # 主应用入口，包含所有API接口 ├── requirements.txt # 依赖包列表 └── .env # 环境变量配置文件 frontend/ # 微信小程序前端目录 ├── cloudfunctions # 云函数 ├── images # 素材存放 ├── pages/ # 页面目录 │ ├── home/ # 首页 │ ├── result/ # 图片结果页 │ ├── result3d/ # 3D模型结果页 │ └── me/ # 登录和作品展示页面 ├── utils/ # 工具函数（如请求封装、数据处理） ├── app.js # 小程序入口文件 ├── app.json # 小程序配置文件 └── project.config.json # 项目开发配置文件 ``` ## 环境搭建 ### 后端环境配置 #### 1. 创建并激活 conda 环境 ```bash # 创建Python 3.9环境（推荐使用3.8+版本） conda create -n generate-env python=3.9 # 激活环境 conda activate generate-env ``` #### 2. 安装依赖 ```bash # 方法一：通过requirements.txt安装所有依赖 pip install -r backend/requirements.txt # 方法二：手动安装核心依赖（适用于按需安装） pip install fastapi uvicorn python-dotenv requests python-multipart pydantic ``` #### 3. 配置环境变量 在`backend/`目录下创建`.env`文件，填入以下内容： ```env # 图片生成API配置（硅基流动） API_KEY=你的图片生成API密钥 API_URL=https://api.siliconflow.cn/v1/images/generations # 3D模型生成API配置（Meshy） MESHY_API_KEY=你的3D模型生成API密钥 MESHY_API_URL=https://api.meshy.ai/openapi/v2/text-to-3d ``` ### 前端环境配置 #### 1. 安装微信开发者工具 - 下载地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html - 支持平台：Windows/macOS #### 2. 导入项目 1. 打开微信开发者工具，点击 "导入项目" 2. 选择`frontend/`目录 3. 填写小程序 AppID（可在[微信公众平台](https://mp.weixin.qq.com/)注册申请） #### 3. 修改配置 修改`pages/home/home.js`中的 API 地址为后端服务地址： ```javascript baseUrl: 'http://127.0.0.1:1189' // 改为你的后端服务IP和端口 ``` 修改`pages/result3d/result3d.js`中的 API 地址为后端服务地址： ```javascript url: `http://127.0.0.1:1189/text-to-3d/${this.data.taskId}` // 改为你的后端服务IP和端口 ``` 修改`app.js`中云开发的环境ID（新人使用微信小程序开发可以有一个月的免费使用，需要云开发控制台的数据库创建spanWorkshop结合和部署对应云函数） ``` wx.cloud.init({ env: "yourID", // 改为你的云开发的环境ID traceUser: true }) ``` 修改`project.config.json`中修改成你自己的微信小程序AppID ``` "appid": "yourAppID", // 改为你自己的微信小程序AppID ``` ## 服务启动 ### 启动后端服务 ```bash # 进入后端目录 cd backend # 启动服务（含热重载，修改代码后自动重启） uvicorn main:app --reload --port 1189 ``` - 启动成功后，访问 http://127.0.0.1:1189/docs 查看自动生成的 API 文档 - 热重载功能支持代码修改后自动重启服务，无需手动重启 ## API 接口说明 ### 1. 图片生成接口：POST /generate-image 根据文本描述生成图片。 #### 请求参数 | 参数名 | 类型 | 必填 | 默认值 | 说明 | | ------------------- | ------ | ---- | ---------- | ------------------------------------------------------------ | | prompt | string | 是 | - | 图片描述文本，越详细生成效果越精准（如："一片金色麦田，夕阳下有风车"） | | image_size | string | 否 | 1024x1024 | 图片尺寸，可选值：1024x1024, 960x1280, 768x1024, 720x1440, 720x1280 | | num_inference_steps | int | 否 | 20 | 推理步数，范围：1-100（步数越多效果越精细，耗时越长） | | guidance_scale | float | 否 | 7.5 | 引导强度，范围：0-20（值越高越贴近 prompt 描述） | | negative_prompt | string | 否 | "" | 负面提示词，不希望出现的元素（如："模糊，失真"） | | seed | int | 否 | 4999999999 | 随机种子，相同种子可复现相同生成结果 | #### 请求示例 ```json { "prompt": "一只躺在云朵上的猫咪，周围有彩虹和星星，水彩画风格", "image_size": "768x1024", "num_inference_steps": 30, "guidance_scale": 8.0 } ``` ### 2. 图片风格转换接口：POST /convert-style 将上传的图片转换为指定艺术风格。 #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | | ------------------- | ---------- | ---- | ------------------------------------------------------------ | | image | UploadFile | 是 | 图片文件，支持 JPG、PNG 格式（建议分辨率≥512x512） | | style | string | 是 | 风格类型，可选值： cartoon（卡通风格） oil_painting（油画风格） sketch（素描风格） ink_wash（水墨风格） | | image_size | string | 否 | 输出图片尺寸，可选值同上 | | num_inference_steps | int | 否 | 推理步数，范围：1-100 | | guidance_scale | float | 否 | 引导强度，范围：0-20 | | negative_prompt | string | 否 | 负面提示词 | ### 3. 3D 模型生成接口 #### 3.1 创建预览任务：POST /text-to-3d 根据文本描述创建 3D 模型预览任务。 | 参数名 | 类型 | 必填 | 默认值 | 说明 | | --------- | ------ | ---- | --------- | ------------------------------------------------------------ | | prompt | string | 是 | - | 3D 模型描述文本，最多 600 字符（如："一只机械恐龙，金属质感，站立姿势"） | | art_style | string | 否 | realistic | 艺术风格，可选值： realistic（写实风格） sculpture（雕塑风格） | #### 3.2 精细化任务：POST /text-to-3d/refine 创建 3D 模型精细化任务（需基于预览任务 ID）。 | 参数名 | 类型 | 必填 | 说明 | | ----------------- | ------ | ---- | ------------------------------------------------------ | | preview_task_id | string | 是 | 预览任务 ID，从 /text-to-3d 接口返回的 result 字段获取 | | enable_pbr | bool | 否 | 是否生成 PBR 贴图（雕塑风格时自动设为 false） | | texture_prompt | string | 否 | 纹理提示词（如："木纹质感，深色纹理"） | | texture_image_url | string | 否 | 纹理参考图片 URL | #### 3.3 查询任务状态：GET /text-to-3d/{task_id} 查询 3D 模型任务状态及结果。 | 参数名 | 类型 | 说明 | | ------------ | ------ | ------------------------------------------------------------ | | status | string | 任务状态： PENDING（等待） PROCESSING（处理中） SUCCEEDED（成功） FAILED（失败） | | progress | int | 任务进度（0-100） | | model_urls | object | 模型文件下载链接，包含 glb/fbx/obj/mtl/usdz 格式（SUCCEEDED 时返回） | | texture_urls | array | 贴图下载链接（如启用 PBR） | ### 4. 图片转 3D 模型接口 #### 4.1 上传图片创建任务：POST /image-to-3d/upload 通过上传图片创建 3D 模型任务。 | 参数名 | 类型 | 必填 | 说明 | | ------ | ---------- | ---- | ----------------------- | | file | UploadFile | 是 | 图片文件，支持 JPG、PNG | #### 4.2 查询任务状态：GET /image-to-3d/{task_id} 查询图片转 3D 任务状态，返回格式与 /text-to-3d/{task_id} 一致。 ## 使用示例 ### 1. 生成图片 ```bash curl -X POST "http://127.0.0.1:1189/generate-image" \ -H "Content-Type: application/json" \ -d '{"prompt": "一座漂浮在天空中的城堡，周围环绕着云彩和飞鸟，奇幻风格", "image_size": "1024x1024", "num_inference_steps": 25}' ``` ### 2. 转换图片风格 ```bash curl -X POST "http://127.0.0.1:1189/convert-style" \ -F "image=@/path/to/your/image.jpg" \ -F "style=oil_painting" \ -F "image_size=768x1024" \ -F "num_inference_steps=20" ``` ### 3. 生成 3D 模型 #### 3.1 创建预览任务 ```bash curl -X POST "http://127.0.0.1:1189/text-to-3d" \ -H "Content-Type: application/json" \ -d '{"prompt": "一个现代风格的台灯，金属底座，白色灯罩，简约设计", "art_style": "realistic"}' ``` #### 3.2 创建精细化任务（假设预览任务 ID 为`01234567-89ab-cdef-ghij-klmnopqrstuv`） ```bash curl -X POST "http://127.0.0.1:1189/text-to-3d/refine" \ -H "Content-Type: application/json" \ -d '{"preview_task_id": "01234567-89ab-cdef-ghij-klmnopqrstuv", "enable_pbr": true}' ``` #### 3.3 查询任务状态 ```bash curl "http://127.0.0.1:1189/text-to-3d/01234567-89ab-cdef-ghij-klmnopqrstuv" ``` ### 4. 图片转 3D 模型 #### 4.1 上传图片创建任务 ```bash curl -X POST "http://127.0.0.1:1189/image-to-3d/upload" \ -F "file=@/path/to/your/photo.jpg" ``` #### 4.2 查询任务状态（假设任务 ID 为`abc123`） ```bash curl "http://127.0.0.1:1189/image-to-3d/abc123" ``` ## 常见问题 ### 1. API 密钥获取 - **图片生成 API 密钥**：访问[硅基流动官网](https://cloud.siliconflow.cn/i/IfZMfM4f)注册账号，在控制台获取 API 密钥 - **3D 模型 API 密钥**：访问[Meshy 官网](https://www.meshy.ai/)注册账号，通过邀请好友获取 Pro 套餐（含免费额度） ### 2. 后端服务启动失败 - 问题 ``` ModuleNotFoundError ``` 错误 - **解决**：确认依赖已正确安装，可通过`pip list`查看已安装包 - 问题 ：端口被占用（默认端口 1189） - **解决**：使用其他端口启动：`uvicorn main:app --reload --port 8000` ### 3. 微信小程序无法连接后端 - 确认后端服务已启动且网络可达（可通过浏览器访问 API 文档测试） - 检查小程序`request.js`中的 API 地址是否正确（需包含 IP 和端口） - 微信小程序存在跨域限制，后端需在main.py中添加 CORS 中间件： ```python from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) ``` ### 4. 3D 模型生成失败 - 确保 Meshy API 密钥有效（可通过官方文档测试 API 是否可用） - 优化 prompt 描述：避免模糊词汇（如 "可能"、"大概"），增加细节（如材质、颜色、姿势） - 精细化任务需在预览任务状态为`SUCCEEDED`后进行，避免提前调用 ### 5. 图片生成效果不符合预期 - 调整`guidance_scale`参数：值越高越贴近 prompt 描述（建议范围 5-10） - 增加`negative_prompt`：明确排除不希望出现的元素（如 "低分辨率，模糊"） - 延长`num_inference_steps`：增加推理步数（建议 20-50）以提升细节