JavaScript SDK
Generate Figviz diagrams from Node.js or the command line with the official SDK and CLI
The official SDK is a thin, zero-dependency wrapper around the REST API.
It ships both a programmatic client and a figviz CLI. Source and full changelog
live on npm: @figviz/figviz-sdk.
Get an API key
Create a key (new accounts include 8 free credits) at
Settings > API. Figviz is pay-as-you-go — no subscription, and
credits never expire. Every key begins with the fvk_ prefix.
A key spends real credits. Keep it server-side and never ship it in a browser or mobile bundle.
Install
npm install @figviz/figviz-sdkRequires Node.js 18+ (it uses the built-in fetch).
Quickstart
import { createFigviz } from '@figviz/figviz-sdk';
const figviz = createFigviz({ apiKey: process.env.FIGVIZ_API_KEY! });
const { images, credits_remaining } = await figviz.generate({
prompt: 'labeled animal cell cross-section for 7th grade',
quality: '2k', // '1k' | '2k' | '4k' (4k costs 2 credits)
aspectRatio: '4:3', // optional, e.g. '16:9', '1:1', '4:3'
});
console.log(images[0].url, `(${credits_remaining} credits left)`);Batch
Pass prompts to render up to 4 diagrams in a single call. The returned images
array preserves prompt order.
await figviz.generate({
prompts: ['water cycle diagram', 'nitrogen cycle diagram'],
});Errors
Failed calls throw a FigvizError carrying the HTTP .status and a machine-readable
.code. For example, 402 / INSUFFICIENT_CREDITS means the balance is too low —
top up at /pricing. See the API error table for every code.
import { createFigviz, FigvizError } from '@figviz/figviz-sdk';
try {
await figviz.generate({ prompt: 'mitosis four-stage sequence' });
} catch (err) {
if (err instanceof FigvizError && err.status === 402) {
console.error('Out of credits — buy a pack at /pricing');
} else {
throw err;
}
}CLI
The package also installs a figviz command. Run it without installing via npx:
# one-off
FIGVIZ_API_KEY=fvk_xxx npx @figviz/figviz-sdk "labeled plant cell for 8th grade"
# pick resolution + aspect ratio, save to a file
npx @figviz/figviz-sdk "convex lens ray diagram" --quality 2k --aspect 16:9 --out lens.pngOptions: -q/--quality 1k|2k|4k, -a/--aspect <ratio>, -o/--out <file>,
--json, -h/--help.
Using your AI assistant instead?
If you want to generate diagrams from Claude Desktop, Cursor, or another AI client, use the MCP server — no code required.