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 4.5, Runway, OmniHuman, ElevenLabs, Cartesia, Fish Audio, 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 images, seed. 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 /api/generate/[shotId] 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 (zero markup) or Varosity Credits (~5% markup). The user picks per provider in Settings.

Authentication

One token. Every surface.

Issue a vsk_... bearer token at /app/keys/api-keys. The same 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 Desktop, Cursor, or any MCP host.

Varosity speaks JSON-RPC 2.0 over Streamable HTTP at /api/mcp. Methods: initialize, tools/list, tools/call, ping. Tools include list_models, generate_video, generate_voice, generate_music, get_job, render_project, suggest_model.

{
  "mcpServers": {
    "varosity": {
      "url": "https://varosity.ai/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer vsk_..."
      }
    }
  }
}

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