# Generation API Generate template SVGs, background SVGs, element briefs and apply-ready Design Lab documents with POST /api/generate and its versioned JSON contract. `POST /api/generate` accepts a JSON body with `Content-Type: application/json`. The `kind` field selects one of four generators: `template` (the default), `background`, `element-brief` and `design-sequence`. `GET /api/generate` returns the current contract (`schemaVersion` 3) with the request schema, value ranges and examples. Read it before building a request. A top-level field that the contract does not define is rejected with `unknown_field`. ## Output [#output] * `template` and `background` return a JSON envelope by default (`output: "json"`). The SVG is in `artifact.content`. * `output: "raw"` returns the SVG itself as `image/svg+xml`. * `element-brief` and `design-sequence` always return JSON. Successful responses send `Cache-Control: no-store` and a `Content-Disposition` header with the file name. ## Design sequence [#design-sequence] A `design-sequence` request builds a document for Design Lab, the Studio's layered composition tool. The document holds a shader sequence: a series of cuts through other materials that ends on the chosen material and holds it. The composition can also include the identity's brand mark, text layers and one converter effect. ```json { "kind": "design-sequence", "identity": { "preset": "gt" }, "ratio": "wide", "backgroundColor": "#111216", "shader": { "materialId": "paper-gem-smoke", "shaderSize": 1 }, "sequence": { "cutCount": 10, "finalHoldMs": 5000, "pace": "accelerating" }, "effect": { "kind": "bayer", "opacity": 0.76, "foreground": "#F5F5F2", "background": "#111216" }, "texts": [{ "value": "Open Source", "weight": 500 }], "export": { "width": 1920, "fps": 30, "quality": "best" } } ``` | Field | Values | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `shader.materialId` | Any ID listed by `/api/materials` (default `paper-gem-smoke`). Retired material IDs are rejected | | `shader.shaderSize` | Material zoom from 0.1 to 10 (default 1) | | `shader.opacity`, `shader.blendMode` | 0–1; `normal`, `multiply`, `overlay` or `screen` | | `shader.settings` | Shared material controls from `/api/materials`, and `effectProps` for Shaders.com materials | | `sequence.cutCount` | 8–12 cuts (default 10) | | `sequence.finalHoldMs` | 3000–6000 ms (default 5000) | | `sequence.pace` | `accelerating` (default) or `even` | | `effect.kind` | `bayer` (default), `ascii`, `halftone` or `posterize`, with `opacity`, `foreground`, `background` and converter settings | | `texts` | Up to 32 text layers, each with a `value` of up to 1000 characters | | `includeBrandMark` | `true` by default. An identity without a mark gets a monogram | | `ratio` | `wide` (default), `square` or `opengraph` | | `backgroundColor` | Six-digit HEX (default `#111216`) | | `export` | `width` 320–3840, `fps` 12, 15, 24 or 30, `quality` `fast`, `balanced` or `best`, `durationMs` 1200–4000, `gifLoop` `raw` or `seamless` | Image effects are not part of this request. Add them in the browser with `design.effects.add` after the document is applied. The response is JSON with these fields: * `schemaVersion: 1`: the version of the response envelope. * `document`: an apply-ready Design Lab compatibility source with `version: 3`. * `sequence.timeline` and `sequence.durationMs`: the resolved material IDs and cut boundaries. * `automation`: the browser global and the exact apply and export commands. `document.version` is not the active canvas schema. `applySource(response.document)` validates and migrates the compatibility source. The Design Lab adapter then exposes the normalized result as CanvasDocument schema 2 with Design Lab metadata source version 4. Read the source again after applying it and before making targeted CanvasDocument edits. When the document is applied, Design Lab keeps `export.durationMs` only if it is 1200, 1600, 2400 or 4000 and uses 1600 otherwise. Apply and render inside `/studio?tool=material`: ```js await window.glyphfield.studio.applySource(response.document); const artifact = await window.glyphfield.studio.invoke( 'design.export', { format: 'mp4', mode: 'shader-sequence', download: true } ); ``` Choose `png`, `jpg`, `gif` or `mp4`. `mode: 'shader-sequence'` works with GIF and MP4 only. The export action resolves to the same artifact object that the UI produces, rendered with the live shader canvases, composition effects, text, marks, layer order and output settings. `download: true` also saves the file. ## Templates [#templates] The `template` kind renders the Studio's brand templates as standalone SVG: OpenGraph images, terminal cards, slides, blog covers and partnership lockups. It uses the same layouts and renderer as the Studio and embeds the brand's font files and images, so the SVG renders in the brand typeface inside a plain `` element. A font whose data URL is longer than 560,000 characters is not embedded. Each request renders one page. When a request leaves out copy, the identity fills it in. Proof figures fill metrics slides, strategy pillars fill agenda slides, and the identity's own proof partner fills lockups. A lockup without a partner shows the placeholder text “Partner”. ```json { "kind": "template", "template": "slides", "slideLayout": "agenda", "texture": "white", "title": "One system, every market.", "body": "Foundation\nExpression\nApplication\nDelivery", "identity": { "preset": "gt" }, "output": "raw" } ``` | Field | Values | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `template` | `slides` (default), `blog`, `partnership`, `opengraph` or `terminal` | | `slideLayout` | Slides only: `title`, `section`, `agenda`, `split`, `metrics`, `quote`, `timeline`, `statement`, `comparison`, `process`, `chart`, `team`, `image` or `closing` | | `layout` | `opengraph`: `split`, `statement`, `media`, `centered`, `editorial`. `blog`: `editorial`, `feature`, `statement`, `centered`, `ledger`. `terminal`: `card`, `split`, `focus`, `caption`. `partnership`: `lockup`, `centered`, `hero`, `announcement`. Slides also accept `layout`, and sending both `layout` and `slideLayout` is an error | | `format` | `opengraph`, `wide`, `square`, `portrait`, `story`, `linkedin` or `lockup`. Slides use `16x9`, `4x3` or `square` | | `texture` | `white`, `dark`, `grid` or `noise` | | `language` | Terminal only: `typescript`, `tsx`, `javascript`, `python`, `bash`, `json`, `html` or `css` | | `title` | 1–240 characters | | `body` | 1–1000 characters, or 4000 for `terminal`. Slides read one list item per line, terminal cards read it as code, and other layouts use it as supporting copy where they have a slot for it | | `background`, `foreground` | Six-digit HEX colors for the page surface and for every text layer | | `backgroundImageDataUrl`, `partnerLogoDataUrl` | Base64 image data URLs of up to 5,000,000 characters | | `partnerId` | For `partnership`: a proof asset ID of the identity, another built-in identity ID, or `template-northstar` | | `output` | `json` (default) or `raw` | The default size is 1600 × 900 for slides, 1200 × 630 for OpenGraph, terminal and blog, and 1200 × 600 for partnership. `format` changes it. The file name is `-