Flows
Join some of a template's pages into one video, with a transition into each page.
list_flows
A template's flows. A flow joins some of its pages into one video with transitions; the Kalpana app calls a flow a video. A template can have any number, each with its own pages and order.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
template_id | string | Yes | — | The template. |
- Returns: Each flow's
flow_id, name, description, length inseconds,steps, and itswidth,heightand background when set. Give aflow_idto the batch toolscreate_batchasflowto render it. A flow longer than a video renders carries awarning.
create_flow
Add a flow to a template: some of its pages, in the order you give, joined by transitions into one video. Edits to the pages not yet saved are saved first. By default a page holds for its own duration, so give each page its motion before adding a flow, or update the flow after. Returns the flow with its flow_id and length.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
template_id | string | Yes | — | The template. |
name | string | Yes | — | The flow's name. |
description | string | No | — | What this cut of the video is for. |
steps | object[] | Yes | — | The pages in order, 1 to 100. A page can come twice. |
width, height | number | No | The first page's | The video's size. |
background | string | No | Near-black | What shows between pages during a fly: #RRGGBB, or page for the first page's look. |
background_gradient | string[] | No | — | Two to six #RRGGBB colours to show between pages as a gradient, in place of background. |
Each step:
| Field | Type | Required | Description |
|---|---|---|---|
page_id | string | Yes | The page, from list_pages. |
hold | number | No | Seconds on this stop after its transition. A stop lasts its transition plus its hold, and the page's motion starts when its transition starts. Left out, it is the page's duration minus the transition (at least 0.5 s) and follows the page when it changes; a still page or a layer_id close-up holds 2 s. |
transition | object | No | How the video arrives here. Ignored on the first step. Left out: a dissolve. |
layer_id | string | No | Close in on this layer instead of showing the whole page. |
padding, zoom | number | No | Framing for a close-up. |
show_finished | boolean | No | Coming back to a page: skip its animation and show it at its still time, or where its motion ends without one. |
A transition:
| Field | Type | Description |
|---|---|---|
type | string | fly, morph, dissolve, cut, push, cover, wipe, dip, zoom, zoom_through, blur, whip, flip, cube, iris, clock, flood, rings, stripes, blades, burst or pixel. |
seconds | number | Its length, 0.05 to 10. Left out: the type's usual length. |
style | string | smooth, gentle, snappy or bouncy. |
direction | string | Which way a push, cover, wipe, whip, flip, cube or pixel moves: left, right, up or down; stripes take left or right. Default left. |
color | string | The colour of a dip, flood, rings, stripes, blades, burst or pixel as #RRGGBB. Default black. |
opacity | number | How solid the colour is, 0 to 1. Below 1 the pages show through and fade across. |
gradient | string[] | Two to six #RRGGBB colours to use in place of color. |
gradient_angle | number | Turns the gradient, degrees clockwise. |
count | number | How many rings (2 to 6), stripes (2 to 24) or burst rays (4 to 40). |
angle | number | A stripe's lean, -60 to 60, or where a clock starts, degrees clockwise from 12. |
anticlockwise | boolean | On a clock: the hand turns anticlockwise. |
size | number | A pixel block (0.02 to 0.25) or burst ray (0.004 to 0.06), as a share of the page's long side. |
origin | number[] | Where an iris, flood, rings or burst starts: [x, y] as fractions of the page. |
order | string | Which way a pixel's rows set off: random, in_order or centre. |
panels | string | Where blades close from: sides, top_bottom or corners. |
tilt_x, tilt_y | number | A fly's lean in degrees. |
travel | boolean | On a morph: the pages also slide the way they sit on the board. |
Every type except fly, morph, dissolve and cut needs whole pages on both sides, so it can't go to or from a step with layer_id.
update_flow
Change a flow. Fields left out keep their values. steps replaces the whole list, so read it with list_flows first.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
template_id | string | Yes | — | The template. |
flow_id | string | Yes | — | The flow, from list_flows. |
name, description, steps, width, height, background, background_gradient | No | — | As in create_flow. |
delete_flow
Delete a flow. Its pages stay in the template, and videos already rendered from it stay.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
template_id | string | Yes | — | The template. |
flow_id | string | Yes | — | The flow, from list_flows. |
Updated 9 Nov 2026