Agent guide

Build agents with one API endpoint.

Varosity AI gives agents and developers a single API for AI media generation across every major provider. One vsk_... key reaches Veo 3.1, Kling 3.0, Seedance 2.0, Runway, GPT Image 2, Nano Banana Pro, Grok Imagine, ElevenLabs, Suno, and more. We handle provider-specific request shapes, async job orchestration, capability discovery, and billing. You send one request shape, we return one response shape.

Get an API key OpenAPI 3.1 llms.txt

Why this shape.

One request shape, every model

Submit a normalized GenerateShotRequest — model, prompt, duration, aspect ratio, reference image. We translate per provider and normalize the response back. Zero per-vendor boilerplate in your agent code.

Async jobs, no hangs

Submit returns a job id immediately. Poll GET /api/v1/jobs/{jobId} or drive the MCP get_job tool. A 60-second video render never blocks your agent's response path.

BYOK or Varosity Credits, per provider

Your agent uses a single Varosity key. Under the hood, each provider is billed either from the user's own provider key or Varosity Credits — the provider's list price either way, no markup. The user picks per provider in Settings.

Authentication

One token. Every surface.

No key yet? An agent that can make HTTP calls gets its own: POST /api/v1/agent/connect, show the user the returned link, then poll /api/v1/agent/connect/poll for api_key (the user approves once and picks a daily limit). Otherwise the user creates one in one click at /agent/key or on the API Keys page. The same vsk_... token works for MCP, REST, and the CLI. Format: vsk_<43-char-base64url>. Only the SHA-256 hash is stored; the plaintext is shown exactly once.

Canonical header

Authorization: Bearer vsk_...

MCP · recommended

Drop into Claude Code, Cursor, Windsurf, or any MCP host (Claude Desktop: npx tab, or add it as a connector).

Two transports, same tools. Remote hosts speak JSON-RPC 2.0 over Streamable HTTP at /api/mcp; stdio-only hosts run npx -y @varosity/mcp-server instead. Methods: initialize, tools/list, tools/call, ping. Tools include list_models, generate_video, generate_image, generate_voice, generate_music, get_job, render_project, suggest_model.

Install in four steps

1. No key needed in hosts that sign in: in Claude Code, add the URL (Claude Code tab below) and run /mcp → Authenticate. For a key instead: agents call POST https://varosity.ai/api/v1/agent/connect (your human approves once). People: /agent/key.
2. Paste the config for your host below.
3. Restart the host.
4. Prove it: tools/list shows the Varosity tools.

# No key needed: add it, then run /mcp → varosity → Authenticate
claude mcp add --transport http varosity https://varosity.ai/api/mcp

# Or with a key (every tool, the key's own daily cap)
claude mcp add --transport http varosity https://varosity.ai/api/mcp \
  --header "Authorization: Bearer vsk_..."

# Or local stdio via the npm package
claude mcp add varosity --env VAROSITY_API_KEY=vsk_... \
  -- npx -y @varosity/mcp-server

# Prove it: tools/list should include generate_video, get_job, ...
claude mcp list

Cursor and Windsurf take the remote url / headers shape above (Gemini CLI calls the field httpUrl; Cline needs "type": "streamableHttp"). Hosts that only run local servers use the npx config. In Claude Desktop or Claude.ai, the simplest path is Customize → Connectors → add https://varosity.ai/api/mcp and sign in.

REST

JSON in, JSON out.

Prefer straight HTTP? The REST surface covers the same ground as MCP. Submit is fire-and-forget; poll until status === "succeeded". See /api/openapi.json for the full schema.

# One call — no project or shot setup required.
curl -X POST https://varosity.ai/api/v1/video/generate \
  -H "Authorization: Bearer vsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "veo-3.1",
    "prompt": "A lighthouse keeper at dusk, cinematic, shallow DOF.",
    "aspectRatio": "16:9",
    "durationSec": 8
  }'
# → { ok: true, jobId: "..." }

CLI

Same API, from the terminal.

@varosity/cli wraps the MCP surface. Every command accepts --json for script-friendly output. Subcommands: models, voices, projects, generate, job, render, route suggest.

npm install -g @varosity/cli
varosity login                                  # paste your vsk_ token
varosity models list --kind video --json
varosity generate video veo-3.1 \
  --prompt "slow push-in on a rain-slicked alley" \
  --duration 8 --out shot.mp4
# → Submitted · jobId <uuid>
# → [0s] rendering
# → [6s] succeeded
# → Output · https://...
# → Saved 3145728 bytes

Coach surface

Self-describing best practices.

Pull curated best-practice tips for any surface or model: GET /api/v1/tips?surface=storyboard-canvas&model=veo-3.1. Useful for agents that auto-explain their choices, or for prompt builders that want to surface model-specific advice inline.

Browse /api/v1/tips llms.txt agents.json