Workflow

Workflow

The node graph behind every Onepin workflow — the three node families and how lines flow between them.

Every workflow is a definition: a graph of typed nodes connected by edges. A line of script enters at one end, passes through the nodes you wire up, and leaves as finished audio. When you clone a template you get a ready-made graph; to change what it says, who speaks, or what comes out, you edit node config objects.

definition
├── graph
│   ├── nodes[]   — id (UUID), type, name, position, config
│   └── edges[]   — id, source, sourcePort, target, targetPort
└── execution     — run-time settings

The three node families

Every node belongs to one of three families. Open a node for what it does, its config, and how to inspect it live.

FamilyWhat it doesNodes
SourceBrings script inScript
OperatorTransforms linesTranslator · Normalizer · Generator · validators (Accuracy, Naturalness, Noise)
SinkSends the result outExport

The names above are what you see on the canvas. In a definition’s JSON, each node’s type carries its internal id — source_script, processing_translator, processing_booster (the Normalizer), processing_generator, validator_error_rate (Accuracy), validator_naturalness, validator_noise, sink_preview (Export). Use the type strings when you author a definition by hand; run onepin nodes list to see them all.

How lines flow

Every edge carries lines. A line is one piece of script plus its language, and it picks up more as it moves through the graph:

Script → (translated) → (normalized) → Generator → validators → Export
 text        text            text        + audio    + scores    downloaded

A port only accepts a line that already carries what it needs. Export, for example, requires audio — and only the Generator adds audio — so a Generator always sits upstream of Export. Onepin checks these connections when you save; an edge that can’t carry what the next node needs is rejected with a clear message. See General rules for the full set.

Editing a definition

Definitions are replaced whole, not merged — so the reliable pattern is read → modify → write back:

1definition = client.workflows.get(workflow_id=workflow_id).data.model_dump()["definition"]
2for node in definition["graph"]["nodes"]:
3    if node["type"] == "source_script":
4        node["config"] = {"input_type": "text", "source_language": "en-us", "text": "..."}
5client.workflows.patch_workflow(workflow_id, definition=definition)

The Run a workflow guide walks this end to end. Authoring a definition from scratch (client.workflows.create_workflow / onepin workflows create --definition @file.json) follows the same schema — start from onepin workflows definition-schema.

Estimating cost before running

$onepin workflows preview-run <WORKFLOW_ID>     # estimate a run without executing it

Also available per template (GET /api/v1/templates/{id}/estimate) and via the SDK (client.workflows.preview_run, client.workflows.estimate_workflow).