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:
- BYOK header (
X-Provider-Key-*) — $0 varg cost
- Dashboard-saved BYOK key — $0 varg cost
- Varg pooled key — metered billing via credits
Provider keys
| Provider | Header | Env var | Get key at |
|---|
| Fal | X-Provider-Key-Fal | FAL_KEY | fal.ai/dashboard/keys |
| ElevenLabs | X-Provider-Key-ElevenLabs | ELEVENLABS_API_KEY | elevenlabs.io/app/settings/api-keys |
| Higgsfield | X-Provider-Key-Higgsfield | HIGGSFIELD_API_KEY | higgsfield.ai |
| Replicate | X-Provider-Key-Replicate | REPLICATE_API_TOKEN | replicate.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
| Scenario | Use |
|---|
| Getting started, small projects | Credits — simplest, one key |
| High volume production | BYOK — use provider pricing directly |
| Need specific provider features | BYOK — full access to provider API |
| Team with existing provider accounts | BYOK — reuse existing keys |
| Prototyping, learning | Credits — no provider setup needed |
