Input reference

The inputs field of POST /runs is how you provide the specific data a flow needs at run time. Every flow has placeholder prompts and optional media slots; inputs fills them in.

Shape

interface RunInputs {
  prompts?: Record<number, string>;
  media?: Record<number, { url: string; type: "image" | "video" | "audio" }>;
  model_overrides?: Record<number, Record<string, unknown>>;
}

Keys are step indices (step_order) — the zero-based position of the node in the flow’s topological sort. Find these via GET /flows/:id → required_inputs.

`inputs.prompts`

Per-step prompt overrides. The most common use — 95% of integrations only need this. Applies to steps whose executor reads a prompt:

text_input, text_editor
ai_transform, script_generation, mixed_media, parse_scenes, continuity_enhance
image_generation, text_to_video, image_to_video, animation
multi_angle, ai_music, voiceover

The override beats everything: inline textbox values, upstream artifact prompts, flow defaults.

Example

{
  "inputs": {
    "prompts": {
      "0": "A lone lighthouse keeper hears footsteps upstairs",
      "4": "Cinematic, 35mm film grain, cool blue palette",
      "7": "A calm narrator, slight British accent"
    }
  }
}

When a flow has a single text_input at step 0, the whole integration is usually just { "prompts": { "0": "..." } }.

`inputs.media`

Supplies URLs for media_input and audio_overlay nodes. Overrides baked-in fixedMediaUrl values.

string (url)

required

Publicly accessible URL. Hyperclip’s workers fetch it directly — no authentication headers are sent.

'image' | 'video' | 'audio'

required

Declares the media kind. The artifact is routed to the correct downstream field (imageUrl, videoUrl, audioUrl).

Example

{
  "inputs": {
    "media": {
      "2": { "url": "https://cdn.example.com/character.png", "type": "image" },
      "3": { "url": "https://cdn.example.com/reference-dance.mp4", "type": "video" }
    }
  }
}

Supported hosts

Any URL Hyperclip’s workers can GET with a 200 response:

Public CDNs (Cloudflare R2, S3 with public ACL, imgix, Cloudinary, etc.)
User-uploaded URLs on your own backend
Pre-signed S3 URLs (valid for the duration of the run — at least 10 minutes)
Direct public object-storage URLs

Private URLs must be pre-signed before being passed in. Hyperclip does not authenticate with third-party systems. A 401 or 403 fetching the URL fails the step with an upstream error.

Expected formats

Type	Formats	Notes
`image`	PNG, JPEG, WebP	Prefer square or 9:16. Min 512px on the shorter side.
`video`	MP4 (H.264/H.265), MOV, WebM	≤10 min long. 1080p maximum for cost.
`audio`	MP3, WAV, AAC, M4A	Any reasonable length.

`inputs.model_overrides`

Advanced — partial node_data patches applied to specific steps. Use this to override model settings without editing the flow itself.

object

A key-value object that merges into the step’s node_data at run time. Common keys listed below.

Common overrides

_model_options — engine-specific settings

Passed through to the underlying engine. Shape depends on the model:

{
  "model_overrides": {
    "5": { "_model_options": { "duration": "10", "tier": "pro", "seed": 42 } }
  }
}

For Kling 3.0: tier, duration, seed. For Veo 3: tier, duration. See AI models.

_voiceover_default_voice — ElevenLabs voice ID

{
  "model_overrides": {
    "7": { "_voiceover_default_voice": "Rachel" }
  }
}

_clip_count — clipping node pick count

Number of clips to extract from a long video.

{
  "model_overrides": {
    "3": { "_clip_count": 3 }
  }
}

_selected_angles — multi_angle angles list

{
  "model_overrides": {
    "2": { "_selected_angles": ["front", "side", "back"] }
  }
}

_caption_style_id / _caption_style_overrides — caption appearance

Two ways to style captions on the auto_captions node. Pass either or both — overrides win field-by-field.Option A — paste a style ID from the Caption Designer. The ID is a self-contained cs_… blob that carries the full style payload:

{
  "model_overrides": {
    "6": {
      "_caption_style_id": "cs_eyJmb250RmFtaWx5IjoiQW50b24sIEltcGFjdCwgc2Fucy1zZXJpZiIsImZvbnRTaXplIjo4MH0"
    }
  }
}

Option B — pass _caption_style_overrides, a partial CaptionStyle object. See the Auto Captions reference for every field.

{
  "model_overrides": {
    "6": {
      "_caption_style_overrides": {
        "fontFamily": "Anton, Impact, sans-serif",
        "fontSize": 72,
        "color": "#FFFFFF",
        "highlightColor": "#22D3C1",
        "position": 75,
        "uppercase": true
      }
    }
  }
}

_background_audio_volume / _ai_music_volume

Numbers between 0 and 1. Per-track mix levels, applied at the final composition.

{
  "model_overrides": {
    "8": { "_background_audio_volume": 0.25 },
    "9": { "_ai_music_volume": 0.6 }
  }
}

Finding step_order

Fetch the flow to see its step order:

curl $BASE/flows/<flow_id> -H "Authorization: Bearer $HYPERCLIP_API_KEY"

Look at required_inputs for the quick list, or walk flow_schema.nodes in array order — that’s the step order used for inputs.

The required_inputs array returned by GET /flows/:id is the authoritative source. It already filters to just the steps that expect caller-supplied input, so you can drive a form directly off it.

Prompt resolution priority

Within a single step, the executor picks a prompt in this order:

Textbox override (inline value)

If the node has textboxOverrides.text-in.value set in the flow schema, that wins. Used for hardcoded text in template flows.

Caller-supplied prompt

inputs.prompts[step_order]. This is the normal API override path.

Upstream artifact prompt

The prompt produced by the previous node (e.g. a script_generation output flows into image_generation).

Empty

The step is skipped with its upstream artifact passed through unchanged.

Validation

POST /runs validates inputs.prompts and inputs.media against the flow’s schema before the run is queued — bad input fails fast with a 400 instead of charging credits and failing downstream. Specifically:

Step indices must exist in the flow (invalid_input_step).
Prompts only go to text_input / text_editor steps (input_type_mismatch).
Media only goes to media_input steps (input_type_mismatch).
Each media entry must have a url (non-empty string) and a type of image, video, or audio (invalid_input_value).
The media type must be one of the node’s accepted types — read required_inputs[].accepted_media_types from GET /flows/:id (media_type_not_accepted).

See error codes for the full catalog.

`model_overrides` is loose

model_overrides is patched into existing node_data, not replaced. Unknown keys are ignored by the executor; invalid _model_options surface as status: "failed" with a generic error at run time.

There’s no schema validation on model_overrides today — bad values surface as run-time errors. A future version may validate against each model’s option catalog.

Full example

POST /runs
{
  "flow_id": "a3c7f1ea-...",
  "idempotency_key": "c3dd7be6-a8f4-4d06-b9c4-cc55da7bdedc",
  "inputs": {
    "prompts": {
      "0": "A lighthouse keeper's diary entry about strange lights",
      "3": "35mm film grain, cinematic, cool palette"
    },
    "media": {
      "2": { "url": "https://cdn.example.com/lighthouse.png", "type": "image" }
    },
    "model_overrides": {
      "4": { "_model_options": { "duration": "10", "tier": "pro" } },
      "7": { "_voiceover_default_voice": "Adam" },
      "8": { "_caption_style_overrides": { "fontSize": 72, "uppercase": true } }
    }
  }
}

Introduction

Endpoints

Reference

Examples

AI tooling

Shape

`inputs.prompts`

Example

`inputs.media`

Example

Supported hosts

Expected formats

`inputs.model_overrides`

Common overrides

Finding step_order

Prompt resolution priority

Validation

`model_overrides` is loose

Full example

​Shape

​inputs.prompts

​Example

​inputs.media

​Example

​Supported hosts

​Expected formats

​inputs.model_overrides

​Common overrides

​Finding step_order

​Prompt resolution priority

​Validation

​model_overrides is loose

​Full example

Shape

`inputs.prompts`

Example

`inputs.media`

Example

Supported hosts

Expected formats

`inputs.model_overrides`

Common overrides

Finding step_order

Prompt resolution priority

Validation

`model_overrides` is loose

Full example