Skip to main content
The varg Gateway provides a single REST API for AI generation across multiple providers (Fal, ElevenLabs, Higgsfield, Replicate, PiAPI). One API key, server-side caching, and stable output URLs at s3.varg.ai.

​
Base URL

https://api.varg.ai/v1

​
Authentication

All requests require a varg API key: 
Authorization: Bearer varg_xxx
Get your API key at app.varg.ai or run bunx vargai login. See Authentication for details.

​
Bring Your Own Key (BYOK)

You can also pass your own provider keys to bypass varg billing. See the BYOK guide for a full tutorial. 
X-Provider-Key-Fal: fal_xxx
X-Provider-Key-ElevenLabs: el_xxx

​
Quick Start

Generate a video and poll for the result: 
# Create job
curl -X POST https://api.varg.ai/v1/video \
  -H "Authorization: Bearer varg_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-v3", "prompt": "cat jumping over a fence"}'

# Response
# {"job_id": "job_a1b2c3d4", "status": "queued", "model": "fal:kling-v2.5", "created_at": "2026-02-13T10:00:00Z"}

# Poll until complete
curl https://api.varg.ai/v1/jobs/job_a1b2c3d4 \
  -H "Authorization: Bearer varg_xxx"

# Response when done
# {"job_id": "job_a1b2c3d4", "status": "completed", "output": {"url": "https://s3.varg.ai/o/job_a1b2c3d4.mp4", "media_type": "video/mp4"}, ...}

​
TypeScript SDK

The vargai package provides a high-level provider for AI SDK integration: 
bun add vargai

import { createVarg } from "vargai/ai";

const varg = createVarg({ apiKey: "varg_xxx" });

// Use with AI SDK
const { images } = await generateImage({
  model: varg.imageModel("nano-banana-pro"),
  prompt: "sunset over mountains",
});
For low-level REST API access, the @vargai/gateway package exposes VargClient: 
bun add @vargai/gateway

import { VargClient } from "@vargai/gateway";

const client = new VargClient({ apiKey: "varg_xxx" });

​
Generate video

// Create job and wait for completion
const job = await client.createVideo({
  model: "kling-v3",
  prompt: "cat jumping over a fence in slow motion",
  duration: 5,
  aspect_ratio: "16:9",
});

const result = await client.waitForJob(job.job_id);
console.log(result.output.url); // https://s3.varg.ai/o/job_xxx.mp4

// Image-to-video
const i2vJob = await client.createVideo({
  model: "kling-v3",
  prompt: "cat turns and looks at camera",
  files: [{ url: "https://example.com/cat.jpg" }],
});

​
Generate image

const job = await client.createImage({
  model: "flux-schnell",
  prompt: "sunset over mountains, dramatic lighting",
  aspect_ratio: "16:9",
});

const result = await client.waitForJob(job.job_id);
console.log(result.output.url); // https://s3.varg.ai/o/job_xxx.jpg

​
Generate speech

const job = await client.createSpeech({
  model: "eleven_v3",
  text: "Hello everyone! Welcome to my channel.",
  voice: "rachel", // rachel, domi, sarah, antoni, elli, josh, arnold, adam, sam
});

const result = await client.waitForJob(job.job_id);
console.log(result.output.url); // https://s3.varg.ai/o/job_xxx.mp3

​
Upload a file

const file = await fs.readFile("./photo.jpg");

const uploaded = await client.uploadFile(file, "image/jpeg");

console.log(uploaded.url); // https://s3.varg.ai/u/user_xxx/abc123.jpg

// Use in generation
const job = await client.createVideo({
  model: "kling-v2.5",
  prompt: "photo comes to life",
  files: [{ url: uploaded.url }],
});

​
Model resolution

Models can be specified as provider:model or just the model name. The gateway resolves the provider automatically. 
{ "model": "fal:kling-v2.5" }  // explicit
{ "model": "kling-v2.5" }      // auto-resolved to fal
{ "model": "soul" }            // auto-resolved to higgsfield
ModelProvider
kling-v3, kling-v2.6, kling-v2.5Fal
seedance-2-preview, seedance-2-fast-previewPiAPI
wan-2.5, minimax, ltxFal
nano-banana-pro, flux-schnell, flux-proFal
sync-v2, sync-v2-pro, omnihumanFal
recraft-v3Fal
eleven_v3, eleven_multilingual_v2, eleven_flash_v2_5ElevenLabs
music_v1ElevenLabs
soulHiggsfield
background-removerReplicate
whisperFal

​
Caching

All generations are cached. Same parameters return instantly from cache at no cost. The cache key is computed from: capability, model, prompt, duration/aspect ratio, and file content hashes (not URLs). Response headers: 
X-Cache: HIT
X-Cache-Key: sha256:abc123...
X-Cache-TTL: 2592000
Bypass cache: 
Cache-Control: no-cache   # skip lookup, still store result
Cache-Control: no-store   # skip cache entirely

​
Billing

Cache hits are free. Only cache misses with pooled keys are billed. BYOK users pay $0 varg cost. You’re billed directly by the provider. Key resolution order:
  1. X-Provider-Key-* header — BYOK, $0
  2. Dashboard-saved key — BYOK, $0
  3. Varg pooled key — metered billing

​
Error codes

StatusErrorDescription
400ValidationErrorInvalid request body
401AuthErrorMissing or invalid API key
402InsufficientBalanceErrorAccount balance too low
404NotFoundErrorJob or file not found
413—File too large (max 50MB)
429RateLimitErrorToo many requests
500InternalErrorServer error
502ProviderErrorUpstream provider failed
Error responses follow this shape: 
{
  "error": "ValidationError",
  "message": "prompt is required",
  "field": "prompt",
  "statusCode": 400
}

​
Rate limits

PlanRequests/minuteConcurrent jobs
Free102
Pro10010
EnterpriseCustomCustom