Quickstart

This guide walks you through everything needed to trigger a flow run and download the result.

Prerequisites

A Hyperclip account with at least one flow saved (use a pre-built niche or build one in the visual editor).
Credits in your account. New accounts come with free credits; autorefill covers sustained usage.

Step 1: Create an API key

Open Settings → API Keys

In the Hyperclip app, click API Keys in the sidebar.

Click New key

Name it something descriptive like “My integration”. Optionally set a monthly credit cap or a per-run cap to limit spend.

Copy the full key

The full key is shown exactly once. It looks like hck_live_AbCdEf123456.0123456789abcdefghijklmnopqrstuv. Store it in your secret manager immediately.

If you close the dialog without copying the key, you cannot retrieve it. Revoke it and create a new one.

Step 2: Find a flow to run

curl https://YOUR-PROJECT.supabase.co/functions/v1/api-v1/flows \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY"

const res = await fetch(`${BASE}/flows`, {
  headers: { Authorization: `Bearer ${process.env.HYPERCLIP_API_KEY}` },
});
const { flows } = await res.json();

import requests, os
r = requests.get(f"{BASE}/flows", headers={"Authorization": f"Bearer {os.environ['HYPERCLIP_API_KEY']}"})
flows = r.json()["flows"]

The response lists every flow the key can access:

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

Fetch a specific flow’s required_inputs with GET /flows/:id to see which steps expect prompts or media. See flows.

Step 3: Create a run

curl -X POST https://YOUR-PROJECT.supabase.co/functions/v1/api-v1/runs \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "flow_id": "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    "inputs": {
      "prompts": {
        "0": "A lone lighthouse keeper hears footsteps upstairs"
      }
    }
  }'

import { randomUUID } from "node:crypto";

const res = await fetch(`${BASE}/runs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HYPERCLIP_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    inputs: {
      prompts: {
        0: "A lone lighthouse keeper hears footsteps upstairs",
      },
    },
  }),
});
const { id: runId } = await res.json();

import uuid, requests

r = requests.post(
    f"{BASE}/runs",
    headers={
        "Authorization": f"Bearer {HYPERCLIP_API_KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "flow_id": "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
        "inputs": {"prompts": {"0": "A lone lighthouse keeper hears footsteps upstairs"}},
    },
)
run_id = r.json()["id"]

Always send an Idempotency-Key. If the POST fails with a network error, retrying with the same key returns the existing run instead of creating a duplicate one (and double-charging you).

The response is immediate:

{
  "id": "6f2c1c9a-9b4e-44a8-a1e3-1d8a4f5b2c60",
  "status": "queued",
  "created_at": "2026-04-17T15:04:05Z"
}

Step 4: Poll until complete

async function waitForRun(runId: string) {
  while (true) {
    const r = await fetch(`${BASE}/runs/${runId}`, {
      headers: { Authorization: `Bearer ${process.env.HYPERCLIP_API_KEY}` },
    });
    const run = await r.json();
    if (["completed", "failed", "cancelled"].includes(run.status)) return run;
    console.log(`step ${run.current_step ?? "?"} · ${run.status}`);
    await new Promise((r) => setTimeout(r, 4000));
  }
}

const final = await waitForRun(runId);
if (final.status !== "completed") {
  throw new Error(`Run ${final.status}: ${final.error_code} — ${final.error_message}`);
}
console.log("Video URL:", final.video_url);

import time, requests

def wait_for_run(run_id):
    while True:
        r = requests.get(
            f"{BASE}/runs/{run_id}",
            headers={"Authorization": f"Bearer {HYPERCLIP_API_KEY}"},
        ).json()
        if r["status"] in ("completed", "failed", "cancelled"):
            return r
        print(f"step {r.get('current_step', '?')} · {r['status']}")
        time.sleep(4)

final = wait_for_run(run_id)
assert final["status"] == "completed", final
print("Video URL:", final["video_url"])

A successful response looks like this:

{
  "id": "6f2c1c9a-9b4e-44a8-a1e3-1d8a4f5b2c60",
  "status": "completed",
  "current_step": 8,
  "video_url": "https://remotion-lambda-...s3.amazonaws.com/.../hyperclip-export.mp4",
  "error_code": null,
  "error_message": null,
  "credits_charged": 143,
  "api_markup_multiplier": "1.250",
  "created_at": "2026-04-17T15:04:05Z",
  "started_at": "2026-04-17T15:04:07Z",
  "completed_at": "2026-04-17T15:07:42Z"
}

Step 5: Download the video

The video_url is a signed S3 URL. Download it directly or pipe it to your own storage.

curl -o output.mp4 "$VIDEO_URL"

import fs from "node:fs/promises";
const res = await fetch(final.video_url);
await fs.writeFile("output.mp4", Buffer.from(await res.arrayBuffer()));

import requests
with open("output.mp4", "wb") as f:
    f.write(requests.get(final["video_url"]).content)

Remotion output URLs expire after 24 hours. Save the file to your own storage if you need a permanent copy.

Full working script

Show End-to-end Node.js script

// quickstart.ts — end-to-end: list flows, run one, save the MP4.
import { randomUUID } from "node:crypto";
import fs from "node:fs/promises";

const API_KEY = process.env.HYPERCLIP_API_KEY!;
const BASE = "https://YOUR-PROJECT.supabase.co/functions/v1/api-v1";

const h = (extra: Record<string, string> = {}) => ({
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
  ...extra,
});

async function main() {
  // 1. pick the first flow
  const flows = await (await fetch(`${BASE}/flows`, { headers: h() })).json();
  const flow = flows.flows[0];
  if (!flow) throw new Error("No flows available — create one in the app first.");

  // 2. start a run
  const createRes = await fetch(`${BASE}/runs`, {
    method: "POST",
    headers: h({ "Idempotency-Key": randomUUID() }),
    body: JSON.stringify({
      flow_id: flow.id,
      inputs: { prompts: { 0: "A lone lighthouse keeper hears footsteps upstairs" } },
    }),
  });
  if (!createRes.ok) throw new Error(await createRes.text());
  const { id: runId } = await createRes.json();
  console.log(`queued run ${runId}`);

  // 3. poll
  while (true) {
    await new Promise((r) => setTimeout(r, 4000));
    const run = await (await fetch(`${BASE}/runs/${runId}`, { headers: h() })).json();
    console.log(`  step ${run.current_step ?? "?"} · ${run.status}`);
    if (run.status === "completed") {
      // 4. download
      const bytes = await (await fetch(run.video_url)).arrayBuffer();
      await fs.writeFile("output.mp4", Buffer.from(bytes));
      console.log(`done — saved ${bytes.byteLength} bytes · charged ${run.credits_charged} credits`);
      return;
    }
    if (run.status === "failed" || run.status === "cancelled") {
      throw new Error(`${run.status}: ${run.error_code} — ${run.error_message}`);
    }
  }
}

main();

Next steps

Input reference

Learn how prompts, media, and model_overrides work.

Error handling

Every error code and how to recover from each.

Node-js SDK example

A production-ready wrapper with typed helpers and retries.

Pricing

How credits and the 1.25× markup work in practice.

Introduction

Endpoints

Reference

Examples

AI tooling

Prerequisites

Step 1: Create an API key

Step 2: Find a flow to run

Step 3: Create a run

Step 4: Poll until complete

Step 5: Download the video

Full working script

Next steps

Input reference

Error handling

Node-js SDK example

Pricing

​Prerequisites

​Step 1: Create an API key

​Step 2: Find a flow to run

​Step 3: Create a run

​Step 4: Poll until complete

​Step 5: Download the video

​Full working script

​Next steps

Input reference

Error handling

Node-js SDK example

Pricing

Prerequisites

Step 1: Create an API key

Step 2: Find a flow to run

Step 3: Create a run

Step 4: Poll until complete

Step 5: Download the video

Full working script

Next steps