varg API

The varg API is a single REST API for AI media generation across providers such as fal, Google, OpenAI, ElevenLabs, Black Forest Labs, HeyGen, Higgsfield, PiAPI, Together, Groq and Rendi. One API key, 120+ models, async jobs, stable output URLs at s3.varg.ai, and transparent credit billing.

Base URL

https://api.varg.ai/v2

The OpenAPI 3.1 spec is at https://api.varg.ai/v2/openapi.json. Use it to generate a typed client or import the API into Postman. See OpenAPI spec.

Authentication

All requests (except GET /pricing) 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.

Core concepts

The API vocabulary has three levels:

Concept	Example	What it is
Tool	`image`, `video`, `speech`	A capability. Each tool has its own endpoint (`POST /v2/image`) and unified input schema.
Model	`flux_schnell`, `kling_v3`	What you put in the `model` field. One model can be served by multiple providers.
Provider	`fal`, `elevenlabs`	Who actually runs the generation. varg picks the best provider automatically.

Tools: image, video, speech, music, transcription, ffmpeg, render, pipeline. Discover them at runtime via GET /v2/tools. Some parameters — vendor voice ids, style ids, avatar ids — are values you cannot guess and that silently fail when placed at the wrong path. The Presets catalogue (/v2/presets) browses, filters, and safely applies those values for you.

Quick start

Every generation is an async job: create it, poll until terminal, read the output URL.

# 1. Create a job (202 Accepted)
JOB=$(curl -s -X POST https://api.varg.ai/v2/video \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling_v3", "prompt": "cat jumping over a fence", "duration": 5}')

JOB_ID=$(echo $JOB | jq -r '.id')

# 2. Poll until status is terminal
curl -s https://api.varg.ai/v2/jobs/$JOB_ID \
  -H "Authorization: Bearer $VARG_API_KEY" | jq '{status, output}'

# 3. When completed, the video URL is in output.outputs[0].url
# {
#   "status": "completed",
#   "output": {
#     "version": "v1",
#     "outputs": [{
#       "url": "https://s3.varg.ai/files/acc_x/file_abc.mp4",
#       "file_id": "file_abc123",
#       "media_type": "video/mp4"
#     }]
#   }
# }

Creation responses include ready-made lifecycle URLs:

{
  "id": "job_a1b2c3d4e5f6",
  "status": "queued",
  "estimated_cost_cents": 221,
  "urls": {
    "self": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6",
    "status": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/status",
    "cancel": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/cancel",
    "retry": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/retry",
    "refresh": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/refresh"
  }
}

Job lifecycle

queued → running → completed | failed | cancelled

The status only moves forward. What a running job is doing right now is its stage:

Status	Stage	Meaning
`queued`	`queued`	Accepted, waiting for a provider slot
`running`	`submitting`	Being sent to the provider
`running`	`uploading_references`	The provider is taking your reference files into its asset library — `progress_message` shows `uploading references to ByteDance (1/2)`
`running`	`rendering`	The provider is generating
`running`	`retrying`	The provider refused or failed; the job is moving to the next provider (see `attempts`)
`running`	`finalizing`	Saving the result
`completed`	—	Done — read `output.outputs[0].url`
`failed`	—	Check the `error` field; retry with `POST /jobs/{id}/retry`
`cancelled`	—	Aborted via `POST /jobs/{id}/cancel`

When a provider refuses a request — a real person in the references, a content policy, a full queue — varg tries the next provider for the same model instead of failing the job. Every provider tried is listed in attempts, with a short reason and a reason_code for the ones that failed:

{
  "status": "running",
  "stage": "rendering",
  "progress_message": "rendering on piapi",
  "attempts": [
    { "n": 1, "provider": "byteplus", "model_key": "byteplus:dreamina-seedance-2-5-260628",
      "status": "failed", "reason": "real person in the reference images",
      "reason_code": "content_privacy", "started_at": "…", "ended_at": "…" },
    { "n": 2, "provider": "piapi", "model_key": "piapi:seedance-2.5-less-restriction",
      "status": "running", "started_at": "…", "ended_at": null }
  ]
}

reason_code is one of content_privacy, content_policy, quota, rate_limit, provider_error, timeout, expired, prompt_too_long. Poll GET /v2/jobs/{id} (full view) or GET /v2/jobs/{id}/status (lightweight: status, stage, progress 0..1 and progress_message). Treat queued and running as in progress. A stuck job is guaranteed to reach a terminal status: every attempt has a time limit, and a submit interrupted by a restart is retried automatically.

Instead of polling, set options.webhook_url in your request. When the job finishes, varg POSTs the job snapshot (including stage and attempts) to your URL, signed with X-Varg-Signature: v1=<hmac-sha256>, with 8 retries and exponential backoff.

Request format

All generation endpoints take a flat JSON body: model plus tool-specific fields at the top level.

{
  "model": "kling_v3",
  "prompt": "cat jumping over a fence",
  "duration": 5,
  "aspect_ratio": "16:9",
  "files": [{ "url": "https://s3.varg.ai/files/acc_x/cat.jpg" }],
  "provider_options": { "fal": { "seed": 42 } },
  "options": { "webhook_url": "https://example.com/hook" }
}

Field	Applies to	Description
`model`	all	Model id — required
`prompt`	image, video, music	Text prompt (max 2000 chars)
`text`	speech	Text to speak (max 10000 chars)
`voice`	speech	Voice name
`audio_url`	transcription	Public URL of the audio file
`duration`	video, music	Seconds
`aspect_ratio`	image, video	e.g. `"16:9"`, `"9:16"`
`files`	image, video	Input files by URL (max 10) — start frames, edit sources, lipsync inputs
`provider_options`	all	Provider-native overrides, keyed by provider
`options.webhook_url`	all	Completion webhook

Media inputs are always passed by URL — upload local files first via POST /v2/files to get a stable varg URL.

Model resolution

Most requests should just use the model name. Pass a canonical varg name (seedance_2, kling_v3, flux_schnell) and varg auto-routes by priority and input shape — if your request includes files, routes that map files are preferred; the first route whose schema accepts your input wins.

{ "model": "seedance_2" }   // canonical name — varg picks the route (recommended)

For advanced control, two more address forms exist:

{ "model": "fal:seedance_2" }                                      // provider prefix — routes filtered to fal
{ "model": "fal:bytedance/seedance-2.0/fast/reference-to-video" }  // exact model_key — pins one route

Provider prefix — same auto-routing, restricted to routes on that provider.
Exact model_key — pins one specific route. model_key values are a permanent public contract and safe to hardcode.

Every route’s model_key is listed in GET /v2/models. Two guarantees:

No silent substitution. varg only picks which route serves the model you named — never a different model family.
Transparent routing. The job records which provider model actually ran (provider, provider_model fields), and POST /v2/estimate returns the resolved_model_key before you submit.

Within a model, input shape can select a variant automatically: sending an image in files to kling_v3 routes to its image-to-video endpoint. Same family, same pricing rules. Model ids use underscores (kling_v3, flux_schnell). Dashed spellings (kling-v3) are accepted and normalized automatically. Browse all models and prices at GET /v2/pricing (public, no auth).

Model catalog

GET /v2/models (public, no auth) returns the full catalog: every model with its routes, pricing, and operational hints. Filter by tool with ?tool=video.

curl -s "https://api.varg.ai/v2/models?tool=video"

{
  "version": "v1",
  "data": [
    {
      "model": "seedance_2",
      "tool": "video",
      "routes": [
        {
          "model_key": "fal:bytedance/seedance-2.0/text-to-video",
          "provider": "fal",
          "modality": ["text-to-video"],
          "output_type": "video",
          "description": "Seedance 2.0 standard tier, up to 4k",
          "priority": 1,
          "accepts_files": false,
          "pricing": {
            "pricing_id": "ppr_...",
            "rule": { "type": "per_second_conditional", "param": "duration", "rates": ["..."] },
            "user_price_estimate_cents": 479
          },
          "ops": {
            "delivery": "webhook",
            "poll_interval_ms": 5000,
            "estimated_duration_ms": 180000,
            "max_timeout_ms": 1800000
          },
          "schema_url": "/v2/tools/video?model=fal:bytedance/seedance-2.0/text-to-video"
        }
      ]
    }
  ]
}

Each route’s model_key can be used directly in the model field to pin that route.

Discovering schemas at runtime

Agents and dynamic clients can discover the full API without reading docs. The discovery reads are public — no key needed (with a key, they also list your team’s private pipelines):

# List all tools
curl -s https://api.varg.ai/v2/tools

# Get the image tool's input schema, output shape, and a worked example
curl -s https://api.varg.ai/v2/tools/image

# Get the explicit per-provider options for a specific model
curl -s "https://api.varg.ai/v2/tools/image?model=flux_schnell"

# A tool's models with routes, prices, a real example and the input schema
curl -s "https://api.varg.ai/v2/tools/image/models?limit=50"

# Call any tool generically (same as POST /v2/image)
curl -s -X POST https://api.varg.ai/v2/tools/image/call \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "flux_schnell", "prompt": "a cat astronaut"}'

Every model’s schema is also published as a readable Markdown spec at https://varg.ai/models/{model}.md — see Model specs for agents.

Pricing and billing

1 credit = 1 cent = $0.01. The billing flow:

Reserve — at job creation, the estimated cost is held from your balance (402 if insufficient).
Commit — on completion, the hold is charged and a usage record written.
Release — on failure, the hold is returned (most models; some bill partial work).

# Price a request WITHOUT creating a job
curl -s -X POST https://api.varg.ai/v2/estimate \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance_2", "prompt": "cat", "duration": 5}'
# {"valid": true, "model": "seedance_2", "tool": "video",
#  "resolved_model_key": "fal:bytedance/seedance-2.0/text-to-video",
#  "pricing": {"user_price_cents": 160, "pricing_id": "ppr_..."}}

# Check your balance
curl -s https://api.varg.ai/v2/billing/balance \
  -H "Authorization: Bearer $VARG_API_KEY"
# {"available": 8200, "reserved": 300, "total_balance": 8500, ...}

Each job carries its pricing in the response: pricing.estimated, pricing.actual, pricing.billed_units (e.g. {"seconds": 6}), and a pricing_id that pins the price rule the job was charged under — mid-flight price changes never affect running jobs.

Caching

Results are cached by canonical input. Repeating an identical request returns a completed job instantly with actual_cost_cents: 0 and pricing.cached: true — cache hits are free.

Idempotency

Pass an Idempotency-Key header on any job-creating POST to make retries safe:

curl -s -X POST https://api.varg.ai/v2/image \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Idempotency-Key: my-unique-key-1" \
  -H "Content-Type: application/json" \
  -d '{"model": "flux_schnell", "prompt": "a cat astronaut"}'

The first request creates the job (202). Retrying with the same key returns the same job (200) — no duplicate charge, no duplicate generation.

Files and lineage

Outputs are mirrored to varg storage and served from stable s3.varg.ai URLs. Every output gets a file record with an AI-generated title, a thumbnail, and lineage back to the job that created it:

# Upload an input file (raw binary body, max 200MB)
curl -s -X POST https://api.varg.ai/v2/files \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: image/jpeg" \
  -H "X-Filename: cat.jpg" \
  --data-binary @cat.jpg
# {"file_id": "file_abc123", "url": "https://s3.varg.ai/files/...", ...}

# Which job made this file? (get the recipe: prompt, model, cost)
curl -s -X POST https://api.varg.ai/v2/lineage \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "file_abc123"}'

Send X-Content-Hash: sha256:<hex> on upload for content deduplication, or pre-check with GET /v2/files/check?hash=.

Error format

All errors use one envelope:

{
  "error": {
    "code": "model_not_found",
    "message": "Unknown model: flux-shnell",
    "details": null
  }
}

Status	Code	Description
400	`invalid_request`, `invalid_json`	Malformed body
401	`unauthorized`	Missing or invalid API key
402	`insufficient_balance`	Balance too low to reserve the estimated cost
404	`model_not_found`, `tool_not_found`, `job_not_found`, `file_not_found`	Unknown resource
409	`conflict`	Cancel: the provider refused to stop a task that is already rendering — it completes and is charged as usual
413	`file_too_large`	Upload over 200 MB
422	`invalid_request`	Body failed schema validation (details included)
429	`rate_limited`	Too many requests — honor `Retry-After`
503	`no_pricing`	Model temporarily has no active pricing

model_not_found errors include suggestions in details: did_you_mean lists close model names, and models_url points to /v2/models for the full catalog.

Rate limits

Rate limiting is a sliding window per API key. Every job-creation response carries:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 2026-07-01T10:01:00.000Z

On 429, wait for Retry-After seconds and retry (ideally with the same Idempotency-Key).

Migrating from v1

The v1 gateway (api.varg.ai/v1) is frozen. Key differences in v2:

v1	v2
`job_id` field	`id` field
`output.url` (single)	`output.outputs[]` (array, each with `file_id`)
`GET /jobs/{id}/stream` (SSE)	Removed — poll or use `options.webhook_url`
`DELETE /jobs/{id}`	`POST /jobs/{id}/cancel`
`GET /balance`	`GET /billing/balance` (richer breakdown)
`GET /usage`	`GET /billing/usage`
`POST /ffmpeg/trim` etc.	Single `POST /ffmpeg`, operation selected by `model`
`POST /ffmpeg/probe`	`POST /files/probe`
`GET /voices`	Not yet ported — pass `voice` by name
Model names with dashes	Underscores canonical (dashes still accepted)
Flat error shape	`{"error": {"code", "message"}}` envelope

Overview

Presets

Generation

Tools

Jobs

Files

Folders

Templates

Pricing & Billing

Analytics

Account

Base URL

Authentication

Core concepts

Quick start

Job lifecycle

Request format

Model resolution

Model catalog

Discovering schemas at runtime

Pricing and billing

Caching

Idempotency

Files and lineage

Error format

Rate limits

Migrating from v1

​Base URL

​Authentication

​Core concepts

​Quick start

​Job lifecycle

​Request format

​Model resolution

​Model catalog

​Discovering schemas at runtime

​Pricing and billing

​Caching

​Idempotency

​Files and lineage

​Error format

​Rate limits

​Migrating from v1

Base URL

Authentication

Core concepts

Quick start

Job lifecycle

Request format

Model resolution

Model catalog

Discovering schemas at runtime

Pricing and billing

Caching

Idempotency

Files and lineage

Error format

Rate limits

Migrating from v1