Quick Start
A successful API call in under five minutes.
1. Get an API key
Sign up → API Keys → Create key.
Authorization: Bearer pk_test_YOUR_KEYYou get a pk_test_… sandbox key for development and a pk_live_… key for production. The POST request below needs a key: without one it returns 401. Only GET /api/v1/render works with no key, and then only for PNG up to 1200px at 5 renders per 15 minutes per IP address (see Authentication).
2. Make the request
POST a JSON spec to /api/v1/render. The response is raw image bytes.
curl -X POST https://www.chart-output.com/api/v1/render \
-H "Authorization: Bearer pk_test_YOUR_KEY" \
-H "Content-Type: application/json" \
--output chart.png \
-d '{
"type": "bar",
"width": 800,
"height": 400,
"format": "png",
"data": {
"labels": ["Jan", "Feb", "Mar", "Apr"],
"datasets": [{
"label": "Revenue",
"data": [12000, 15000, 18000, 22000],
"backgroundColor": "#6ee7b7",
"borderRadius": 4
}]
}
}'const res = await fetch('https://www.chart-output.com/api/v1/render', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.CHART_OUTPUT_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"type": "bar",
"width": 800,
"height": 400,
"format": "png",
"data": {
"labels": ["Jan", "Feb", "Mar", "Apr"],
"datasets": [{
"label": "Revenue",
"data": [12000, 15000, 18000, 22000],
"backgroundColor": "#6ee7b7",
"borderRadius": 4
}]
}
}),
});
if (!res.ok) throw new Error(await res.text());
// Binary PNG bytes — save to disk or pipe to an S3 upload
const buf = Buffer.from(await res.arrayBuffer());
await fs.promises.writeFile('chart.png', buf);import os, json, urllib.request
spec = json.loads(r"""{
"type": "bar",
"width": 800,
"height": 400,
"format": "png",
"data": {
"labels": ["Jan", "Feb", "Mar", "Apr"],
"datasets": [{
"label": "Revenue",
"data": [12000, 15000, 18000, 22000],
"backgroundColor": "#6ee7b7",
"borderRadius": 4
}]
}
}""")
req = urllib.request.Request(
"https://www.chart-output.com/api/v1/render",
data=json.dumps(spec).encode(),
headers={
"Authorization": f"Bearer {os.environ['CHART_OUTPUT_API_KEY']}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req) as resp:
open("chart.png", "wb").write(resp.read())3. Read the response
The default response is binary image data. Every response includes diagnostic headers.
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 28431
Cache-Control: public, max-age=31536000, immutable
ETag: "d41d8cd9..."
X-Render-Time-Ms: 52
X-Cache: MISS
X-Request-Id: req_01hx...
<binary PNG bytes>Set returnUrl: true to get a CDN URL instead. Useful when you need a stable image URL for embedding in HTML or passing to another service.
{
"type": "bar",
"width": 800,
"height": 400,
"returnUrl": true,
"data": {
"labels": ["Jan", "Feb", "Mar"],
"datasets": [{ "label": "Revenue", "data": [12000, 15000, 18000] }]
}
}HTTP/1.1 200 OK
Content-Type: application/json
X-Render-Time-Ms: 48
X-Cache: MISS
X-Request-Id: req_01hx...
{ "url": "https://cdn.chart-output.com/renders/abc123.png" }| Header | Meaning |
|---|---|
| Content-Type | image/png, image/jpeg, image/svg+xml, image/webp, or application/pdf |
| X-Render-Time-Ms | Server-side render latency in milliseconds |
| X-Cache | HIT or MISS — identical specs are cached |
| X-Request-Id | Unique request ID — include this when reporting issues |
| ETag | MD5 of the spec — use for client-side conditional requests |
4. Embed in email
Use the GET endpoint with your key as a query parameter. Browsers cannot send Authorization headers with image requests, so a ?key= query parameter is how the GET endpoint takes a key. The key is then part of the image URL, so anyone who views the email source can read it. For emails that go to other people, render once with returnUrl: true and embed the hosted image URL, which does not contain your key.
<img
src="https://www.chart-output.com/api/v1/render?key=pk_live_YOUR_KEY&type=bar&labels=Jan,Feb,Mar,Apr&data=12000,15000,18000,22000&format=png&width=600&height=300"
alt="Revenue chart"
width="600"
height="300"
/>Use PNG for email — it has the broadest client support. See the Charts in Email guide for Resend, Nodemailer, and SendGrid examples.
Next steps
- Authentication — Key types, query-param auth, 401 debugging
- API Reference — All parameters and response shapes
- Chart Specifications — Every dataset field, limits, null gaps
- Brand Kits — Consistent colors, fonts, and logos across renders
- Output Formats — PNG vs SVG vs PDF — when to use each
- Error Reference — Every status code with cause and fix
Related walkthroughs
Convert Chart.js to an image
Export a Chart.js config as PNG, SVG, WebP or PDF for email, reports and pipelines.
Add a chart to an n8n workflow
Google Sheets rows to a chart image in Slack or email, with one Code node and one HTTP Request node.
Turn a CSV into a chart in Claude, Cursor or Windsurf
Add the MCP server once, paste a CSV, get a chart image back. Setup, three prompts and common errors.
Replacing the shut-down Google Chart API
chart.googleapis.com returns 404. Your options, with a parameter translation table.