SDKs

Official client libraries for Python and TypeScript. Both SDKs provide type-safe interfaces, automatic retries, rate limit handling, and SSE streaming support.

Python SDK

envizion

Installation

Terminal

pip install envizion

Requires Python 3.9+. Uses httpx for HTTP transport.

Quick Start

Python

from envizion import EnvizionClient

# Initialize the client
client = EnvizionClient(api_key="vk_your_api_key")

# List available agents
agents = client.agents.list()
for agent in agents:
    print(f"{agent.name} ({agent.slug}) - {len(agent.tools)} tools")

# Create and execute a run
run = client.runs.create(
    agent_id="creative_director",
    inputs={
        "topic": "SpaceX Starship launch highlights",
        "style": "cinematic",
        "duration": 60,
    }
)
print(f"Run started: {run.id} (status: {run.status})")

# Stream real-time progress
for event in client.runs.stream(run.id):
    print(f"  [{event.get('type')}] {event.get('tool', '')}")

# Wait for completion (alternative to streaming)
completed_run = client.runs.wait(run.id, poll_interval=2.0, timeout=600)
print(f"Result: {completed_run.result}")

# Download the rendered video
download_url = client.renders.download_url(completed_run.result["render_id"])
print(f"Download: {download_url}")

# Clean up
client.close()

Context Manager

Python

# Automatically closes the client when done
with EnvizionClient(api_key="vk_...") as client:
    agents = client.agents.list()
    run = client.runs.create(agent_id="creative_director", inputs={...})

Resource Methods

client.agents

Python

# List agents (paginated)
agents = client.agents.list(page=1, limit=20)

# Get a single agent by ID or slug
agent = client.agents.get("creative_director")

# Create a new agent
agent = client.agents.create(
    name="My Agent",
    tools=["write_script", "source_assets"],
    description="Custom video pipeline",
    pipeline_type="sequential"
)

# Delete an agent
client.agents.delete("agent-uuid-here")

client.runs

Python

# Create a run
run = client.runs.create(
    agent_id="creative_director",
    inputs={"topic": "AI news recap"},
    project_id="existing-project-uuid"  # optional
)

# Get run status
run = client.runs.get("run-id")
print(run.status)  # pending, running, completed, failed, cancelled

# Stream SSE events
for event in client.runs.stream("run-id"):
    if event["type"] == "tool_complete":
        print(f"Tool {event['tool']} finished")

# Cancel a running execution
client.runs.cancel("run-id")

# Poll until completion (blocking)
run = client.runs.wait("run-id", poll_interval=2.0, timeout=600)

client.marketplace

Python

# Browse templates
templates = client.marketplace.list_templates(category="sports")

# Get template details
template = client.marketplace.get_template("sports_highlight_reel")

# Install a template as your own agent
agent = client.marketplace.install_template("sports_highlight_reel")

client.credits

Python

# Check balance
wallet = client.credits.balance()
print(f"Balance: {wallet.balance} credits ({wallet.plan_name})")

# List recent transactions
transactions = client.credits.transactions(limit=10)

client.renders

Python

# Trigger a render
job = client.renders.trigger(
    project_id="proj_xyz789",
    options={"resolution": "1080p", "codec": "h264"}
)

# Check render progress
job = client.renders.status("render-id")
print(f"Progress: {job.progress}%")

# Get download URL
url = client.renders.download_url("render-id")

client.keys

Python

# List API keys (prefix only, never the full secret)
keys = client.keys.list()

# Create a new key
new_key = client.keys.create(
    name="CI/CD Key",
    scopes=["read", "write"],
    expires_in_days=30
)
print(f"New key: {new_key.key}")  # Only shown once!

# Rotate a key (revokes old, creates new with same config)
rotated = client.keys.rotate("key-id")
print(f"Rotated key: {rotated.key}")

# Revoke a key
client.keys.revoke("key-id")

client.webhooks

Python

# Create a webhook (secret returned only once!)
result = client.webhooks.create(
    url="https://your-app.com/webhooks/vision",
    events=["run.completed", "render.completed"]
)
print(f"Secret: {result['secret']}")

# List webhooks
hooks = client.webhooks.list()

# Send a test event
test_result = client.webhooks.test("webhook-id")

# List available event types
events = client.webhooks.list_events()

# Delete a webhook
client.webhooks.delete("webhook-id")

Error Handling

Python

from envizion.exceptions import (
    EnvizionError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    InsufficientCreditsError,
    ValidationError,
    ServerError,
)

try:
    run = client.runs.create(agent_id="invalid", inputs={})
except AuthenticationError:
    print("Bad API key or insufficient scopes")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except NotFoundError:
    print("Agent not found")
except InsufficientCreditsError:
    print("Not enough credits")
except ValidationError as e:
    print(f"Invalid request: {e}")
except ServerError:
    print("Server error -- will auto-retry up to 3 times")
except EnvizionError as e:
    print(f"General error: {e} (status={e.status_code})")

Webhook Verification Helper

Python

from envizion.webhooks import verify_webhook_signature

# In your webhook handler:
is_valid = verify_webhook_signature(
    payload=request.body,         # raw bytes or string
    signature=request.headers["X-Vision-Signature"],
    secret="whsec_your_secret",
    tolerance=300                  # max age in seconds (5 min)
)

if not is_valid:
    return Response(status_code=401)

TypeScript SDK

@envizion/sdk

Installation

Terminal

npm install @envizion/sdk

Works in Node.js 18+, Deno, Bun, and edge runtimes. Uses the Fetch API.

Quick Start

TypeScript

import { EnvizionClient } from "@envizion/sdk";

// Initialize the client
const client = new EnvizionClient("vk_your_api_key");

// List available agents
const agents = await client.agents.list();
agents.forEach(a => console.log(`${a.name} (${a.slug})`));

// Create and execute a run
const run = await client.runs.create({
  agentId: "creative_director",
  inputs: {
    topic: "SpaceX Starship launch highlights",
    style: "cinematic",
    duration: 60,
  },
});
console.log(`Run started: ${run.id}`);

// Stream real-time progress
for await (const event of client.runs.stream(run.id)) {
  console.log(`  [${event.type}] ${event.tool ?? ""}`);
}

// Get final result
const completed = await client.runs.get(run.id);
console.log("Result:", completed.result);

// Download the rendered video
const url = await client.renders.downloadUrl(completed.result.renderId);
console.log(`Download: ${url}`);

Resource Methods

client.agents

TypeScript

// List agents
const agents = await client.agents.list({ page: 1, limit: 20 });

// Get a single agent
const agent = await client.agents.get("creative_director");

// Create an agent
const newAgent = await client.agents.create({
  name: "My Agent",
  tools: ["write_script", "source_assets"],
  pipelineType: "sequential",
});

// Delete an agent
await client.agents.delete("agent-uuid");

client.runs

TypeScript

// Create a run
const run = await client.runs.create({
  agentId: "creative_director",
  inputs: { topic: "AI news recap" },
});

// Get run status
const status = await client.runs.get(run.id);

// Stream SSE events (async iterator)
for await (const event of client.runs.stream(run.id)) {
  if (event.type === "tool_complete") {
    console.log(`Tool ${event.tool} finished`);
  }
}

// Cancel a running execution
await client.runs.cancel(run.id);

// Poll until completion
const completed = await client.runs.wait(run.id, {
  pollInterval: 2000,
  timeout: 600000,
});

client.marketplace

TypeScript

// Browse templates
const templates = await client.marketplace.listTemplates("sports");

// Get template details
const template = await client.marketplace.getTemplate("sports_highlight_reel");

// Install a template
const agent = await client.marketplace.installTemplate("sports_highlight_reel");

client.credits

TypeScript

// Check balance
const wallet = await client.credits.balance();
console.log(`Balance: ${wallet.balance} (${wallet.planName})`);

// List transactions
const txns = await client.credits.transactions({ limit: 10 });

client.renders

TypeScript

// Trigger a render
const job = await client.renders.trigger({
  projectId: "proj_xyz789",
  options: { resolution: "1080p", codec: "h264" },
});

// Check progress
const status = await client.renders.status(job.id);
console.log(`Progress: ${status.progress}%`);

// Get download URL
const url = await client.renders.downloadUrl(job.id);

client.keys

TypeScript

// List API keys
const keys = await client.keys.list();

// Create a new key
const newKey = await client.keys.create({
  name: "CI/CD Key",
  scopes: ["read", "write"],
  expiresInDays: 30,
});
console.log(`New key: ${newKey.key}`); // Only shown once!

// Rotate a key
const rotated = await client.keys.rotate("key-id");

// Revoke a key
await client.keys.revoke("key-id");

client.webhooks

TypeScript

// Create a webhook
const hook = await client.webhooks.create({
  url: "https://your-app.com/webhooks/vision",
  events: ["run.completed", "render.completed"],
});
console.log(`Secret: ${hook.secret}`);

// List webhooks
const hooks = await client.webhooks.list();

// Test a webhook
const result = await client.webhooks.test("webhook-id");

// Delete a webhook
await client.webhooks.delete("webhook-id");

Error Handling

TypeScript

import {
  EnvizionError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  InsufficientCreditsError,
  ValidationError,
  ServerError,
} from "@envizion/sdk";

try {
  const run = await client.runs.create({ agentId: "invalid" });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof AuthenticationError) {
    console.log("Bad API key or insufficient scopes");
  } else if (err instanceof NotFoundError) {
    console.log("Resource not found");
  } else if (err instanceof InsufficientCreditsError) {
    console.log("Not enough credits");
  } else if (err instanceof EnvizionError) {
    console.log(`API error: ${err.message} (status=${err.statusCode})`);
  }
}

Webhook Verification Helper

TypeScript

import { verifyWebhookSignature } from "@envizion/sdk";
import crypto from "crypto";

// In your Express/Hono handler:
app.post("/webhooks/vision", async (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers["x-vision-signature"] as string;

  const isValid = verifyWebhookSignature({
    payload,
    signature,
    secret: "whsec_your_secret",
    tolerance: 300, // 5 minutes
  });

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Process the event...
  res.json({ ok: true });
});

Runtime Compatibility

Runtime	Version	Status
Node.js	18+	Supported
Deno	1.28+	Supported
Bun	1.0+	Supported
Cloudflare Workers	-	Supported
Vercel Edge	-	Supported

Client Configuration

Both SDKs accept configuration options at initialization:

Python

client = EnvizionClient(
    api_key="vk_...",
    base_url="https://api.envizion.ai/v1",
    timeout=30.0,     # Request timeout (seconds)
    max_retries=3,    # Auto-retry on 429/5xx
)

TypeScript

const client = new EnvizionClient("vk_...", {
  baseUrl: "https://api.envizion.ai/v1",
  timeout: 30000,    // Request timeout (ms)
  maxRetries: 3,     // Auto-retry on 429/5xx
});

→Endpoint Reference →Webhook Guide →Error Reference