Nodes & specs
The node palette, node specs, connectors, and why you should never guess inputs.
Nodes are the executable units of a workflow: hosted models, LLMs, media utilities. The node palette is the catalog of everything you can run, and each entry is described by a node spec.
In a workflow, a node's input ports are fed by other nodes (or by workflow inputs) and its output ports feed the next node:
You can also run a node on its own — same ports, no graph.
Node specs
A spec describes a node's exact interface — its identity (id, kind,
display metadata) and its inputs / outputs ports:
{
"id": "rd-fast",
"kind": "model",
"title": "RD Fast",
"category": "image",
"description": "Fast image generation…",
"inputs": {
"prompt": {
"name": "prompt",
"connector": { "id": "TEXT", "isOptional": false, "isArray": false }
},
"style": {
"name": "style",
"connector": {
"id": "TEXT",
"isOptional": true,
"isArray": false,
"defaultValue": "game_asset",
"optionValues": ["game_asset", "character_turnaround", "item_sheet"]
}
}
},
"outputs": {
"image": {
"name": "image",
"connector": { "id": "IMAGE", "isOptional": false, "isArray": false }
}
}
}The same spec, rendered as the interface a caller programs against:
Each port's connector carries the type and constraints:
| Connector field | Meaning |
|---|---|
id | IMAGE, TEXT, AUDIO, VIDEO, FLOAT, INT, BOOLEAN, EMBEDDING, FILE, STRUCTURED, or CUSTOM:<name> |
isOptional | Whether the port may be omitted |
isArray | Whether the port takes a list |
defaultValue | Default used when the port is omitted |
optionValues | Allowed enum values, when constrained |
minValue / maxValue | Numeric bounds, when constrained |
Discover before you call
Never guess inputs or enum values. Fetch the node's spec first and build
your inputs from its inputs ports. Enum names (style, modes, sizes) are
not guessable, and a value outside optionValues fails validation before
anything runs.
The palette is searchable — filter by free text and category, then inspect the candidate:
# search
curl "https://studio.blitflow.com/api/v1/nodes?q=sprite&category=image" \
-H "Authorization: Bearer $BLITFLOW_TOKEN"Via the SDK use searchNodes / getNode (SDK: nodes); via
MCP use the nodes_list / nodes_get tools (MCP tools).
Practical tips
- Reproducibility — if a node exposes a
seedinput, set it. Same seed + same inputs → same output; hold the seed while iterating a prompt. - Respect locked modes — some model modes fix output dimensions or formats. Read the spec's defaults and bounds instead of fighting them.
- Prefer the cheapest node that clears the bar — step up to a higher-fidelity (more expensive) node only when quality actually demands it.