Skip to main content

AI chart rendering

Pass a natural-language description and optional raw data. Chart-Output generates a validated chart spec and renders it in the same request. Response shape mirrors /api/v1/render, so you can swap endpoints without changing the rest of your code path.

What this endpoint does

  1. Runs your description (and any data you attach) through our AI layer to produce chart JSON.
  2. Parses the response as JSON and validates it with the same Zod schema as the standard render endpoint.
  3. On invalid JSON or schema failure, returns GENERATION_FAILED immediately — there is no repair or model retry.
  4. Optionally runs shared validate-and-normalize when repair_mode is set, then hands the spec to the existing renderer.

The model never renders anything itself. Every image you receive was produced by the same deterministic renderer used by /api/v1/render.

Request shape

POST /api/v1/ai/render

json
{ "description": string, // optional if data is given: natural-language prompt, up to 4000 chars "data": unknown, // optional if description is given: CSV string, JSON array, or object "brandKitId": string, // optional: UUID of a saved brand kit "brand": string, // optional: slug of a saved brand kit "width": number, // optional: 100–4000, default 800 "height": number, // optional: 100–4000, default 400 "format": "png" | "jpeg" | "svg" | "webp" | "pdf", "returnUrl": boolean, // optional: return { url, chartType } JSON instead of bytes "repair_mode": "off" | "safe" // optional: structured envelope + validate-and-normalize }

Response headers include X-Ai-Chart-Type (the chart type the model chose) and X-Ai-Generation-Ms (time spent in the model, excluding render).

Examples

Description only

typescript
const res = await fetch('https://www.chart-output.com/api/v1/ai/render', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CHART_OUTPUT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ description: 'Monthly active users for 2024, rising from 12k in Jan to 24k in Dec. Use a calm blue palette.', format: 'png', width: 800, height: 400, }), }); if (!res.ok) { const err = await res.json(); throw new Error(err.details ?? err.error); } const buffer = Buffer.from(await res.arrayBuffer()); const chartType = res.headers.get('x-ai-chart-type'); const generationMs = res.headers.get('x-ai-generation-ms');

Description + structured data, persisted URL

typescript
await fetch('https://www.chart-output.com/api/v1/ai/render', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CHART_OUTPUT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ description: 'Revenue by region, ranked highest to lowest.', data: [ { region: 'Americas', revenue: 420 }, { region: 'EMEA', revenue: 310 }, { region: 'APAC', revenue: 280 }, { region: 'Other', revenue: 90 }, ], returnUrl: true, }), });

How validation works

Chart-Output validates the model output with the same Zod schema that powers /api/v1/render. There is no repair step: invalid JSON or schema failure returns 422 with a structured GENERATION_FAILED error (retryable: true). When repair_mode is off or safe, a valid spec also runs through the shared validate-and-normalize pipeline used by the standard render endpoint.

This means every image you receive from the AI endpoint would also be renderable via the manual JSON API. There is no path by which the model can cause an invalid render.

Limits and pitfalls

  • The model is limited to the six supported chart types: line, bar, pie, doughnut, radar, polarArea.
  • Chart.js plugins not represented in the schema (e.g. custom scale plugins) cannot be requested.
  • Attached data is serialized and truncated at 2,000 characters before being sent to the model. For very large datasets, pre-aggregate server-side.
  • Descriptions over 4,000 characters are rejected at request time.
  • Each call includes a round-trip to the model, so it is slower than a normal render. The call is synchronous.
  • Chart specs are written by an OpenAI chat model. Your description and data are sent to OpenAI for that request. The model is chosen by Chart-Output, not per request.

Plan gating & quotas

AI rendering is available on the Pro and Agency plans. Free keys receive 403 with an upgrade URL.

AI renders have their own monthly cap separate from the general render quota — each AI generation call has real per-request cost, so the limit is intentionally tighter:

PlanAI renders / monthGeneral renders / month
Pro10025,000
Agency1,000150,000

Exceeding the AI quota returns 402 with error: "quota_exceeded", the metric, your limit and an upgrade_url. Successful responses carry X-Quota-Limit, X-Quota-Used and X-Quota-Reset headers so you can monitor usage programmatically.