Python SDK

The VCursor Python SDK offers a clean, idiomatic interface for integrating video generation capabilities into your Python applications.

Installation

bash

pip install vcursor-cli

Quick Start

Synchronous usage for simple scripts and straightforward integrations.

main.py
from vcursor import VCursor

client = VCursor(api_key="your_api_key")

# Submit a video generation task
resp = client.submit("a cat playing piano in a jazz club")
print(f"Task started: {resp.task_id}")

# Wait for completion with progress callback
result = client.wait_for_completion(
    resp.task_id,
    on_progress=lambda p: print(f"{p.data.progress}%")
)

print(f"Video URL: {result.data.products.url}")

Async Usage

Use VCursorAsync for high-performance asyncio applications such as FastAPI servers or Discord bots.

async_example.py
import asyncio
from vcursor import VCursorAsync

async def main():
    async with VCursorAsync(api_key="your_api_key") as client:
        resp = await client.submit("sunset timelapse over mountains")
        print(f"Task: {resp.task_id}")
        
        result = await client.wait_for_completion(resp.task_id)
        if result.data.status == "completed":
             print(result.data.products.url)

asyncio.run(main())

Agent Mode

Trigger complex workflows using the Agent API.

complex_task.py
# Submit a complex request that requires planning and assets
resp = client.submit_agent("Create a 15s social media ad for my sneakers")
task_id = resp.get("task_id")

# The agent takes care of the rest
result = client.wait_for_agent_completion(task_id)
print(f"Agent Output: {result.video_url}")

Concurrency Limiting

Check your current rate limits or throttle client-side requests.

python
# Check current rate limit status
status = client.check_concurrency("standard")
print(f"Standard: {status.summary['standard'].used}/{status.summary['standard'].limit}")

# Client-side limit (capped at server limit)
client = VCursor(api_key="your_api_key", max_concurrency=10)