SDKs

The Hyperclip API ships official SDKs for Node and Python. Both wrap the same REST endpoints documented elsewhere in this section, so you can mix and match — start with curl in a notebook, switch to the SDK when you ship.

Node SDK

npm install hyperclip · TypeScript-first · Node 18+ · zero runtime deps

Python SDK

pip install hyperclipco · Python 3.9+ · httpx under the hood

Source: github.com/hyperclip/hyperclip-sdks

Install

npm install hyperclip

pip install hyperclipco

The npm package is hyperclip. The PyPI package is hyperclipco (the bare hyperclip name was already taken). The Python module imports as hyperclipco, but the class is still Hyperclip for consistency with the Node SDK.

Configure

The only thing you need is your API key. Set HYPERCLIP_API_KEY in your environment and the SDK picks it up automatically — the base URL defaults to Hyperclip production, so you don’t have to configure it.

import { Hyperclip } from "hyperclip";

// reads HYPERCLIP_API_KEY from process.env
const hc = new Hyperclip();

from hyperclipco import Hyperclip

# reads HYPERCLIP_API_KEY from os.environ
hc = Hyperclip()

You can also pass the key explicitly — handy for multi-tenant servers, tests, or edge runtimes without process.env:

const hc = new Hyperclip({ apiKey: "hck_live_..." });

hc = Hyperclip(api_key="hck_live_...")

Constructor options

Option	Node	Python	Default	Notes
API key	`apiKey`	`api_key`	`HYPERCLIP_API_KEY` env var	Required
Base URL	`baseUrl`	`base_url`	Hyperclip production (or `HYPERCLIP_BASE_URL` env var)	Only override for staging or self-hosted setups
Custom HTTP client	`fetch`	`client` (`httpx.Client`)	global `fetch` / new `httpx.Client`	Useful for tests or proxies
Request timeout	(set on `fetch`)	`timeout`	30s (Python)	Per-request

Method reference

All methods are grouped under two namespaces: runs (the asynchronous-execution endpoints) and flows (saved-flow inspection).

`runs.create(params)` · `POST /runs`

Submit a new run. Returns immediately with a run handle — does not wait for completion.

const ref = await hc.runs.create({
  flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
  inputs: {
    prompts: { 0: "a lighthouse keeper hears footsteps upstairs" },
    media:   { 2: { url: "https://cdn.example.com/ref.png", type: "image" } },
  },
  idempotency_key: crypto.randomUUID(),
});
console.log(ref.id);  // "6f2c1c9a-..."

import uuid

ref = hc.runs.create(
    flow_id="a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    inputs={
        "prompts": {0: "a lighthouse keeper hears footsteps upstairs"},
        "media":   {2: {"url": "https://cdn.example.com/ref.png", "type": "image"}},
    },
    idempotency_key=str(uuid.uuid4()),
)
print(ref["id"])  # "6f2c1c9a-..."

Parameters (mutually-exclusive: one of flow_id or flow_schema required):

flow_id · saved flow UUID from flows.list()
flow_schema · inline FlowSchema JSON; see flows
inputs · per-step overrides; see inputs
idempotency_key · opaque retry key; strongly recommended for every call

Always pass an idempotency_key. If your code retries the call after a network blip, the same key returns the existing run instead of creating a duplicate one.

`runs.get(id)` · `GET /runs/:id`

Fetch the latest state of a single run. Use this to poll, or use the higher-level wait() method below.

const run = await hc.runs.get(runId);
console.log(run.status, run.current_step);

run = hc.runs.get(run_id)
print(run["status"], run.get("current_step"))

`runs.wait(id, options?)` · convenience polling

Poll until the run reaches a terminal state (completed, failed, or cancelled). Replaces hand-rolled polling loops.

const run = await hc.runs.wait(runId, {
  pollIntervalMs: 4000,                              // default 4000
  timeoutMs: 10 * 60_000,                            // default 10 min
  onUpdate: (r) => console.log(r.status, r.current_step),
});
if (run.status !== "completed") {
  throw new Error(`${run.error_code}: ${run.error_message}`);
}
console.log(run.video_url);

run = hc.runs.wait(
    run_id,
    poll_interval=4.0,                              # default 4.0
    timeout=600.0,                                  # default 600
    on_update=lambda r: print(r["status"], r.get("current_step")),
)
assert run["status"] == "completed", run
print(run["video_url"])

Behavior:

Returns the final run object on completed, failed, or cancelled.
Raises HyperclipTimeoutError if the run doesn’t finish within timeoutMs / timeout.
The onUpdate / on_update callback fires on every poll — use it for progress UI or structured logging.

`runs.list(params?)` · `GET /runs`

List your recent runs. Useful for dashboards or reconciliation jobs.

const recent = await hc.runs.list({ limit: 50, status: "completed" });
recent.forEach((r) => console.log(r.id, r.created_at, r.credits_charged));

recent = hc.runs.list(limit=50, status="completed")
for r in recent:
    print(r["id"], r["created_at"], r["credits_charged"])

`runs.cancel(id)` · `POST /runs/:id/cancel`

Cancel a queued or running run. The worker stops at the next step boundary; any in-flight provider call still completes and bills naturally.

await hc.runs.cancel(runId);

hc.runs.cancel(run_id)

`flows.list()` · `GET /flows`

List flows the API key can access (your own flows plus any public ones you’ve saved).

const flows = await hc.flows.list();
flows.forEach((f) => console.log(f.id, f.title));

for f in hc.flows.list():
    print(f["id"], f["title"])

`flows.get(id)` · `GET /flows/:id`

Fetch a single flow’s full FlowSchema plus its required_inputs summary — what prompts and media slots the API caller must fill in.

const flow = await hc.flows.get(flowId);
console.log("Required:", flow.required_inputs);
// → [{ step_order: 0, node_type: "text_input", field: "prompt" }]

flow = hc.flows.get(flow_id)
print("Required:", flow["required_inputs"])

Errors

Both SDKs raise a typed error class when the API returns a non-2xx response:

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) {
    // err.status (number), err.code (string), err.message
    if (err.code === "monthly_cap_exceeded") { /* raise the cap */ }
    else if (err.code === "insufficient_credits") { /* top up */ }
    else if (err.status === 401) { /* revoke + reissue the key */ }
  } else if (err instanceof HyperclipTimeoutError) {
    // run took longer than timeoutMs — cancel and bump the deadline
  } else {
    throw err;
  }
}

from hyperclipco import Hyperclip, HyperclipError, HyperclipTimeoutError

try:
    ref = hc.runs.create(flow_id=FLOW_ID, inputs=inputs)
    hc.runs.wait(ref["id"])
except HyperclipError as err:
    # err.status (int), err.code (str), err.message (str)
    if err.code == "monthly_cap_exceeded":
        ...  # raise the cap
    elif err.code == "insufficient_credits":
        ...  # top up
    elif err.status == 401:
        ...  # revoke + reissue
    else:
        raise
except HyperclipTimeoutError:
    ...  # cancel + bump the deadline

See error codes for the full catalog of code values you can branch on.

Runtime requirements

Feature	Node	Python
Minimum runtime	Node 18+	Python 3.9+
Native HTTP	`fetch` (built-in)	`httpx` (installed automatically)
TypeScript types	bundled (`.d.ts`)	type hints throughout
ESM / CJS	both (`import` and `require`)	n/a
Async	`Promise`-based	sync (raises `HyperclipError`); async client coming

The Node SDK works on Vercel, Netlify, AWS Lambda, Cloudflare Workers, Bun, and Deno (with npm: specifiers). Edge runtimes need to support fetch and crypto.randomUUID(). The Python SDK works in any 3.9+ environment that allows installing httpx. For async codebases, you can pass your own httpx.AsyncClient and call the SDK from synchronous threads, or wait for the upcoming async client.

Versioning

Both SDKs follow SemVer and ship in lockstep — [email protected] matches hyperclipco==0.1.x. Pin to a minor version in production:

{
  "dependencies": {
    "hyperclip": "^0.1.0"
  }
}

[project]
dependencies = [
  "hyperclipco~=0.1.0",
]

When not to use the SDK

The SDKs are thin wrappers — they don’t unlock any capabilities you can’t get from raw HTTP. Reach for raw fetch / requests / curl when:

You’re calling Hyperclip from a language we don’t ship an SDK for (Go, Ruby, PHP, etc.). The REST API is plain JSON over HTTPS.
You need an HTTP client behavior the SDK doesn’t expose — custom retries, mTLS, structured logging hooks. The SDK uses fetch / httpx, both of which are wrappable.
You’re prototyping in a notebook or shell. curl | jq and requests.post() are perfectly fine.

The endpoint reference in runs and flows covers the raw HTTP path for every operation.

Where to next

Quickstart

End-to-end: install the SDK, run a flow, save the MP4.

Node example

Bulk processing, Next.js routes, idempotency patterns.

Python example

CSV-driven batch jobs, FastAPI proxies, async patterns.

Error reference

Every error code with recovery guidance.

Build with AI tools

Wire Claude, Cursor, or Copilot into these docs via the hosted MCP server.

Introduction

Endpoints

Reference

Examples

AI tooling

Node SDK

Python SDK

Install

Configure

Constructor options

Method reference

`runs.create(params)` · `POST /runs`

`runs.get(id)` · `GET /runs/:id`

`runs.wait(id, options?)` · convenience polling

`runs.list(params?)` · `GET /runs`

`runs.cancel(id)` · `POST /runs/:id/cancel`

`flows.list()` · `GET /flows`

`flows.get(id)` · `GET /flows/:id`

Errors

Runtime requirements

Versioning

When not to use the SDK

Where to next

Quickstart

Node example

Python example

Error reference

Build with AI tools

Node SDK

Python SDK

​Install

​Configure

​Constructor options

​Method reference

​runs.create(params) · POST /runs

​runs.get(id) · GET /runs/:id

​runs.wait(id, options?) · convenience polling

​runs.list(params?) · GET /runs

​runs.cancel(id) · POST /runs/:id/cancel

​flows.list() · GET /flows

​flows.get(id) · GET /flows/:id

​Errors

​Runtime requirements

​Versioning

​When not to use the SDK

​Where to next

Quickstart

Node example

Python example

Error reference

Build with AI tools

Install

Configure

Constructor options

Method reference

`runs.create(params)` · `POST /runs`

`runs.get(id)` · `GET /runs/:id`

`runs.wait(id, options?)` · convenience polling

`runs.list(params?)` · `GET /runs`

`runs.cancel(id)` · `POST /runs/:id/cancel`

`flows.list()` · `GET /flows`

`flows.get(id)` · `GET /flows/:id`

Errors

Runtime requirements

Versioning

When not to use the SDK

Where to next