Chart Splat
Generate beautiful charts from data using the Chart Splat API. Charts are rendered server-side with Chart.js and returned as PNG images.
Supported Chart Types
| Type | Best For |
|---|
| INLINECODE0 | Trends over time |
| INLINECODE1 |
Comparing categories |
|
pie | Parts of a whole |
|
doughnut | Parts of a whole (with center space) |
|
radar | Multivariate comparison |
|
polarArea | Comparing categories with radial layout |
|
candlestick | Financial/crypto OHLC price data |
|
ohlc | Financial/crypto OHLC price data (bar variant) |
Method 1: CLI (Preferred)
Use the chartsplat CLI via npx. No install required.
CODEBLOCK0
CLI Options
| Flag | Description |
|---|
| INLINECODE9 | Comma-separated labels |
| INLINECODE10 |
Comma-separated numeric values |
|
-t, --title <text> | Chart title |
|
--label <text> | Dataset label for legend |
|
-c, --color <hex> | Background color |
|
-w, --width <px> | Image width (default: 800) |
|
--height <px> | Image height (default: 600) |
|
-o, --output <file> | Output file path (default: chart.png) |
|
--config <file> | JSON config file for complex charts |
CLI Chart Commands
CODEBLOCK1
Candlestick Charts
Candlestick and OHLC charts require a JSON config file since the data format is more complex than a simple CSV list. Use --config to provide a file with OHLC data points.
CODEBLOCK2
Config format (ohlc.json):
CODEBLOCK3
Each OHLC data point requires: x (numeric timestamp in ms, or a date string like "2025-02-25"), o (open), h (high), l (low), c (close).
Complex Charts via Config File
For multi-dataset or customized charts, write a JSON config file then pass it to the CLI:
CODEBLOCK4
See examples/sample-charts.json for config file examples and references/api-reference.md for the full config schema.
Method 2: Helper Script
Use the bundled script for quick generation without installing the CLI:
CODEBLOCK5
Or with a config file:
CODEBLOCK6
Output Handling
- - Charts are saved as PNG files to the specified output path
- Default output is
chart.png in the current directory - For messaging platforms (Discord, Slack), return the file path: INLINECODE27
- The CLI and helper script handle base64 decoding automatically
Error Handling
| Error | Cause | Fix |
|---|
| INLINECODE28 | Missing INLINECODE29 | Set the env var in agent config |
| INLINECODE30 |
Wrong or revoked key | Generate a new key at chartsplat.com/dashboard |
|
Rate limit exceeded | Monthly quota reached | Upgrade plan or wait for reset |
|
Invalid chart configuration | Bad request payload | Check that
data.labels and
data.datasets are present (candlestick/ohlc only require
data.datasets) |
Tips
- - Always provide both
labels and data arrays of the same length - Use hex colors (e.g.,
#8b5cf6) for consistent styling - For pie/doughnut charts, use an array of colors for
backgroundColor to color each segment - Default dimensions (800x600) work well for most uses; increase for presentations
- The
--config flag accepts any valid Chart.js configuration for full customization
Chart Splat
使用Chart Splat API从数据生成精美的图表。图表在服务端通过Chart.js渲染，并以PNG图片形式返回。
支持的图表类型
类别对比 |
| pie | 整体中的各部分占比 |
| doughnut | 整体中的各部分占比（带中心空白） |
| radar | 多变量对比 |
| polarArea | 径向布局的类别对比 |
| candlestick | 金融/加密货币OHLC价格数据 |
| ohlc | 金融/加密货币OHLC价格数据（柱状变体） |
方法一：命令行工具（推荐）
通过npx使用chartsplat命令行工具，无需安装。
bash
npx -y chartsplat-cli bar \
--labels Q1,Q2,Q3,Q4 \
--data 50,75,60,90 \
--title 季度收入 \
--color #8b5cf6 \
-o chart.png
命令行选项
| 标志 | 说明 |
|---|
| -l, --labels <csv> | 逗号分隔的标签 |
| -d, --data <csv> |
逗号分隔的数值 |
| -t, --title
| 图表标题 |
| --label | 图例的数据集标签 |
| -c, --color | 背景颜色 |
| -w, --width | 图片宽度（默认：800） |
| --height | 图片高度（默认：600） |
| -o, --output | 输出文件路径（默认：chart.png） |
| --config | 复杂图表的JSON配置文件 |
命令行图表命令
bash
npx -y chartsplat-cli line -l 周一,周二,周三,周四,周五 -d 100,200,150,300,250 -o line.png
npx -y chartsplat-cli bar -l A,B,C -d 10,20,30 -o bar.png
npx -y chartsplat-cli pie -l 红色,蓝色,绿色 -d 30,50,20 -o pie.png
npx -y chartsplat-cli doughnut -l 是,否,可能 -d 60,25,15 -o doughnut.png
npx -y chartsplat-cli radar -l 速度,力量,范围,耐久度,精准度 -d 80,90,70,85,95 -o radar.png
npx -y chartsplat-cli polararea -l 北,东,南,西 -d 40,30,50,20 -o polar.png
npx -y chartsplat-cli candlestick --config ohlc.json -o chart.png
K线图
K线图和OHLC图表需要JSON配置文件，因为数据格式比简单的CSV列表更复杂。使用--config提供包含OHLC数据点的文件。
bash
npx -y chartsplat-cli candlestick --config ohlc.json -o candlestick.png
配置格式（ohlc.json）：
json
{
type: candlestick,
data: {
datasets: [{
label: VVV价格,
data: [
{ x: 1740441600000, o: 4.23, h: 4.80, l: 4.10, c: 4.45 },
{ x: 1740528000000, o: 4.45, h: 5.50, l: 4.30, c: 5.34 },
{ x: 1740614400000, o: 5.34, h: 6.20, l: 5.10, c: 5.97 }
]
}]
}
}
每个OHLC数据点需要：x（数值型时间戳，单位为毫秒，或日期字符串如2025-02-25）、o（开盘价）、h（最高价）、l（最低价）、c（收盘价）。
通过配置文件创建复杂图表
对于多数据集或自定义图表，编写JSON配置文件后传递给命令行工具：
bash
npx -y chartsplat-cli bar --config chart-config.json -o chart.png
配置文件示例请参见examples/sample-charts.json，完整配置模式请参考references/api-reference.md。
方法二：辅助脚本
使用内置脚本快速生成，无需安装命令行工具：
bash
node scripts/generate-chart.js bar Q1,Q2,Q3,Q4 50,75,60,90 收入 chart.png
或使用配置文件：
bash
node scripts/generate-chart.js --config chart-config.json -o chart.png
输出处理
- - 图表以PNG文件形式保存到指定的输出路径
- 默认输出为当前目录下的chart.png
- 对于消息平台（Discord、Slack），返回文件路径：MEDIA: /path/to/chart.png
- 命令行工具和辅助脚本会自动处理base64解码
错误处理
| 错误 | 原因 | 解决方法 |
|---|
| 需要API密钥 | 缺少CHARTSPLATAPIKEY | 在代理配置中设置环境变量 |
| 无效的API密钥 |
密钥错误或已吊销 | 在chartsplat.com/dashboard生成新密钥 |
| 超出速率限制 | 达到月度配额 | 升级套餐或等待重置 |
| 无效的图表配置 | 请求负载错误 | 检查是否包含data.labels和data.datasets（K线图/OHLC仅需data.datasets） |
提示
- - 始终提供长度相同的labels和data数组
- 使用十六进制颜色（如#8b5cf6）保持样式一致
- 对于饼图/环形图，使用颜色数组作为backgroundColor为每个扇区着色
- 默认尺寸（800x600）适用于大多数场景；演示时可增大尺寸
- --config标志接受任何有效的Chart.js配置，实现完全自定义
