Node.js

The official Node SDK is published on npm as hyperclip. This page shows production patterns built on top of it. For the full method reference see SDKs.

Install

npm install hyperclip

Requires Node 18+ (uses native fetch). Works on Vercel, Netlify, AWS Lambda, Cloudflare Workers, Bun, and Deno.

Basic usage

import { Hyperclip } from "hyperclip";

// reads HYPERCLIP_API_KEY from process.env
// base URL defaults to Hyperclip production
const hc = new Hyperclip();

const ref = await hc.runs.create({
  flow_id: "a3c7f1ea-...",
  inputs: { prompts: { 0: "A lighthouse keeper hears footsteps upstairs" } },
  idempotency_key: crypto.randomUUID(),
});

const run = await hc.runs.wait(ref.id, {
  onUpdate: (r) => console.log(`step ${r.current_step ?? "?"} · ${r.status}`),
});

if (run.status !== "completed") {
  throw new Error(`${run.error_code}: ${run.error_message}`);
}

console.log(`Video ready: ${run.video_url} (${run.credits_charged} credits)`);

Bulk processing with concurrency control

Run the same flow against rows from a spreadsheet, CMS, or queue. Fixed concurrency keeps you from overwhelming credit reservations.

Show batch.ts

import { Hyperclip, HyperclipError } from "hyperclip";
import fs from "node:fs/promises";

const CONCURRENCY = 4;
const FLOW_ID = process.env.HYPERCLIP_FLOW_ID!;

interface Row { id: string; prompt: string; }

async function processRow(hc: Hyperclip, row: Row) {
  try {
    const ref = await hc.runs.create({
      flow_id: FLOW_ID,
      inputs: { prompts: { 0: row.prompt } },
      idempotency_key: `row-${row.id}`,  // dedupe on the input ID
    });
    const run = await hc.runs.wait(ref.id);
    if (run.status !== "completed") throw new Error(run.error_message ?? run.status);

    const bytes = await (await fetch(run.video_url!)).arrayBuffer();
    await fs.writeFile(`out/${row.id}.mp4`, Buffer.from(bytes));
    console.log(`✓ ${row.id} · ${run.credits_charged} credits`);
  } catch (err) {
    const msg = err instanceof HyperclipError ? `${err.code} (${err.status})` : (err as Error).message;
    console.error(`✗ ${row.id} · ${msg}`);
  }
}

async function main() {
  const rows: Row[] = JSON.parse(await fs.readFile("rows.json", "utf8"));
  const hc = new Hyperclip();

  const queue = [...rows];
  const workers = Array.from({ length: CONCURRENCY }, async () => {
    while (queue.length) {
      const row = queue.shift()!;
      await processRow(hc, row);
    }
  });
  await Promise.all(workers);
}

main();

The deterministic idempotency key (one per row ID) is the magic here. If the batch crashes and you re-run it, already-processed rows return their existing completed run instead of re-charging.

Next.js: webhook-triggered generation

Expose an API route that kicks off a run and returns its ID immediately. Your frontend polls a status endpoint until the video is ready — never touching the API key.

// app/api/generate/route.ts
import { Hyperclip } from "hyperclip";
import { NextResponse } from "next/server";

const hc = new Hyperclip();  // reads env vars

export async function POST(req: Request) {
  const { userId, prompt } = await req.json();

  const ref = await hc.runs.create({
    flow_id: process.env.HYPERCLIP_FLOW_ID!,
    inputs: { prompts: { 0: prompt } },
    idempotency_key: `user-${userId}-${Date.now()}`,
  });

  return NextResponse.json({ run_id: ref.id });
}

// app/api/generate/[id]/route.ts
import { Hyperclip } from "hyperclip";
import { NextResponse } from "next/server";

const hc = new Hyperclip();

export async function GET(_: Request, { params }: { params: { id: string } }) {
  const run = await hc.runs.get(params.id);
  return NextResponse.json({
    status: run.status,
    progress: run.current_step,
    video_url: run.video_url,
    error: run.error_code ? { code: run.error_code, message: run.error_message } : null,
  });
}

The frontend polls GET /api/generate/<id> every few seconds and renders the video once status === "completed".

Cloudflare Workers / edge runtimes

The SDK is dependency-free and runs on any environment that has fetch. The one gotcha: edge runtimes don’t have process.env by default — pass the API key explicitly.

import { Hyperclip } from "hyperclip";

export default {
  async fetch(req: Request, env: Env) {
    const hc = new Hyperclip({ apiKey: env.HYPERCLIP_API_KEY });

    const { prompt } = await req.json<{ prompt: string }>();
    const ref = await hc.runs.create({
      flow_id: env.HYPERCLIP_FLOW_ID,
      inputs: { prompts: { 0: prompt } },
      idempotency_key: crypto.randomUUID(),
    });
    return Response.json({ run_id: ref.id });
  },
};

Don’t runs.wait() inside a serverless function with a short timeout. Most serverless platforms cap at 30s of CPU time. Return the run ID and let the client poll.

Cancellation with AbortSignal

The wait() helper accepts an AbortSignal so you can bail early — useful when the user navigates away or your job runner ages out.

const controller = new AbortController();
setTimeout(() => controller.abort(), 5 * 60_000);  // hard cap at 5 minutes

try {
  const run = await hc.runs.wait(runId, { signal: controller.signal });
  console.log(run.video_url);
} catch (err) {
  if (err instanceof HyperclipTimeoutError) {
    await hc.runs.cancel(runId);  // release credits faster
  }
  throw err;
}

Error handling

import { Hyperclip, HyperclipError, HyperclipTimeoutError } from "hyperclip";

try {
  const ref = await hc.runs.create({ flow_id, inputs });
  await hc.runs.wait(ref.id);
} catch (err) {
  if (err instanceof HyperclipError) {
    switch (err.code) {
      case "monthly_cap_exceeded":     /* raise the cap or wait for reset */ break;
      case "insufficient_credits":     /* enable autorefill or top up */    break;
      case "worker_error":
      case "render_failed":            /* safe to retry with a new key */    break;
      default:
        if (err.status === 401)        /* revoke + reissue */;
        else throw err;
    }
  } else if (err instanceof HyperclipTimeoutError) {
    /* run is still going server-side — cancel or extend */
  } else {
    throw err;
  }
}

See error codes for every case.

Inline FlowSchema (no saved flow)

Skip the saved-flow step and pass a graph inline. Useful for templated or AI-generated flows.

const ref = await hc.runs.create({
  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" } },
});

See inline FlowSchema for the full shape and node catalog.

Bring-your-own fetch

Inject a custom fetch for testing, structured logging, or proxying:

import { Hyperclip } from "hyperclip";

const tracingFetch: typeof fetch = async (input, init) => {
  console.log("→", init?.method, input);
  const start = Date.now();
  const res = await fetch(input, init);
  console.log("←", res.status, `${Date.now() - start}ms`);
  return res;
};

const hc = new Hyperclip({ fetch: tracingFetch });

Where next

SDK reference

Every method, parameter, and option.

Inputs reference

All the ways to override a flow’s defaults at run time.

Errors

Catalog of every error you can hit.

Source on GitHub

File issues, read source, watch for releases.

Introduction

Endpoints

Reference

Examples

AI tooling

Install

Basic usage

Bulk processing with concurrency control

Next.js: webhook-triggered generation

Cloudflare Workers / edge runtimes

Cancellation with AbortSignal

Error handling

Inline FlowSchema (no saved flow)

Bring-your-own fetch

Where next

SDK reference

Inputs reference

Errors

Source on GitHub

​Install

​Basic usage

​Bulk processing with concurrency control

​Next.js: webhook-triggered generation

​Cloudflare Workers / edge runtimes

​Cancellation with AbortSignal

​Error handling

​Inline FlowSchema (no saved flow)

​Bring-your-own fetch

​Where next

SDK reference

Inputs reference

Errors

Source on GitHub

Install

Basic usage

Bulk processing with concurrency control

Next.js: webhook-triggered generation

Cloudflare Workers / edge runtimes

Cancellation with AbortSignal

Error handling

Inline FlowSchema (no saved flow)

Bring-your-own fetch

Where next