Compositor (compv3) headless contract
Drive the free compv3 compositor over the API: node config shape, layers, stage size and the rendered PNG output.
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):
- 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). - Google Fonts, any family, weights 100–900.
- Your registered fonts: upload the file with
POST /api/v1/media/upload, then register it withPOST /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/cyare fractions of the box,ra fraction of its longer side. kindis 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
strokeorshadowColor: 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
fitexplicitly when you want crop (cover) or stretch (fill). A sized layer with nofitnow 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_1input 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.