# 图片生成接口文档 ## 接口概述轻量级 HTTP 图片生成服务，用于根据画布配置和商品数据生成营销图片。该接口返回 base64 格式的图片数据，不做文件落地，便于外部（如 Python）直接调用获取图片切片。 **运行环境**: 仅在 Electron 渲染进程中可用（需要 Node.js 能力） --- ## 接口信息 ### 基本信息 - **接口地址**: `http://localhost:3001/generate` - **请求方法**: `POST` - **Content-Type**: `application/json` - **请求体大小限制**: 最大 50MB ### 接口路径 ``` POST /generate ``` --- ## 请求参数 ### 请求体结构 ```json { "canvasList": [], // 画布配置数组（必填） "goodsList": [] // 商品数据数组（必填） } ``` ### 参数说明 #### 1. canvasList（画布配置数组）画布配置数组，每个元素代表一个画布模板。 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | index | number | 是 | 画布索引，从 0 开始 | | canvas_json | string | 是 | Fabric.js 画布配置的 JSON 字符串，或特殊值 `"scene"`（场景图） | | width | number | 是 | 画布宽度（像素） | | height | number | 是 | 画布高度（像素） | | bg_color | string | 是 | 背景色，如 `"#fff"` | | name | string | 否 | 画布名称 | | preview | string | 否 | 预览图 URL | | tpl_url | string | 否 | 模板 URL | | image_path | string | 否 | 图片路径 | | canvas_type | string | 否 | 画布类型：`"normal"`（普通）、`"model"`（模特图）、`"scene"`（场景图） | | multi_goods_mode | string | 否 | 多商品模式 | | max_goods_count | number \| null | 否 | 最大商品数量 | **canvas_json 说明**: - 普通画布：Fabric.js 格式的 JSON 字符串，包含 `version`、`objects`、`background` 等字段 - 场景图：直接传入字符串 `"scene"` #### 2. goodsList（商品数据数组）商品数据数组，每个元素是一个对象，键为款号（styleKey），值为商品信息。 **数据结构**: ```json { "款号（styleKey）": { "款号": "string", // 款号，如 "E305-01003" "设计理念": "string", // 设计理念文案（可选，款级） "货号资料": [ // 货号数组 { "货号": "string", // 货号，如 "A596351" "颜色": "string", // 颜色，如 "黑色" "设计理念": "string", // 设计理念文案（可选，货号级，优先级高于款级） "pics": { // 图片路径对象 "视角名称": "string" // 键为视角名称（如"俯视"、"侧视"、"后跟"等），值为图片路径 } } ] } } ``` **pics 对象说明**: - 键：视角名称，如 `"俯视"`、`"侧视"`、`"后跟"`、`"鞋底"`、`"内里"` 等 - 值：图片文件路径（支持本地路径，如 `"C:\\Users\\...\\image.png"`） --- ## 响应格式 ### 成功响应 **HTTP 状态码**: `200` **响应体**: ```json { "code": 0, "images": [ { "canvasIndex": 0, // 画布索引 "dataUrl": "data:image/png;base64,..." // base64 格式的图片数据 } ], "plans": [] // 渲染计划数组（内部使用） } ``` **响应字段说明**: | 字段 | 类型 | 说明 | |------|------|------| | code | number | 响应码，0 表示成功 | | images | array | 生成的图片数组 | | images[].canvasIndex | number | 对应的画布索引 | | images[].dataUrl | string | base64 格式的图片数据，可直接用于 `

` | | plans | array | 渲染计划数组（内部数据结构） | ### 失败响应 **HTTP 状态码**: `500` **响应体**: ```json { "code": 1, "msg": "error message" } ``` **响应字段说明**: | 字段 | 类型 | 说明 | |------|------|------| | code | number | 响应码，1 表示失败 | | msg | string | 错误信息 | ### 其他错误响应 | HTTP 状态码 | 说明 | 响应体 | |------------|------|--------| | 404 | 路径或方法错误 | `"Not Found"` | | 413 | 请求体过大（>50MB） | `"Payload Too Large"` | --- ## 调用示例 ### JavaScript/TypeScript 示例 ```javascript const response = await fetch('http://localhost:3001/generate', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ canvasList: [ { index: 0, canvas_json: '{"version":"5.2.1","objects":[{"type":"image","src":"...","left":0,"top":0}],"background":"#fff"}', width: 395, height: 618, bg_color: "#fff", name: "画布_1", canvas_type: "normal" } ], goodsList: [ { "AC5120913": { "款号": "E305-01003", "设计理念": "平衡舒适性、美观性、功能性和工艺品质", "货号资料": [ { "货号": "A596351", "颜色": "黑色", "设计理念": "满足现代消费者在不同场景下的需求", "pics": { "俯视": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\1.png", "侧视": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\2.png", "后跟": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\3.png", "鞋底": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\4.png", "内里": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\5.png" } } ] } } ] }) }) const result = await response.json() if (result.code === 0) { console.log('生成成功，共', result.images.length, '张图片') result.images.forEach(img => { console.log(`画布 ${img.canvasIndex} 的图片:`, img.dataUrl.substring(0, 50) + '...') }) } else { console.error('生成失败:', result.msg) } ``` ### Python 示例 ```python import requests import json url = "http://localhost:3001/generate" payload = { "canvasList": [ { "index": 0, "canvas_json": '{"version":"5.2.1","objects":[],"background":"#fff"}', "width": 395, "height": 618, "bg_color": "#fff", "name": "画布_1", "canvas_type": "normal" } ], "goodsList": [ { "AC5120913": { "款号": "E305-01003", "货号资料": [ { "货号": "A596351", "颜色": "黑色", "pics": { "俯视": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\1.png", "侧视": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\2.png" } } ] } } ] } response = requests.post(url, json=payload) if response.status_code == 200: result = response.json() if result.get("code") == 0: print(f"生成成功，共 {len(result['images'])} 张图片") for img in result["images"]: print(f"画布 {img['canvasIndex']} 的图片已生成") # 可以保存 base64 图片 # data_url = img["dataUrl"] # base64_data = data_url.split(",")[1] # with open(f"output_{img['canvasIndex']}.png", "wb") as f: # f.write(base64.b64decode(base64_data)) else: print(f"生成失败: {result.get('msg')}") else: print(f"请求失败，状态码: {response.status_code}") ``` ### cURL 示例 ```bash curl -X POST http://localhost:3001/generate \ -H "Content-Type: application/json" \ -d '{ "canvasList": [ { "index": 0, "canvas_json": "{\"version\":\"5.2.1\",\"objects\":[],\"background\":\"#fff\"}", "width": 395, "height": 618, "bg_color": "#fff", "name": "画布_1", "canvas_type": "normal" } ], "goodsList": [ { "AC5120913": { "款号": "E305-01003", "货号资料": [ { "货号": "A596351", "颜色": "黑色", "pics": { "俯视": "C:\\\\Users\\\\Administrator\\\\Desktop\\\\img\\\\A596351\\\\1.png", "侧视": "C:\\\\Users\\\\Administrator\\\\Desktop\\\\img\\\\A596351\\\\2.png" } } ] } } ] }' ``` --- ## 注意事项 1. **运行环境限制**: 该接口仅在 Electron 渲染进程中可用，需要 Node.js 集成能力。在普通浏览器环境中无法使用。 2. **端口占用**: 接口默认监听 `3001` 端口，确保该端口未被占用。 3. **请求体大小**: 请求体大小限制为 50MB，超过此限制将返回 `413` 错误。 4. **图片路径**: - 支持本地文件路径（Windows 路径格式：`C:\\Users\\...`） - 确保图片文件存在且可访问 5. **canvas_json 格式**: - 普通画布必须是有效的 Fabric.js JSON 字符串 - 场景图使用特殊值 `"scene"` 6. **错误处理**: 建议在调用时捕获异常，并根据 `code` 字段判断请求是否成功。 7. **base64 图片使用**: - 返回的 `dataUrl` 可直接用于 HTML `` 标签的 `src` 属性 - 如需保存为文件，需要提取 base64 数据部分（去掉 `data:image/png;base64,` 前缀） --- ## 版本信息 - **接口版本**: v1.0 - **最后更新**: 2024-12-09