Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.varg.ai/llms.txt

Use this file to discover all available pages before exploring further.

BYOK (Bring Your Own Key) lets you use your own provider API keys through the varg gateway. You still get caching, stable URLs, and unified API — but you’re billed directly by the provider instead of through varg credits.
You still need a VARG_API_KEY even with BYOK. It authenticates you with the gateway. BYOK just changes who pays for the AI generation.

​
Why BYOK?

  • $0 varg cost — you pay the provider directly
  • Own quotas — use your own rate limits and billing
  • Same gateway features — caching, stable URLs, unified API
  • Mix and match — use BYOK for some providers, varg credits for others

​
How it works

When a request reaches the gateway, it resolves the API key in this order:
  1. BYOK header (X-Provider-Key-*) — $0 varg cost
  2. Dashboard-saved BYOK key — $0 varg cost
  3. Varg pooled key — metered billing via credits

​
Provider keys

ProviderHeaderEnv varGet key at
FalX-Provider-Key-FalFAL_KEYfal.ai/dashboard/keys
ElevenLabsX-Provider-Key-ElevenLabsELEVENLABS_API_KEYelevenlabs.io/app/settings/api-keys
HiggsfieldX-Provider-Key-HiggsfieldHIGGSFIELD_API_KEYhiggsfield.ai
ReplicateX-Provider-Key-ReplicateREPLICATE_API_TOKENreplicate.com/account/api-tokens

​
Quick tutorial

​
Gateway API (curl)

Pass your provider key as a header alongside your varg key: 
# Generate an image using your own Fal key ($0 varg cost)
curl -X POST https://api.varg.ai/v1/image \
  -H "Authorization: Bearer varg_xxx" \
  -H "X-Provider-Key-Fal: fal_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-pro", "prompt": "sunset over mountains"}'

​
Cloud Render

Pass BYOK keys in the request body: 
curl -s -X POST https://render.varg.ai/api/render \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "export default (<Render width={1920} height={1080}><Clip duration={3}>{Image({ model: fal.imageModel(\"nano-banana-pro\"), prompt: \"mountains\" })}</Clip></Render>);",
    "providerKeys": {
      "fal": "fal_xxx",
      "elevenlabs": "el_xxx"
    }
  }'

​
Local Render (TypeScript)

Pass provider keys when creating the varg client: 
/** @jsxImportSource vargai */
import { Render, Clip, Image } from "vargai/react"
import { createVarg } from "vargai/ai"

const varg = createVarg({
  apiKey: process.env.VARG_API_KEY!,
  providerKeys: {
    fal: process.env.FAL_KEY!,
    elevenlabs: process.env.ELEVENLABS_API_KEY!,
  },
})

const img = Image({
  model: varg.imageModel("nano-banana-pro"),
  prompt: "a cabin in mountains at sunset",
  aspectRatio: "16:9",
})

export default (
  <Render width={1920} height={1080}>
    <Clip duration={3}>{img}</Clip>
  </Render>
)

​
.env setup for BYOK

# Required
VARG_API_KEY=varg_xxx

# BYOK provider keys (optional — only include the ones you have)
FAL_KEY=fal_xxx
ELEVENLABS_API_KEY=xxx
HIGGSFIELD_API_KEY=hf_xxx
REPLICATE_API_TOKEN=r8_xxx

​
Caching with BYOK

BYOK requests use the same cache as pooled requests. The cache key is based on the request parameters (prompt, model, etc.), not the API key used. This means:
  • If a result is already cached from a previous pooled request, your BYOK request gets the cached result at $0
  • If you generate something new with BYOK, subsequent requests (pooled or BYOK) get the cached result

​
When to use BYOK vs credits

ScenarioUse
Getting started, small projectsCredits — simplest, one key
High volume productionBYOK — use provider pricing directly
Need specific provider featuresBYOK — full access to provider API
Team with existing provider accountsBYOK — reuse existing keys
Prototyping, learningCredits — no provider setup needed