data-chart-tool/API.md

📡 数据可视化图表生成器 - API 文档

版本：v1.9.0 | 基础地址：http://192.168.0.101:16016

---

接口总览

方法	路径	说明
POST	/api/chart	生成图表图片（JSON body，推荐）
GET	/api/chart	生成图表图片（URL 参数）
POST	/api/combine	多图合并（横排/竖排）生成一张图
GET	/api/health	健康检查
GET	/api/docs	返回本文档（JSON）

---

1. POST /api/chart（推荐）

通过 JSON 请求体生成图表，返回 PNG 图片。

请求

POST /api/chart
Content-Type: application/json

参数说明

参数	类型	必填	默认值	说明
data	string	✅	—	CSV 格式数据，\n 换行，第一行表头，第一列横坐标
chartType	string	—	bar	图表类型：bar / line / bar-line / pie / radar
title	string	—	""	图表标题
theme	string	—	default	主题风格：default / dark / macarons / gradient / retro
showLegend	boolean	—	true	显示图例
showGrid	boolean	—	true	显示网格线
showLabel	boolean	—	false	显示数据标签
stackMode	boolean	—	false	堆叠模式
smoothLine	boolean	—	true	折线平滑
enableSplit	boolean	—	false	启用区域分割
splitIndex	number	—	3	分割位置（第几个数据后分割）
leftLabel	string	—	"左侧"	左侧区域标签
rightLabel	string	—	"右侧"	右侧区域标签
splitStyle	string	—	"solid"	分割线样式：solid / dashed / dotted
dualYAxis	boolean	—	false	启用双Y轴（左右量度不同）
rightAxisSeries	array	—	null	右轴系列名列表，如 ["利润"]（未列出的系列用左轴）
leftAxisName	string	—	""	左轴名称（如 "销售额(元)"）
rightAxisName	string	—	""	右轴名称（如 "增长率(%)"）
seriesTypes	array	—	null	每系列图表类型，按系列顺序对应，如 ["bar","line"]（bar/line/auto）
seriesAxis	array	—	null	每系列坐标轴，按系列顺序对应，如 [0,1]（0=左轴 1=右轴，配合 dualYAxis；优先于 rightAxisSeries）
rowsAsSeries	boolean	—	false	数据方向：false=列=系列（第一列是横坐标，每列一个系列）；true=行=系列（第一行是横坐标，每行一个系列）
width	number	—	800	图片宽度（px）
height	number	—	500	图片高度（px）
pixelRatio	number	—	2	像素倍率（越大越清晰）

返回

• Content-Type: image/png
• 响应头:
  • X-Chart-Width — 图片宽度
  • X-Chart-Height — 图片高度
  • X-Chart-Pixel-Ratio — 像素倍率

curl 示例

基础柱状图：

curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "产品, Q1, Q2, Q3, Q4\n手机, 1200, 1800, 2100, 2500\n平板, 800, 950, 1100, 1300\n笔记本, 600, 750, 900, 1050",
    "chartType": "bar",
    "title": "季度销售对比"
  }' -o chart.png

深色主题折线图 + 数据标签：

curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "月份, 营收(万), 利润(万), 用户(千)\n1月, 500, 80, 50\n2月, 680, 120, 85\n3月, 820, 160, 130\n4月, 1050, 230, 200\n5月, 1380, 350, 320",
    "chartType": "line",
    "title": "年度增长趋势",
    "theme": "dark",
    "showLabel": true,
    "width": 900,
    "height": 500
  }' -o trend.png

区域分割对比图：

curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "月份, 方案A, 方案B\n1月, 85, 78\n2月, 88, 82\n3月, 92, 88\n4月, 90, 95\n5月, 95, 98\n6月, 98, 102",
    "chartType": "bar",
    "title": "方案对比",
    "theme": "gradient",
    "enableSplit": true,
    "splitIndex": 3,
    "leftLabel": "上半年",
    "rightLabel": "下半年",
    "splitStyle": "dashed"
  }' -o compare.png

堆叠柱状图：

curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "季度, 线上, 线下, 批发\nQ1, 300, 200, 150\nQ2, 450, 280, 200\nQ3, 520, 350, 180\nQ4, 680, 400, 250",
    "chartType": "bar",
    "title": "渠道销售分布",
    "stackMode": true,
    "theme": "macarons"
  }' -o stack.png

高分辨率大图：

curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "产品, 2023, 2024, 2025\nA, 100, 200, 300\nB, 150, 250, 350",
    "width": 1600,
    "height": 900,
    "pixelRatio": 3
  }' -o hd-chart.png

---

2. GET /api/chart

通过 URL 参数生成图表，适合简单场景或直接在浏览器中使用。

参数

参数	说明
data	CSV 数据（换行用 \n 表示，需 URL 编码）
type	图表类型（bar / line / bar-line）
title	图表标题
theme	主题风格
width	图片宽度
height	图片高度

curl 示例

curl "http://192.168.0.101:16016/api/chart?data=%E4%BA%A7%E5%93%81,Q1,Q2%0A%E6%89%8B%E6%9C%BA,100,200%0A%E5%B9%B3%E6%9D%BF,150,250&type=bar&title=%E6%B5%8B%E8%AF%95" -o chart.png

---

3. POST /api/combine（多图合并）

将多张图表合并到一张图片中（默认 2 张，可多张），支持横排（单行）、竖排（单列）、多行多列网格三种排布，返回 PNG 图片。

请求

POST /api/combine
Content-Type: application/json

参数说明

参数	类型	必填	说明
charts	array	✅	图表配置数组（N 张），每项同 /api/chart 参数：data/chartType/title/theme 等
direction	string	否	horizontal 横排（默认）/ vertical 竖排 / grid 多行多列
cols	number	否	多行多列时的每行列数（默认 2，仅 grid 生效）
gap	number	否	图间距（默认 24px）
pixelRatio	number	否	像素倍率，默认 2（越清晰文件越大）
background	string	否	背景色，默认 #ffffff
bigTitle	string	否	整张图片的大标题（可空），居中显示在顶部
legendMode	string	否	图例方式：own 每个小图各自图例（默认）/ shared-top 共用一套图例放顶部 / shared-bottom 共用一套图例放底部（共用时各子图隐藏自己的图例，系列合并去重）
theme	string	否	大标题/共享图例文字颜色所属主题，默认 default（深色用 dark）

兼容旧参数：chart1 + chart2 仍可传（等价于 charts: [chart1, chart2]）。

每个子图配置支持：data（CSV）、chartType（bar/line/bar-line/pie/radar）、title、theme、showLegend、showGrid、showLabel、stackMode、smoothLine、width、height，以及数据方向与多类型双轴：rowsAsSeries（行=系列）、dualYAxis、leftAxisName、rightAxisName、seriesTypes、seriesAxis。

高级示例（大标题 + 底部共享图例 + 行=系列 + 柱状/折线双轴）

curl -X POST http://127.0.0.1:16016/api/combine \
  -H "Content-Type: application/json" \
  -d '{
    "bigTitle": "经营总览大图",
    "legendMode": "shared-bottom",
    "direction": "grid",
    "cols": 2,
    "charts": [
      {"data": "指标, 2023, 2024, 2025\n营收(元), 1200, 1800, 2100\n销量(个), 100, 150, 130",
       "rowsAsSeries": true, "chartType": "bar", "title": "营收与销量",
       "dualYAxis": true, "leftAxisName": "元", "rightAxisName": "个",
       "seriesTypes": ["bar","line"], "seriesAxis": [0,1]},
      {"data": "产品, Q1, Q2\n手机, 1200, 1800\n平板, 800, 950", "chartType": "bar", "title": "季度销售"}
    ]
  }' -o combine.png

curl 示例

横排三张图（左右并排）：

curl -X POST http://127.0.0.1:16016/api/combine \
  -H "Content-Type: application/json" \
  -d '{
    "charts": [
      {"data": "产品, Q1, Q2\n手机, 1200, 1800\n平板, 800, 950", "title": "销售", "chartType": "bar"},
      {"data": "月份, 营收\n1月, 500\n2月, 680\n3月, 820", "title": "趋势", "chartType": "line"},
      {"data": "地区, 销量\n华东, 300\n华南, 450", "title": "地区销量", "chartType": "bar"}
    ],
    "direction": "horizontal"
  }' -o combine.png
```  -d '{
    "chart1": {
      "data": "产品, Q1, Q2\n手机, 1200, 1800\n平板, 800, 950",
      "title": "2024年销售",
      "chartType": "bar"
    },
    "chart2": {
      "data": "月份, 营收\n1月, 500\n2月, 680\n3月, 820",
      "title": "营收趋势",
      "chartType": "line"
    },
    "direction": "horizontal"
  }' -o combine.png

竖排（上下堆叠）：

curl -X POST http://127.0.0.1:16016/api/combine \
  -H "Content-Type: application/json" \
  -d '{
    "chart1": {"data": "指标, 2023年\n营收, 500\n利润, 80", "title": "营收对比", "chartType": "bar"},
    "chart2": {"data": "月份, 效率\n1月, 85\n2月, 88", "title": "效率趋势", "chartType": "line"},
    "direction": "vertical"
  }' -o combine.png

返回

PNG 图片二进制流，响应头包含：

响应头	说明
Content-Type	image/png
X-Combine-Direction	horizontal / vertical
X-Chart-Width / X-Chart-Height	合并图逻辑尺寸

---

4. GET /api/health

健康检查。

curl http://192.168.0.101:16016/api/health

返回：

{
  "status": "ok",
  "service": "data-chart-tool",
  "version": "1.16.0",
  "endpoints": {
    "POST /api/chart": "生成图表图片（JSON body）",
    "GET /api/chart": "生成图表图片（URL 参数）",
    "GET /api/health": "健康检查"
  }
}

---

数据格式说明

CSV 格式，规则：

1. 第一行：表头（系列名称）
2. 第一列：横坐标值
3. 其余单元格：数值
4. 分隔符：逗号（自动识别制表符和 |）

类别, 系列1, 系列2, 系列3
A, 10, 20, 30
B, 15, 25, 35
C, 20, 30, 40

在 JSON 中用 \n 表示换行：

{
  "data": "类别, 系列1, 系列2, 系列3\nA, 10, 20, 30\nB, 15, 25, 35\nC, 20, 30, 40"
}

---

各语言调用示例

Python

import requests

resp = requests.post('http://192.168.0.101:16016/api/chart', json={
    "data": "月份, 营收, 利润\n1月, 500, 80\n2月, 680, 120\n3月, 820, 160",
    "chartType": "line",
    "title": "增长趋势",
    "theme": "dark",
    "showLabel": True,
    "width": 900,
    "height": 500
})

with open('chart.png', 'wb') as f:
    f.write(resp.content)

print(f"图片大小: {len(resp.content)} bytes")

JavaScript (Node.js)

const fetch = require('node-fetch');
const fs = require('fs');

const resp = await fetch('http://192.168.0.101:16016/api/chart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        data: "产品, Q1, Q2\n手机, 1200, 2500\n平板, 800, 1300",
        chartType: "bar",
        title: "销售对比",
        width: 800,
        height: 500
    })
});

const buffer = await resp.buffer();
fs.writeFileSync('chart.png', buffer);

JavaScript (浏览器 fetch)

const resp = await fetch('http://192.168.0.101:16016/api/chart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        data: "产品, Q1, Q2\n手机, 1200, 2500\n平板, 800, 1300",
        chartType: "bar",
        title: "销售对比"
    })
});

const blob = await resp.blob();
const url = URL.createObjectURL(blob);
const img = document.createElement('img');
img.src = url;
document.body.appendChild(img);

Shell (保存到文件)

curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{"data":"A,B\n1,2\n3,4","chartType":"bar"}' \
  -o chart.png

---

主题预览

主题	说明	适用场景
default	经典蓝绿配色	通用
dark	深色背景 + 高亮色	大屏展示、PPT
macarons	柔和马卡龙色	清新风格
gradient	渐变色 + 圆角柱	现代感设计
retro	复古低饱和度	文艺风格

---

错误处理

请求失败时返回 JSON：

{
  "error": "缺少 data 参数（CSV 格式数据）"
}

常见错误：

HTTP 状态码	原因
400	缺少 data 参数或数据格式错误
500	服务端渲染异常

---

文档更新时间：2026-07-16