API

Authorization: Bearer hl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -X POST https://api.highlander.sh/v1/generations \
  -H "Authorization: Bearer $HIGHLANDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Waves break over black volcanic rock at dusk.","frames":345,"steps":5}'

curl -X POST https://api.highlander.sh/v1/generations \
  -H "Authorization: Bearer $HIGHLANDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"The painting comes alive; she turns and smiles.",
       "first_frame_url":"https://example.com/portrait.png","frames":124}'

import os, json, requests

BASE = "https://api.highlander.sh"
H = {"Authorization": f"Bearer {os.environ['HIGHLANDER_KEY']}"}

def upload(path, content_type):
    # 1. your prefix. The pathname is baked into the token, so it must already be yours.
    policy = requests.get(f"{BASE}/v1/uploads", headers=H).json()
    pathname = policy["prefix"] + os.path.basename(path)

    # 2. a client token, scoped to that one pathname, content type and size cap
    tok = requests.post(f"{BASE}/v1/uploads", headers=H, json={
        "type": "blob.generate-client-token",
        "payload": {"pathname": pathname,
                    "clientPayload": json.dumps({"contentType": content_type}),
                    "multipart": False},
    }).json()["clientToken"]

    # 3. the bytes, straight to Vercel Blob -- they never touch highlander.sh
    store_id = tok.split("_")[3]
    with open(path, "rb") as f:
        blob = requests.put(
            "https://vercel.com/api/blob/", params={"pathname": pathname}, data=f,
            headers={"authorization": f"Bearer {tok}",
                     "x-api-version": "12",
                     "x-vercel-blob-store-id": store_id,
                     "x-vercel-blob-access": "public",
                     "x-content-type": content_type},
        ).json()
    return blob["url"]      # NOT pathname: a random suffix is added

url = upload("portrait.png", "image/png")
requests.post(f"{BASE}/v1/generations", headers=H, json={
    "prompt": "The painting comes alive; she turns and smiles.",
    "first_frame_url": url, "frames": 124,
})

curl -fsSL https://highlander.sh/hl -o hl && chmod +x hl
export HIGHLANDER_KEY=hl_live_...

./hl generate "Waves break over black volcanic rock at dusk."
./hl generate "The painting comes alive; she turns." --first-frame photo.jpg --seconds 5
./hl status 0f7c1e2a-... --wait --download
./hl list --limit 5
./hl health                # modes, queue and phase; no key needed
./hl upload subject.jpg    # a URL to reuse across runs

{
  "id": "0f7c1e2a-...",
  "status": "queued",
  "mode": "fl2v",
  "pipeline_state": "generating",
  "queue_ahead": 0,
  "queue_depth": 1,
  "latency_s": null,
  "video": null,
  "poll": "/v1/generations/0f7c1e2a-..."
}

{
  "id": "0f7c1e2a-...",
  "status": "succeeded",
  "mode": "t2v",
  "prompt": "A traceur vaults a rooftop ledge...",
  "frames": 345,
  "steps": 5,
  "seed": 1000,
  "width": 1344,
  "height": 768,
  "duration_s": 14.375,
  "first_frame_url": null,
  "last_frame_url": null,
  "references": null,
  "pipeline_state": null,
  "cost_usd": 0.22,
  "refunded": false,
  "latency_s": 11.76,
  "realtime_factor": 0.8181,
  "error": null,
  "created_at": "2026-09-01T18:04:11.201Z",
  "finished_at": "2026-09-01T18:04:24.707Z",
  "queue_ahead": null,
  "queue_depth": null,
  "video": "/v1/generations/0f7c1e2a-.../video",
  "poll": "/v1/generations/0f7c1e2a-..."
}

import os, time, requests

BASE = "https://api.highlander.sh"
H = {"Authorization": f"Bearer {os.environ['HIGHLANDER_KEY']}"}

job = requests.post(f"{BASE}/v1/generations", headers=H, json={
    "prompt": "A traceur vaults a rooftop ledge into a roll, tracking shot alongside.",
    "frames": 345,      # 14.375 s
    "steps": 5,
}).json()

while True:
    s = requests.get(f"{BASE}/v1/generations/{job['id']}", headers=H).json()
    if s["status"] in ("succeeded", "failed"):
        break
    # pipeline_state says WHY it is still waiting -- "queued", "connecting", "generating"
    print(s["status"], s.get("pipeline_state"), s.get("queue_ahead"))
    time.sleep(2)

if s["status"] == "failed":
    raise SystemExit(s["error"])

mp4 = requests.get(f"{BASE}/v1/generations/{job['id']}/video", headers=H).content
open("out.mp4", "wb").write(mp4)
print(f"{s['latency_s']}s render, {s['realtime_factor']}x realtime, ${s['cost_usd']}")

const BASE = "https://api.highlander.sh";
const H = { Authorization: `Bearer ${process.env.HIGHLANDER_KEY}`,
            "Content-Type": "application/json" };

const job = await fetch(`${BASE}/v1/generations`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ prompt: "Waves break over black volcanic rock at dusk." }),
}).then((r) => r.json());

let status;
do {
  await new Promise((r) => setTimeout(r, 2000));
  status = await fetch(`${BASE}/v1/generations/${job.id}`, { headers: H })
    .then((r) => r.json());
} while (status.status === "queued" || status.status === "running");

const mp4 = await fetch(`${BASE}/v1/generations/${job.id}/video`, { headers: H });
await Bun.write("out.mp4", await mp4.arrayBuffer());