Generate vector SVG diagrams using the POST /rest/v1/generations endpoint.
Endpoint Details
- Method:
POST - Path:
/rest/v1/generations - Base URL:
https://svgdiagram.ai
Request Body Parameters
{
"prompt": "Sequence diagram of OAuth2 Authorization Code flow with PKCE",
"design": "auto",
"appearance": "light",
"fontId": "inter",
"colors": {
"source": "automatic"
},
"options": {}
}| Field | Type | Description |
|---|---|---|
prompt |
string |
Required. Natural language brief describing the diagram content, structure, steps, or components. |
design |
string |
Optional. Selection mode or specific design ID: "auto" (default), "creative", or a published design ID (e.g. timeline-zigzag-icon-cards). |
appearance |
string |
Optional. Neutral appearance mode: "light" or "dark". |
fontId |
string |
Optional. Bundled font: "inter", "source-sans-3", "archivo", or "barlow-condensed". |
colors |
object |
Optional. Selects automatic, brand, saved-palette, or custom-palette colors. Each source accepts a different object shape; see examples below. |
options |
object |
Optional. Key-value option overrides for specific published designs. |
Valid colors examples:
{ "source": "automatic" }
{ "source": "custom", "palette": ["#6366f1", "#10b981"] }
{ "source": "brand", "name": "Product", "palette": ["#6366f1", "#10b981"], "fontId": "inter" }
{ "source": "palette", "paletteId": "<palette-uuid>" }
{ "source": "saved", "palette": ["#6366f1", "#10b981"], "name": "Product" }brand accepts optional name, palette, and fontId; saved accepts optional name. custom and saved require a palette of 1–8 #rgb or #rrggbb values.
Design Selection Modes
svgdiagram.ai supports two distinct generation paths:
- Automatic (
design: "auto"): The model evaluates published stable designs in the catalog. If a published design fits the request, it populates its structural parameters. If no published design fits, it seamlessly routes to the creative sandbox. - Creative Sandbox (
design: "creative"): The model generates custom, free-form vector JSX rendered in an isolated sandbox environment. - Named Design ID (
design: "<id>"): Explicitly names a published design (for example,timeline-zigzag-icon-cards). Use an ID returned byGET /rest/v1/designs.
Query available published catalog designs using GET /rest/v1/designs.
Diagram Refinement & Iteration
Refine a completed creative diagram by passing its ID in from and a refine instruction:
{
"from": "e8b21c40-3a52-4f81-8b09-1a052e690f12",
"refine": {
"instruction": "Add a Redis caching layer between the API gateway and microservices"
}
}Alternatively, adjust detail density relatively:
{
"from": "e8b21c40-3a52-4f81-8b09-1a052e690f12",
"refine": {
"detail": "more"
}
}- Refinements cost 1 credit.
- Retries and refinements preserve parent context and produce child attempts linked by
rootId.