Flows

const flows = await hc.flows.list();

flows = hc.flows.list()

curl $HYPERCLIP_BASE_URL/flows \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY"

{
  "flows": [
    {
      "id": "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
      "title": "3-shot horror story",
      "description": "Script → parse scenes → image → video → voiceover → export",
      "updated_at": "2026-04-15T12:00:00Z"
    }
  ]
}

const flows = await hc.flows.list();

flows = hc.flows.list()

curl $HYPERCLIP_BASE_URL/flows \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY"

{
  "flows": [
    {
      "id": "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
      "title": "3-shot horror story",
      "description": "Script → parse scenes → image → video → voiceover → export",
      "updated_at": "2026-04-15T12:00:00Z"
    }
  ]
}

A flow is a workflow you’ve built in the visual editor — a graph of nodes that describes how to produce a video. The API exposes your saved flows for listing and reference, and also accepts inline flow schemas for callers who want full control without persisting state.

GET /flows

List flows the authenticated user owns (plus any public flows they’ve saved).

string

required

Requires flows:read scope (included in default key scopes).

Response

array

Show Flow item

string (uuid)

required

string

required

string | null

string (ISO 8601)

required

const flows = await hc.flows.list();

flows = hc.flows.list()

curl $HYPERCLIP_BASE_URL/flows \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY"

{
  "flows": [
    {
      "id": "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
      "title": "3-shot horror story",
      "description": "Script → parse scenes → image → video → voiceover → export",
      "updated_at": "2026-04-15T12:00:00Z"
    }
  ]
}

GET /flows/:id

Fetch a single flow’s full FlowSchema plus a summary of the inputs it expects from API callers.

string (uuid)

required

Response

string

required

string

required

string | null

object

required

The canonical FlowSchema. Nodes + edges, exactly as saved from the editor. See inline FlowSchema below for the shape.

array

Derived list of which steps expect a prompt or media input. Use this to drive your integration’s UI so users know what they need to supply.

Show required_inputs item

integer

required

string

required

e.g. "text_input", "media_input".

string

required

"prompt" or "media" — which input field this step expects in POST /runs.

array

Only present when field is "media". Any of "image", "video", "audio" — the type you send for this step in inputs.media[step_order] must be one of these.

const flow = await hc.flows.get("a3c7f1ea-1234-4abc-bb11-5faed63c7e90");
console.log("Required inputs:", flow.required_inputs);

flow = hc.flows.get("a3c7f1ea-1234-4abc-bb11-5faed63c7e90")
print("Required inputs:", flow["required_inputs"])

curl $HYPERCLIP_BASE_URL/flows/a3c7f1ea-... \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY"

{
  "id": "a3c7f1ea-...",
  "title": "3-shot horror story",
  "description": "...",
  "flow_schema": {
    "version": 1,
    "nodes": [
      { "id": "node-0", "type": "text_input",          "label": "Story prompt",   "position": { "x": 0,   "y": 100 }, "config": {} },
      { "id": "node-1", "type": "script_generation",   "label": "Write script",   "position": { "x": 300, "y": 100 }, "config": { "model": "grok-fast" } },
      { "id": "node-2", "type": "parse_scenes",        "label": "Parse scenes",   "position": { "x": 600, "y": 100 }, "config": {} },
      { "id": "node-3", "type": "split",               "label": "For each scene", "position": { "x": 900, "y": 100 }, "config": {} },
      { "id": "node-4", "type": "image_generation",    "label": "Scene image",    "position": { "x": 1200,"y": 100 }, "config": { "model": "fal-flux" } },
      { "id": "node-5", "type": "image_to_video",      "label": "Animate",        "position": { "x": 1500,"y": 100 }, "config": { "model": "kling-3.0" } },
      { "id": "node-6", "type": "collect",             "label": "Merge",          "position": { "x": 1800,"y": 100 }, "config": {} },
      { "id": "node-7", "type": "voiceover",           "label": "Narration",      "position": { "x": 2100,"y": 100 }, "config": { "model": "fal-elevenlabs-v3", "voiceoverDefaultVoice": "Adam" } }
    ],
    "edges": [
      { "id": "edge-0", "source": "node-0", "target": "node-1", "sourceHandle": "text-out",  "targetHandle": "text-in"  },
      { "id": "edge-1", "source": "node-1", "target": "node-2", "sourceHandle": "text-out",  "targetHandle": "text-in"  },
      { "id": "edge-2", "source": "node-2", "target": "node-3", "sourceHandle": "text-out",  "targetHandle": "array-in" },
      { "id": "edge-3", "source": "node-3", "target": "node-4", "sourceHandle": "item-out",  "targetHandle": "text-in"  },
      { "id": "edge-4", "source": "node-4", "target": "node-5", "sourceHandle": "image-out", "targetHandle": "image-in" },
      { "id": "edge-5", "source": "node-5", "target": "node-6", "sourceHandle": "video-out", "targetHandle": "item-in"  },
      { "id": "edge-6", "source": "node-6", "target": "node-7", "sourceHandle": "array-out", "targetHandle": "video-in" },
      { "id": "edge-7", "source": "node-1", "target": "node-7", "sourceHandle": "text-out",  "targetHandle": "text-in"  }
    ]
  },
  "required_inputs": [
    { "step_order": 0, "node_type": "text_input", "field": "prompt" }
  ]
}

Inline FlowSchema

Instead of saving a flow first, you can supply a complete FlowSchema JSON in the flow_schema body field of POST /runs. The worker topologically sorts nodes, validates every edge, and executes the graph — same pipeline as a saved flow.

When to use inline schemas

Programmatic flow generation

Your own app builds flows on the fly from templates, user settings, or AI.

Stateless integrations

You’d rather not manage flow state inside Hyperclip.

Per-user customization

Each end user gets a slightly different graph. Avoid mushrooming saved flows.

Ephemeral experiments

A/B test graph variations without cluttering the editor.

Saved flows (flow_id) remain the right choice when you want the flow discoverable in the Hyperclip UI, or when multiple integrations share the same graph.

FlowSchema shape

interface FlowSchema {
  version: 1;
  metadata?: {
    title?: string;
    category?: string;
    description?: string;
  };
  nodes: FlowSchemaNode[];
  edges: FlowSchemaEdge[];
}

interface FlowSchemaNode {
  id: string;                // stable per-node ID, e.g. "node-0"
  type: NodeType;            // one of the 26 supported types — see /api/nodes
  label: string;             // display name, shown in the editor
  position: { x: number; y: number };
  config: FlowSchemaNodeConfig;
}

interface FlowSchemaEdge {
  id: string;
  source: string;            // node.id
  sourceHandle: string;      // e.g. "text-out", "image-out"
  target: string;            // node.id
  targetHandle: string;      // e.g. "text-in", "image-in"
}

interface FlowSchemaNodeConfig {
  model?: string;            // engine ID like "fal-flux", "kling-3.0"
  isBackground?: boolean;    // runs without UI in the editor
  bgInstruction?: string;    // background-mode instruction text
  scriptInstructions?: string;
  mixedMediaInstruction?: string;
  textContent?: string;      // hardcoded text for text_input
  modelOptions?: Record<string, unknown>; // per-model advanced settings
  imageEngine?: string;
  videoEngine?: string;
  fixedMediaUrl?: string;    // baked-in media URL for media_input
  fixedMediaType?: "image" | "video" | "audio";
  voiceoverDefaultVoice?: string;
  audioDefaultQuery?: string;
  audioDefaultTags?: string;
  clipCount?: number;
  angles?: string[];         // multi_angle
  splitMode?: "parallel" | "sequential";
  textboxOverrides?: Record<string, { enabled: boolean; value?: string; description?: string }>;
  // plus any passthrough fields
}

Minimal inline example

curl -X POST $HYPERCLIP_BASE_URL/runs \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_schema": {
      "version": 1,
      "nodes": [
        { "id": "node-0", "type": "text_input",    "label": "Prompt",   "position": {"x":0,"y":100},   "config": {} },
        { "id": "node-1", "type": "text_to_video", "label": "Generate", "position": {"x":300,"y":100}, "config": { "model": "kling-3.0" } }
      ],
      "edges": [
        { "id": "edge-0", "source": "node-0", "target": "node-1", "sourceHandle": "text-out", "targetHandle": "text-in" }
      ]
    },
    "inputs": {
      "prompts": { "0": "a lighthouse at dawn, 35mm film grain" }
    }
  }'

The approve_export node is auto-added at run time — you don’t need to include it in the schema. The final composition is assembled from whatever layers (clipTrims, captionWords, audioTracks, audioOverlay) the graph produces.

Inline schema caveats

Inline schemas don’t appear in GET /flows and aren’t linked to a saved flow. If you rely on the Hyperclip UI for discoverability or collaboration, save the flow first and use flow_id instead.

Max schema size: currently no explicit cap, but keep it under ~500 KB for reliable transport.
Validation happens server-side: the worker runs the same Zod validation as the editor. Malformed schemas fail with 400 invalid_flow_schema.
No versioning: every inline schema must set "version": 1. Future versions will add a migration path.

Input reference

How to supply prompts, media, and per-step overrides at run time.

Node support matrix

Every node type supported by the API (all 26 — full parity with the editor).

Introduction

Endpoints

Reference

Examples

AI tooling

GET /flows

Response

GET /flows/:id

Response

Inline FlowSchema

When to use inline schemas

Programmatic flow generation

Stateless integrations

Per-user customization

Ephemeral experiments

FlowSchema shape

Minimal inline example

Inline schema caveats

See also

Input reference

Node support matrix

​GET /flows

​Response

​GET /flows/:id

​Response

​Inline FlowSchema

​When to use inline schemas

Programmatic flow generation

Stateless integrations

Per-user customization

Ephemeral experiments

​FlowSchema shape

​Minimal inline example

​Inline schema caveats

​See also

Input reference

Node support matrix

GET /flows

Response

GET /flows/:id

Response

Inline FlowSchema

When to use inline schemas

FlowSchema shape

Minimal inline example

Inline schema caveats

See also