Runs

import { Hyperclip } from "hyperclip";
const hc = new Hyperclip();

const ref = await hc.runs.create({
  flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
  inputs: {
    prompts: { 0: "a cat surfing at sunset" },
    media:   { 2: { url: "https://cdn.example.com/ref.png", type: "image" } },
  },
  idempotency_key: crypto.randomUUID(),
});

import uuid
from hyperclipco import Hyperclip
hc = Hyperclip()

ref = hc.runs.create(
    flow_id="a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    inputs={
        "prompts": {0: "a cat surfing at sunset"},
        "media":   {2: {"url": "https://cdn.example.com/ref.png", "type": "image"}},
    },
    idempotency_key=str(uuid.uuid4()),
)

curl -X POST $HYPERCLIP_BASE_URL/runs \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c3dd7be6-a8f4-4d06-b9c4-cc55da7bdedc" \
  -d '{
    "flow_id": "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    "inputs": {
      "prompts": { "0": "a cat surfing at sunset" },
      "media":   { "2": { "url": "https://cdn.example.com/ref.png", "type": "image" } }
    }
  }'

const res = await fetch(`${BASE}/runs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    inputs: {
      prompts: { 0: "a cat surfing at sunset" },
      media:   { 2: { url: "https://cdn.example.com/ref.png", type: "image" } },
    },
  }),
});
const { id } = await res.json();

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

import { Hyperclip } from "hyperclip";
const hc = new Hyperclip();

const ref = await hc.runs.create({
  flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
  inputs: {
    prompts: { 0: "a cat surfing at sunset" },
    media:   { 2: { url: "https://cdn.example.com/ref.png", type: "image" } },
  },
  idempotency_key: crypto.randomUUID(),
});

import uuid
from hyperclipco import Hyperclip
hc = Hyperclip()

ref = hc.runs.create(
    flow_id="a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    inputs={
        "prompts": {0: "a cat surfing at sunset"},
        "media":   {2: {"url": "https://cdn.example.com/ref.png", "type": "image"}},
    },
    idempotency_key=str(uuid.uuid4()),
)

curl -X POST $HYPERCLIP_BASE_URL/runs \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c3dd7be6-a8f4-4d06-b9c4-cc55da7bdedc" \
  -d '{
    "flow_id": "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    "inputs": {
      "prompts": { "0": "a cat surfing at sunset" },
      "media":   { "2": { "url": "https://cdn.example.com/ref.png", "type": "image" } }
    }
  }'

const res = await fetch(`${BASE}/runs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    inputs: {
      prompts: { 0: "a cat surfing at sunset" },
      media:   { 2: { url: "https://cdn.example.com/ref.png", type: "image" } },
    },
  }),
});
const { id } = await res.json();

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

A run is one execution of a flow. The API creates runs asynchronously — POST /runs returns an ID immediately, and you poll GET /runs/:id until the run completes and produces a final video URL.

Lifecycle

queued  →  running  →  completed
                  ↘    failed
                  ↘    cancelled

Status	Meaning
`queued`	Accepted. Waiting for a worker tick (up to ~60s).
`running`	A worker is executing the flow. `current_step` advances between heartbeats.
`completed`	Success. `video_url` is populated.
`failed`	Terminal error. `error_code` and `error_message` are set. Any in-flight credit reservations released.
`cancelled`	You cancelled the run via `POST /runs/:id/cancel`. The worker stops at the next step boundary.

A typical run takes 30 seconds to 5 minutes, longer for flows with multiple video generations.

Runs resume automatically across server-side timeouts. If a processing tick hits its wall clock mid-run, the next tick detects the stale heartbeat and picks up from the last completed step.

POST /runs

Create a new run.

string

required

Bearer hck_live_<prefix>.<secret> — must carry runs:write scope.

string

A UUID (or any opaque string) that the server keys retries on. Two requests with the same (user_id, Idempotency-Key) return the same run instead of creating a second one. Strongly recommended for every POST.

Body

string (uuid)

A saved flow ID from GET /flows. Mutually exclusive with flow_schema.

object

An inline FlowSchema JSON object — the same structure the visual editor saves. Use this when you want to run a flow without persisting it. Mutually exclusive with flow_id. See flows for the full shape.

object

Run an Influencer Studio content mode for one of your projects. The influencer’s saved reference images are wired in automatically. Mutually exclusive with flow_id and flow_schema.

Show studio fields

string (uuid)

required

An Influencer Studio project you own.

string

required

One of avatar, ugc, or vlog. (The carousel mode is image-only and not available via the API.)

Provide the mode’s runtime inputs via inputs — e.g. the driving video (avatar) or product image (ugc) as an inputs.media entry (keyed by the media_input step’s step_order), and any scene/script prompts via inputs.prompts. The influencer reference shots are pre-filled, so you only supply what’s unique to the run. The finished video is returned on the run’s video_url like any other run.

object

Caller-supplied overrides that fill in the flow’s placeholders. See inputs reference for the full schema.

Show inputs fields

Record<number, string>

Maps step_order → prompt. Overrides the prompt the flow would otherwise use at that step.

Record<number, { url, type }>

Maps step_order → media asset. Supplies URLs + types for media_input steps that don’t have a baked-in fixedMediaUrl.

Record<number, object>

Advanced. Per-step node_data patches — custom _model_options, voice IDs, caption styles, etc.

string

Alternative to the Idempotency-Key header — the body field wins if both are present.

Response

string (uuid)

required

The new run’s ID. Use this for polling, listing, and cancellation.

string

required

Always queued on a fresh run. completed or other statuses can appear on an idempotency-retry if the prior run already finished.

string (ISO 8601)

required

UTC timestamp.

import { Hyperclip } from "hyperclip";
const hc = new Hyperclip();

const ref = await hc.runs.create({
  flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
  inputs: {
    prompts: { 0: "a cat surfing at sunset" },
    media:   { 2: { url: "https://cdn.example.com/ref.png", type: "image" } },
  },
  idempotency_key: crypto.randomUUID(),
});

import uuid
from hyperclipco import Hyperclip
hc = Hyperclip()

ref = hc.runs.create(
    flow_id="a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    inputs={
        "prompts": {0: "a cat surfing at sunset"},
        "media":   {2: {"url": "https://cdn.example.com/ref.png", "type": "image"}},
    },
    idempotency_key=str(uuid.uuid4()),
)

curl -X POST $HYPERCLIP_BASE_URL/runs \
  -H "Authorization: Bearer $HYPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c3dd7be6-a8f4-4d06-b9c4-cc55da7bdedc" \
  -d '{
    "flow_id": "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    "inputs": {
      "prompts": { "0": "a cat surfing at sunset" },
      "media":   { "2": { "url": "https://cdn.example.com/ref.png", "type": "image" } }
    }
  }'

const res = await fetch(`${BASE}/runs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
    inputs: {
      prompts: { 0: "a cat surfing at sunset" },
      media:   { 2: { url: "https://cdn.example.com/ref.png", type: "image" } },
    },
  }),
});
const { id } = await res.json();

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

GET /runs/:id

Fetch a single run’s current state. This is the polling endpoint.

string (uuid)

required

Run ID returned from POST /runs.

Response

string

required

string

required

queued | running | completed | failed | cancelled.

integer | null

Zero-indexed step currently being processed (or last completed). null until the worker picks up the run.

string | null

Public URL to the rendered MP4 on video.hyperclip.co. Populated once status === "completed". The file stays hosted at this URL permanently.

string | null

Machine-readable error category. See error codes.

string | null

Human-readable error detail.

integer

Total credits billed so far for this run.

string (ISO 8601)

required

string | null

Set when the worker first claims the run.

string | null

Set on completed, failed, or cancelled.

{
  "id": "6f2c1c9a-9b4e-44a8-a1e3-1d8a4f5b2c60",
  "status": "completed",
  "current_step": 8,
  "video_url": "https://video.hyperclip.co/api-exports/6f2c1c9a-9b4e-44a8-a1e3-1d8a4f5b2c60.mp4",
  "error_code": null,
  "error_message": null,
  "credits_charged": 213,
  "created_at": "2026-04-17T15:04:05Z",
  "started_at": "2026-04-17T15:04:07Z",
  "completed_at": "2026-04-17T15:07:42Z"
}

{
  "id": "6f2c1c9a-...",
  "status": "running",
  "current_step": 3,
  "video_url": null,
  "error_code": null,
  "error_message": null,
  "credits_charged": 42,
  "created_at": "2026-04-17T15:04:05Z",
  "started_at": "2026-04-17T15:04:07Z",
  "completed_at": null
}

{
  "id": "6f2c1c9a-...",
  "status": "failed",
  "current_step": 5,
  "video_url": null,
  "error_code": "generation_failed",
  "error_message": "Generation failed, please try again.",
  "credits_charged": 18,
  "created_at": "2026-04-17T15:04:05Z",
  "started_at": "2026-04-17T15:04:07Z",
  "completed_at": "2026-04-17T15:05:44Z"
}

GET /runs

List the authenticated user’s recent runs.

integer

default:"20"

1–100.

string

Filter to a single status: queued, running, completed, failed, cancelled.

{
  "runs": [
    { "id": "6f2c1c9a-...", "status": "completed", "current_step": 8, "video_url": "https://...", "error_code": null, "credits_charged": 213, "created_at": "2026-04-17T15:04:05Z", "completed_at": "2026-04-17T15:07:42Z" },
    { "id": "0f4aa21e-...", "status": "running",   "current_step": 3, "video_url": null,          "error_code": null, "credits_charged": 42,  "created_at": "2026-04-17T15:08:00Z", "completed_at": null }
  ]
}

POST /runs/:id/cancel

Cancel a queued or running run. The worker respects the cancel flag between steps — any in-flight provider call (image, video, audio generation) still completes and bills naturally.

string

required

string

required

cancelled on success.

{ "id": "6f2c1c9a-...", "status": "cancelled" }

A run that already finished returns 404 run_not_cancellable. Cancellation is only valid for queued or running states.

Polling strategy

The SDKs ship a built-in runs.wait() helper. For raw HTTP, write your own loop following the same shape.

const run = await hc.runs.wait(runId, {
  timeoutMs: 10 * 60_000,
  pollIntervalMs: 4000,
  onUpdate: (r) => console.log(r.status, r.current_step),
});

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

async function waitForRun(runId: string, timeoutMs = 10 * 60_000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const r = await fetch(`${BASE}/runs/${runId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const run = await r.json();
    if (["completed", "failed", "cancelled"].includes(run.status)) return run;
    await new Promise((r) => setTimeout(r, 4_000));
  }
  throw new Error("run polling timed out");
}

import time, requests

def wait_for_run(run_id: str, timeout_sec: int = 600):
    deadline = time.time() + timeout_sec
    while time.time() < deadline:
        run = requests.get(
            f"{BASE}/runs/{run_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        ).json()
        if run["status"] in ("completed", "failed", "cancelled"):
            return run
        time.sleep(4)
    raise RuntimeError("run polling timed out")

Recommendations

Poll every 3–5 seconds. Less than that wastes requests; more than that adds lag.
Back off to 10s after 2 minutes of runtime for long video flows.
Never poll from the browser with your API key attached.
Cancel runs that exceed your expected duration — stuck worker ticks eventually time out anyway, but an explicit cancel releases credits faster.

Idempotency in depth

When you send Idempotency-Key: <uuid>:

If no run exists for (user_id, key) — a new run is created.
If a run already exists — the server returns that run’s current state without creating a new one.

Keys are scoped per API-authenticated user. Different users sending the same key create independent runs.

Pick your idempotency key carefully. Reusing a key across semantically different requests means the server returns the wrong run’s state. One key per logical retry sequence.

Introduction

Endpoints

Reference

Examples

AI tooling

Lifecycle

POST /runs

Body

Response

GET /runs/:id

Response

GET /runs

POST /runs/:id/cancel

Polling strategy

Recommendations

Idempotency in depth

​Lifecycle

​POST /runs

​Body

​Response

​GET /runs/:id

​Response

​GET /runs

​POST /runs/:id/cancel

​Polling strategy

​Recommendations

​Idempotency in depth

Lifecycle

POST /runs

Body

Response

GET /runs/:id

Response

GET /runs

POST /runs/:id/cancel

Polling strategy

Recommendations

Idempotency in depth