A graph is a JSON object made of nodes (blocks) connected by links between ports. The blocks actually available are those of GET /pipelines/capabilities.
Example
Layout blocks detect the regions; the condition sends tables to model_max and everything else to model_fast.
{
"schema_version": 1,
"kind": "ocr",
"nodes": [
{ "id": "in", "type": "input" },
{ "id": "n1", "type": "layout" },
{ "id": "n2", "type": "condition", "params": { "test": "table" } },
{ "id": "n3", "type": "model_max" },
{ "id": "n4", "type": "model_fast" },
{ "id": "out", "type": "output" }
],
"links": [
{ "from": "in", "port": "out", "to": "n1" },
{ "from": "n1", "port": "out", "to": "n2" },
{ "from": "n2", "port": "yes", "to": "n3" },
{ "from": "n2", "port": "no", "to": "n4" },
{ "from": "n3", "port": "out", "to": "out" },
{ "from": "n4", "port": "out", "to": "out" }
]
}
Rules
- A single
inputnode and a singleoutputnode. ids are unique; at most one link per (from,port) pair.- All ports of a
conditionorconfidenceblock must be connected. - No cycles.
- A single block of the layout family per path, placed before the models.
conditionrequires a layout block upstream.- The
handwrittenandprintedtests require ahandwritten_detectblock upstream on every path (otherwiseinvalid_paramon the condition). model_maxis rejected downstream of alayout_word, on at least one path, including through a condition (422 forbidden_block_sequence).- Visual fields (
x,y,label,caption) are ignored.
OCR blocks
| type | Ports | params | Model |
|---|---|---|---|
layout | out | word_boxes, line_boxes (all), line_boxes_method 9 / 10 (same as word_boxes_method), line_params | AlphaLayout (PP-DocLayoutV3) |
layout_word | out | handwritten_threshold 0–1 (default 0.5) | AlphaLayout-Word |
layout_line | out | limit_side_len 32–8000 (default 1280) | AlphaLayout-Line |
handwritten_detect | out | — | alpha-writing-detect |
model_max | out | extraction, extraction_prompt (not executed for now) | alpha-digit-max |
model_fast | out | — | alpha-digit-fast |
model_handwritten | out | — | alpha-digit-handwritten |
condition | yes, no | test among the capabilities' condition_tests | none (logic) |
confidence | high, low | threshold 0–100, in steps of 5 (default 80) | none (logic) |
After layout_word or layout_line, the table, image, text, header, footer and aside tests always answer "no".
layout_word creates one region per word: placed before an OCR model, it triggers one invocation per word (slow on dense documents).
Layout blocks no longer classify writing (writing_type is unknown): handwritten_detect goes after a layout and classifies each region as handwritten or printed; before the OCR model, it gives it the handwriting hint.
line_boxes adds its lines to each region (regions[].lines: text, start, end, bbox_xyxy, polygon, writing_type) and returns lines without text in unmatched_line_boxes.
Audio blocks
| type | Ports | params |
|---|---|---|
diarization | out | min_speakers, max_speakers (1–32) |
transcription | out | model_slug (default alpha-audio-v1) — this block is required in the graph |
confidence | high, low | threshold (default 85) |
postcorrect | out | — (available only if listed in the capabilities) |
pipeline_hash
The hash is the sha256 (lowercase hexadecimal) of the canonical form of the graph: sorted keys, no spaces, UTF-8, nodes sorted by id, links sorted by (from, port), params only when non-empty. Only schema_version, kind, nodes[id, type, params] and links[from, port, to] count.
When sent with the graph, it is checked: any difference returns 422 hash_mismatch. It also appears in responses and in run.started.
import hashlib, json
def pipeline_hash(graph: dict) -> str:
canonical = {
"schema_version": graph["schema_version"],
"kind": graph["kind"],
"nodes": sorted(
({"id": n["id"], "type": n["type"], **({"params": n["params"]} if n.get("params") else {})}
for n in graph["nodes"]),
key=lambda n: n["id"],
),
"links": sorted(
({"from": l["from"], "port": l["port"], "to": l["to"]} for l in graph["links"]),
key=lambda l: (l["from"], l["port"]),
),
}
raw = json.dumps(canonical, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
return hashlib.sha256(raw.encode("utf-8")).hexdigest()
{"kind":"ocr","links":[{"from":"in","port":"out","to":"n1"},{"from":"n1","port":"out","to":"n2"},{"from":"n2","port":"yes","to":"n3"},{"from":"n3","port":"out","to":"out"}],"nodes":[{"id":"in","type":"input"},{"id":"n1","type":"layout"},{"id":"n2","params":{"test":"table"},"type":"condition"},{"id":"n3","type":"model_max"},{"id":"out","type":"output"}],"schema_version":1}
sha256 → 96c6be3b3fd6e5b48ae6100dbc1e53aacba50ca9400252d02d39864b539e489e
Test vector: graph in → layout → condition(table) → model_max → out, ids in, n1, n2, n3, out. This graph gives the canonical form above.
Validation error codes
Possible codes in error.errors[]:
| Code | Meaning |
|---|---|
unsupported_schema_version | schema_version not supported |
unknown_block_type | Unknown block type |
unknown_param, invalid_param | Unknown or invalid parameter |
missing_input, missing_output | input or output node missing |
duplicate_node_id, duplicate_link | Duplicate identifier or link |
unknown_port, dangling_port | Unknown port, or port with no continuation |
unreachable_node | Unreachable node (warning) |
graph_cycle | The graph contains a cycle |
no_model_on_path | No model on a path |
condition_without_layout | condition without layout upstream |
confidence_without_model | confidence without model upstream |
transcription_required | Audio graph without a transcription block |
invalid_block_order | Invalid block order |
hash_mismatch | pipeline_hash differs from the graph |
limit_exceeded | Limit exceeded (nodes, links, size) |