vargai

Environment Detection#

Before generating anything, determine the rendering mode.

Run bash scripts/setup.sh from the skill directory to auto-detect, or check manually:

bunffmpegModeNoNoCloud Render -- read cloud-render.mdYesNoCloud Render -- read cloud-render.mdYesYesLocal Render (recommended) -- read local-render.md

VARG_API_KEY is required for all modes. Get one at https://varg.ai

Critical Rules#

Everything you know about varg is likely outdated. Always verify against this skill and its references before writing code.

1. Never guess model IDs -- consult models.md for current models, pricing, and constraints.
2. Function calls for media, JSX for composition -- Image({...}) creates media, <Clip> composes timeline. Never write <Image prompt="..." />.
3. Cache is sacred -- identical prompt + params = instant $0 cache hit. When iterating, keep unchanged prompts EXACTLY the same. Never clear cache.
4. One image per Video -- Video({ prompt: { images: [img] } }) takes exactly one image. Multiple images cause errors.
5. Duration constraints differ by model -- kling-v3: 3-15s (integer only). kling-v2.5: ONLY 5 or 10. Check models.md.
6. Gateway namespace -- use providerOptions: { varg: {...} }, never fal, when going through the gateway (both modes).
7. Renders cost money -- 1 credit = 1 cent. A typical 3-clip video costs $2-5. Use preview mode (local) or cheap models to iterate.

Quick Start#

Cloud Render (no bun/ffmpeg needed)#

bash

# Submit TSX code to the render service
curl -s -X POST https://render.varg.ai/api/render \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "const img = Image({ model: fal.imageModel(\"nano-banana-pro\"), prompt: \"a cabin in mountains at sunset\", aspectRatio: \"16:9\" });\nexport default (<Render width={1920} height={1080}><Clip duration={3}>{img}</Clip></Render>);"}'

# Poll for result (repeat until "completed" or "failed")
curl -s https://render.varg.ai/api/render/jobs/JOB_ID \
  -H "Authorization: Bearer $VARG_API_KEY"

Full details: cloud-render.md

Local Render (bun + ffmpeg)#

tsx

/** @jsxImportSource vargai */
import { Render, Clip, Image } from "vargai/react"
import { createVarg } from "@vargai/gateway"

const varg = createVarg({ apiKey: process.env.VARG_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>
)

bash

bunx vargai render video.tsx --preview   # free preview
bunx vargai render video.tsx --verbose   # full render (costs credits)

Full details: local-render.md

Single Asset (no video composition)#

For one-off images, videos, speech, or music without building a multi-clip template:

bash

curl -X POST https://api.varg.ai/v1/image \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -d '{"model": "nano-banana-pro", "prompt": "a sunset over mountains"}'

Full API reference: gateway-api.md

How to Write Video Code#

Video code has two layers: media generation (function calls) and composition (JSX).

tsx

// 1. GENERATE media via function calls
const img = Image({ model: ..., prompt: "..." })
const vid = Video({ model: ..., prompt: { text: "...", images: [img] }, duration: 5 })
const voice = Speech({ model: ..., voice: "rachel", children: "Hello!" })

// 2. COMPOSE via JSX tree
export default (
  <Render width={1080} height={1920}>
    <Music model={...} prompt="upbeat electronic" duration={10} volume={0.3} />
    <Clip duration={5}>
      {vid}
      <Title position="bottom">Welcome</Title>
    </Clip>
    <Captions src={voice} style="tiktok" withAudio />
  </Render>
)

Component Summary#

ComponentTypePurposeImage()Function callGenerate still imageVideo()Function callGenerate video (text-to-video or image-to-video)Speech()Function callText-to-speech audio<Render>JSXRoot container -- sets width, height, fps<Clip>JSXTimeline segment -- duration, transitions<Music>JSXBackground audio (always set duration!)<Captions>JSXSubtitle track from Speech<Title>JSXText overlay<Overlay>JSXPositioned layer<Split> / <Grid>JSXLayout helpers

Full props: components.md

Provider Differences (Cloud vs Local)#

Cloud RenderLocal RenderNo imports neededimport { ... } from "vargai/react"``fal.imageModel("nano-banana-pro")``varg.imageModel("nano-banana-pro")``fal.videoModel("kling-v3")``varg.videoModel("kling-v3")``elevenlabs.speechModel("eleven_v3")``varg.speechModel("eleven_v3")Globals are auto-injectedMust call createVarg()

When to Use Which Provider#

ScenarioUseAuthNew project, simplest setupvarg.*Model() (gateway)VARG_API_KEY onlyExisting project with fal/elevenlabs keysfal.*Model() / elevenlabs.*Model()Individual keysCloud render via curl/APIGateway (only option)VARG_API_KEYNeed $0 billing with own keysGateway + BYOK headersVARG_API_KEY + provider keysSpecific provider feature not in gatewayDirect providerIndividual key

Default recommendation: Use the gateway ( varg.*Model() + VARG_API_KEY). It handles routing, caching, billing, and works with a single key.

Cost & Iteration#

• 1 credit = 1 cent. nano-banana-pro = 5 credits, kling-v3 = 150 credits, speech = 20-25 credits.
• Cache saves money. Keep unchanged prompts character-for-character identical across iterations.
• Preview first (local mode only): --preview generates free placeholders to validate structure.
• Full pricing: models.md

References#

Load these on demand based on what you need:

NeedReferenceWhen to loadRender via APIcloud-render.mdNo bun/ffmpeg, or user wants cloud renderingRender locallylocal-render.mdbun + ffmpeg availablePatterns & workflowsrecipes.mdTalking head, character consistency, slideshow, lipsyncModel selectionmodels.mdChoosing models, checking prices, duration constraintsComponent propscomponents.mdNeed detailed props for any componentBetter promptsprompting.mdUser wants cinematic / high-quality resultsREST APIgateway-api.mdSingle-asset generation or Render API detailsDebuggingcommon-errors.mdSomething failed or produced unexpected resultsFull examplestemplates.mdNeed complete copy-paste-ready templatesBYOK keysbyok.mdUsing your own provider API keys for $0 billing