Compositor (compv3) headless contract

Drive the free compv3 compositor over the API: node config shape, layers, stage size and the rendered PNG output.

Last updated View as MarkdownAgent setup

The compositor (compv3) renders layered images/text/shapes to a single PNG at a fixed canvas ("stage") size. Rendering is free (no AI credits) and returns a durable cdn.wireflow.ai URL. This page is the contract for driving it via the API.

Node config shape

The canonical location is node.data.config:

{
  "nodeType": "compv3",
  "config": {
    "stage": { "width": 1080, "height": 1350 },   // canvas size in px
    "layerOrder": ["bg", "headline", "logo"],       // back-to-front draw order
    "layers": {
      "bg":       { "type": "image", "x": 0, "y": 0, "width": 1080, "height": 1350, "fit": "cover" },
      "headline": { "type": "text",  "text": "HEADLINE", "x": 70, "y": 900, "width": 940, "fill": "#fff", "fontFamily": "Anton", "fontSize": 120 },
      "logo":     { "type": "image", "x": 820, "y": 60, "width": 180, "height": 180, "fit": "contain" }
    }
  }
}

Layer types: image, text, rectangle, gradient, draw, shape. The editor-state shape data: { stage, layers, layerOrder } is also accepted, but config.* is canonical — author there.

Binding: a layer receives dynamic content by key (no {{tokens}}). An incoming edge whose target handle is the layer key, or a value under that key in the data batch port / inputs, overrides the layer: a string sets .text for a text layer or .url for an image layer. A URL-shaped string (http(s):, data:, blob:) is always an image, even on a text layer; any other string wired into a text layer (or into an untyped layer with no image url) is its text. A wired or data string wins over text typed in the editor, so a template typed by hand still swaps per run. An upstream layer object (e.g. layerize-text output) does not overwrite typed text; the run's warnings say when that happened.

Fonts

fontFamily on a text layer resolves in this order, identically in the editor canvas and the server render (the HTML export serves hosted and Google fonts only):

  1. Hosted fonts shipped with Wireflow: Veelo Neue (weights 100, 200, 300, 400, 500, 700, 800, 900; an unshipped weight uses the nearest by CSS rules).
  2. Google Fonts, any family, weights 100–900.
  3. Your registered fonts: upload the file with POST /api/v1/media/upload, then register it with POST /api/v1/fonts (family, weight, style, url). Only your own renders can use it; another account naming the same family gets its own file or the fallback.

A family none of these can serve renders in Inter, and the run's failedFonts and warnings name the family and the layers that fell back.

fontStyle: "italic" loads the family's real italic file (Instrument Serif Italic is a different drawing from its roman, not a slanted copy), and fontWeight loads that exact weight. When the family does not ship the face a layer asks for (Anton has no italic, Instrument Serif has one weight), the text stays in that family and draws its nearest face, style first, the way a browser picks: an italic 800 of Instrument Serif draws its italic 400, and an italic Anton draws the roman with a synthesized slant. The editor and the PNG draw the same face, and warnings names the face, the substitute and the layers.

Gradient text

fill is a colour string or a fill object, and a text layer takes the same gradient object a rectangle does. The ramp is painted through the glyphs, clipped to the letters, in the editor, the PNG bake, the export and the HTML export. A vertical purple ramp through a headline:

{
  "type": "text",
  "text": "GRADIENT",
  "x": 70,
  "y": 900,
  "fontFamily": "Anton",
  "fontSize": 160,
  "fill": {
    "kind": "linear",
    "angle": 0,       // degrees: 0 = top to bottom, 90 = left to right
    "span": "box",    // ramp runs edge to edge; omit for the legacy half-diagonal
    "stops": [
      { "offset": 0, "color": "#8269FA" },
      { "offset": 1, "color": "#5040F2" }
    ]
  }
}
  • Radial: { "kind": "radial", "cx": 0.5, "cy": 0.5, "r": 0.5, "stops": [...] }. cx/cy are fractions of the box, r a fraction of its longer side.
  • kind is required. Stops are { offset, color }, offsets clamped to 0..1 and sorted; alpha goes in the colour (rgba(...)). Fewer than two valid stops renders solid black.
  • The ramp spans the text's own ink box, so it stays on the letters when the string changes length.
  • A gradient on text is refused together with stroke or shadowColor: the HTML export cannot paint those under a clipped gradient. Use a solid fill with them.
  • Image layers do not paint fill.

Borders, sticker outlines and vector shapes

Rectangle border. stroke (colour) and strokeWidth (px, default 1 when only stroke is set) draw a border that follows cornerRadius. strokeAlign is "inside" (default: the border stays inside the declared box, like Figma and CSS border-box), "center" or "outside". A stack frame with a stroke and no fill is a border only.

{ "type": "rectangle", "x": 60, "y": 70, "width": 640, "height": 420, "cornerRadius": 28,
  "fill": "rgba(255,255,255,0.06)", "stroke": "#FFFFFF", "strokeWidth": 3 }

Sticker outline. outline: { color, width } on an image layer draws a border along the image's alpha edge, under the image: a cutout gets a die-cut sticker border, smooth at any width (max 200). With a drop shadow set, the outlined silhouette casts it. Do not fake it with stacked offset copies.

{ "type": "image", "x": 860, "y": 150, "width": 420, "height": 420, "fit": "contain",
  "outline": { "color": "#FFFFFF", "width": 14 } }

Vector shape. type: "shape" draws a crisp filled vector. Give one of preset: "cursor" (the arrow pointer, drawn at the layer's width/height), points: [x0,y0, x1,y1, ...] (a closed polygon) or path: "M0 0 L40 0 ..." (SVG path data). points and path are in layer px from x/y; scale them with scaleX/scaleY. Paint with fill (colour or gradient), stroke and strokeWidth (centred, round joins). Omit fill and set stroke for an outline-only shape.

{ "type": "shape", "preset": "cursor", "x": 640, "y": 380, "height": 64,
  "fill": "#111111", "stroke": "#FFFFFF", "strokeWidth": 4 }

All three render identically in the editor, the client export and the PNG bake. The HTML export draws borders and shapes; it does not draw sticker outlines and says so in warnings.

An image or shape that runs past the stage edge is reported once in warnings as a bleed (cropped at the edge, often deliberate); text that overflows gets text advice.

Image fit modes (sizing to the layer box)

Every image layer with an explicit width and height is scaled to that box:

fit behavior
cover fill the box, crop overflow (preserves aspect)
contain fit inside the box, letterboxed (preserves aspect)
fill / stretch stretch to the box exactly (ignores aspect)
(unset, sized layer) defaults to contain — honors the box, never overflows
(unset, no box) native size (full-bleed)

Set fit explicitly when you want crop (cover) or stretch (fill). A sized layer with no fit now scales into its box (previously it drew at the source's natural resolution and could overflow the layout).

Setting an input:image node's media via the API

You do not need a human to drag-and-drop. Set the URL in the node's config when you create/PUT the workflow — any of these fields works (first present wins): imageUrl, image, mediaUrl, videoUrl, url.

{ "nodeType": "input:image", "config": { "imageUrl": "https://cdn.wireflow.ai/your-asset.png" } }

The node then resolves as an upstream media source for downstream nodes (compositor layers, generators, etc.) headlessly.

Headless preview (true export, no billed run)

Render a compositor to a PNG at stage resolution without running the workflow:

POST /api/v1/workflows/:id/compositor/preview
Authorization: Bearer <API_KEY>          # scope: workflows:execute
{
  "nodeId": "comp",                        // optional — defaults to the first compv3
  "inputs": { "bg": "https://…/photo.png" },  // optional per-layer-key port values
  "layers": { … },                          // optional — override the saved layout
  "layerOrder": ["bg","headline"],          // optional
  "stage": { "width": 1080, "height": 1350 }// optional — override the canvas size
}
→ 200 { "data": { "nodeId", "url", "width", "height", "inputsHash", "warnings?", "failedImages?", "failedFonts?" } }

Use it to iterate on a layout and see the real output before committing or running the graph. The returned url is a durable CDN PNG. Empty body previews the node exactly as saved.

Discovering the contract programmatically

GET /api/v1/workflows/:id/schema returns a compositors[] array describing each compv3 node: nodeId, label, stage, the layers (key + type + whether AI-bindable), and where the output image lands. Call it instead of reverse-engineering.

Notes

  • A compositor's output is cached and reused on re-run only while its inputs and stage size are unchanged — a stage resize re-renders at the new size.
  • Normalization re-adds a canonical layer_1 input port to compv3 nodes (a defensive default to avoid dangling edges); an empty one is harmless — just leave it or wire/override the keys you use.

Related

  • Compositor

    Compose layers of images, text, and video. A layer (including one inside a stack `itemTemplate`/`itemTemplates`) can take a WIRED asset with `\"url\": \"$port:<name>\"`, saving mints a real image input port called `<name>`; never bake a CDN URL into a layer. Full layout contract (sizing, anchors, stacks, variants, `$port:`): GET /api/v1/workflows/{id}/schema

  • Batch images

    Mass-produce on-brand images from one reusable layout — one Compositor template, N outputs.

  • Video Editor contract

    Read the contract a Video Editor node renders against, for both template mode and sceneGraph mode.

  • Media uploads

    Get a local file onto the Wireflow CDN so you can wire it into a workflow. Inline for small files, presigned direct-to-R2 for anything up to 25MB, or 100MB for video.

For AI agents: the full documentation index is at /llms.txt, and most docs pages are available as Markdown by adding .md to the URL.

© 2026 Wireflow. All rights reserved.