CameraMachine/generateServer.API.md

图片生成接口文档

接口概述

轻量级 HTTP 图片生成服务，用于根据画布配置和商品数据生成营销图片。该接口返回 base64 格式的图片数据，不做文件落地，便于外部（如 Python）直接调用获取图片切片。

运行环境: 仅在 Electron 渲染进程中可用（需要 Node.js 能力）

---

接口信息

基本信息

• 接口地址: http://localhost:3001/generate
• 请求方法: POST
• Content-Type: application/json
• 请求体大小限制: 最大 50MB

接口路径

POST /generate

---

请求参数

请求体结构

{
  "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），值为商品信息。

数据结构:

{
  "款号（styleKey）": {
    "款号": "string",           // 款号，如 "E305-01003"
    "设计理念": "string",        // 设计理念文案（可选，款级）
    "货号资料": [                // 货号数组
      {
        "货号": "string",        // 货号，如 "A596351"
        "颜色": "string",        // 颜色，如 "黑色"
        "设计理念": "string",    // 设计理念文案（可选，货号级，优先级高于款级）
        "pics": {                // 图片路径对象
          "视角名称": "string"   // 键为视角名称（如"俯视"、"侧视"、"后跟"等），值为图片路径
        }
      }
    ]
  }
}

pics 对象说明:

• 键：视角名称，如 "俯视"、"侧视"、"后跟"、"鞋底"、"内里" 等
• 值：图片文件路径（支持本地路径，如 "C:\\Users\\...\\image.png"）

---

响应格式

成功响应

HTTP 状态码: 200

响应体:

{
  "code": 0,
  "images": [
    {
      "canvasIndex": 0,                    // 画布索引
      "dataUrl": "data:image/png;base64,..."  // base64 格式的图片数据
    }
  ],
  "plans": []  // 渲染计划数组（内部使用）
}

响应字段说明:

字段	类型	说明
code	number	响应码，0 表示成功
images	array	生成的图片数组
images[].canvasIndex	number	对应的画布索引
images[].dataUrl	string	base64 格式的图片数据，可直接用于 <img src="...">
plans	array	渲染计划数组（内部数据结构）

失败响应

HTTP 状态码: 500

响应体:

{
  "code": 1,
  "msg": "error message"
}

响应字段说明:

字段	类型	说明
code	number	响应码，1 表示失败
msg	string	错误信息

其他错误响应

HTTP 状态码	说明	响应体
404	路径或方法错误	"Not Found"
413	请求体过大（>50MB）	"Payload Too Large"

---

调用示例

JavaScript/TypeScript 示例

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 示例

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 示例

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 <img> 标签的 src 属性
   • 如需保存为文件，需要提取 base64 数据部分（去掉 data:image/png;base64, 前缀）

---

版本信息

• 接口版本: v1.0
• 最后更新: 2024-12-09