VCursor JavaScript / TypeScript SDK

Generate videos from text, images, and URLs using AI.

Installation

npm install vcursor-sdk

Quick Start

import { VCursor } from "vcursor-sdk";

const client = new VCursor({ apiKey: "vk-..." });

// Submit a video generation task
const resp = await client.submit("a cat playing piano in a jazz club");

// Wait for completion with progress callback
const result = await client.waitForCompletion(resp.task_id!, {
  onProgress: (p) => console.log(`${p.data.progress}%`),
});

console.log(result.data.products.url);

Agent Mode

const agent = await client.submitAgent(
  "create a 30s commercial for a coffee brand",
  { duration: "30s", aspect_ratio: "16:9" },
);

const result = await client.waitForAgentCompletion(agent.task_id, {
  onProgress: (p) => console.log(`${p.progress}% - ${p.current_stage}`),
});

console.log(result.video_url);

Concurrency Limiting

The server enforces per-user rate limits based on subscription tier:

| Tier | Standard Requests | Agent Requests | Window | | ---- | ----------------- | -------------- | ---------- | | Free | 3 | 1 | Lifetime | | Pro | 30/hr | 5/hr | Rolling 1h | | Plus | 120/hr | 15/hr | Rolling 1h |

// Check current rate limit status
const status = await client.checkConcurrency("standard");
console.log(`Used: ${status.used}/${status.limit}`);

// Client-side limit (capped at server limit)
const limited = new VCursor({ apiKey: "vk-...", maxConcurrency: 10 });

API Reference

new VCursor(options?)

| Option | Type | Description | | ---------------- | -------- | ------------------------------------------- | | apiKey | string | API key (falls back to env / config file) | | server | string | Server URL (falls back to env / config file) | | maxConcurrency | number | Client-side concurrency cap |

Methods

| Method | Description | | --------------------------------------- | -------------------------------------- | | submit(prompt, options?) | Submit a standard video generation task | | getProgress(taskId) | Get task progress | | waitForCompletion(taskId, options?) | Poll until task completes | | cancelTask(taskId) | Cancel a running task | | submitAgent(message, options?) | Submit an agent mode task | | getAgentProgress(taskId) | Get agent task progress | | waitForAgentCompletion(taskId, opts?) | Poll until agent task completes | | checkConcurrency(category?) | Check concurrency limit status |

Configuration

Config is loaded from ~/.vcursor/config.json (shared with the Python SDK and CLI).

Environment variables:

• VCURSOR_API_KEY - API key
• VCURSOR_SERVER - Server URL

License

MIT