varg-ai

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Environment Detection

环境检测

Before generating anything, determine the rendering mode.

Run

bash scripts/setup.sh

from the skill directory to auto-detect, or check manually:

bun	ffmpeg	Mode
No	No	Cloud Render -- read cloud-render.md
Yes	No	Cloud Render -- read cloud-render.md
Yes	Yes	Local Render (recommended) -- read local-render.md

VARG_API_KEY

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

在生成任何内容之前，请先确定渲染模式。

从技能目录运行

bash scripts/setup.sh

进行自动检测，或手动检查：

bun	ffmpeg	渲染模式
否	否	云端渲染 -- 查看cloud-render.md
是	否	云端渲染 -- 查看cloud-render.md
是	是	本地渲染（推荐）-- 查看local-render.md

所有模式都需要

VARG_API_KEY

。可前往https://varg.ai获取。

Critical Rules

核心规则

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

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

你所了解的varg相关信息很可能已过时。在编写代码前，请务必对照本技能及其参考文档进行验证。

切勿猜测模型ID -- 请查阅models.md获取当前可用模型、定价及限制条件。
媒体生成用函数调用，合成用JSX --
```
Image({...})
```
用于生成媒体，
```
<Clip>
```
用于时间轴合成。切勿编写
```
<Image prompt="..." />
```
。
缓存至关重要 -- 相同的提示词+参数=即时免费命中缓存。迭代时，请完全保留未修改的提示词。切勿清除缓存。
每个视频仅含一张图片 --
```
Video({ prompt: { images: [img] } })
```
仅接受一张图片。多张图片会导致错误。
不同模型的时长限制不同 -- kling-v3：3-15秒（仅支持整数）。kling-v2.5：仅支持5秒或10秒。请查阅models.md。
网关命名空间 -- 当通过网关调用时（两种模式均适用），请使用
```
providerOptions: { varg: {...} }
```
，切勿使用
```
fal
```
。
渲染会产生费用 -- 1积分=1美分。一个典型的3片段视频花费约2-5美元。迭代时请使用预览模式（本地）或低成本模型。

Quick Start

快速开始

Cloud Render (no bun/ffmpeg needed)

云端渲染（无需bun/ffmpeg）

bash

undefined

bash

undefined

Submit TSX code to the render service

提交TSX代码至渲染服务

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")

轮询获取结果（重复调用直到状态为"completed"或"failed"）

curl -s https://render.varg.ai/api/render/jobs/JOB_ID
-H "Authorization: Bearer $VARG_API_KEY"


Full details: [cloud-render.md](references/cloud-render.md)

curl -s https://render.varg.ai/api/render/jobs/JOB_ID
-H "Authorization: Bearer $VARG_API_KEY"


详细说明：[cloud-render.md](references/cloud-render.md)

Local Render (bun + ffmpeg)

本地渲染（需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

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   # 免费预览
bunx vargai render video.tsx --verbose   # 完整渲染（消耗积分）

详细说明：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

如需一次性生成图片、视频、语音或音乐，无需构建多片段模板：

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"}'

完整API参考：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" />
  </Render>
)

视频代码分为两层：媒体生成（函数调用）和合成（JSX）。

tsx

// 1. 通过函数调用生成媒体
const img = Image({ model: ..., prompt: "..." })
const vid = Video({ model: ..., prompt: { text: "...", images: [img] }, duration: 5 })
const voice = Speech({ model: ..., voice: "rachel", children: "Hello!" })

// 2. 通过JSX树进行合成
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" />
  </Render>
)

Component Summary

组件汇总

Component	Type	Purpose
`Image()`	Function call	Generate still image
`Video()`	Function call	Generate video (text-to-video or image-to-video)
`Speech()`	Function call	Text-to-speech audio
`<Render>`	JSX	Root container -- sets width, height, fps
`<Clip>`	JSX	Timeline segment -- duration, transitions
`<Music>`	JSX	Background audio (always set `duration` !)
`<Captions>`	JSX	Subtitle track from Speech
`<Title>`	JSX	Text overlay
`<Overlay>`	JSX	Positioned layer
`<Split>` / `<Grid>`	JSX	Layout helpers

Full props: components.md

组件	类型	用途
`Image()`	函数调用	生成静态图像
`Video()`	函数调用	生成视频（文本转视频或图像转视频）
`Speech()`	函数调用	文本转语音音频
`<Render>`	JSX	根容器 -- 设置宽度、高度、帧率
`<Clip>`	JSX	时间轴片段 -- 时长、转场效果
`<Music>`	JSX	背景音频（务必设置 `duration` ！）
`<Captions>`	JSX	基于Speech生成的字幕轨道
`<Title>`	JSX	文本叠加层
`<Overlay>`	JSX	定位图层
`<Split>` / `<Grid>`	JSX	布局辅助组件

完整属性说明：components.md

Provider Differences (Cloud vs Local)

渲染模式差异（云端 vs 本地）

Cloud Render	Local Render
No imports needed	`import { ... } 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-injected	Must call `createVarg()`

云端渲染	本地渲染
无需导入	`import { ... } 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")`
全局变量自动注入	必须调用 `createVarg()`

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

1积分=1美分。nano-banana-pro=5积分，kling-v3=150积分，语音生成=20-25积分。
缓存节省成本。迭代时，请完全保留未修改的提示词。
先预览（仅本地模式支持）：
```
--preview
```
生成免费占位符以验证结构。

References

参考文档

Load these on demand based on what you need:

Need	Reference	When to load
Render via API	cloud-render.md	No bun/ffmpeg, or user wants cloud rendering
Render locally	local-render.md	bun + ffmpeg available
Patterns & workflows	recipes.md	Talking head, character consistency, slideshow, lipsync
Model selection	models.md	Choosing models, checking prices, duration constraints
Component props	components.md	Need detailed props for any component
Better prompts	prompting.md	User wants cinematic / high-quality results
REST API	gateway-api.md	Single-asset generation or Render API details
Debugging	common-errors.md	Something failed or produced unexpected results
Full examples	templates.md	Need complete copy-paste-ready templates

根据需求按需加载以下文档：

需求	参考文档	加载时机
通过API渲染	cloud-render.md	无bun/ffmpeg，或用户需要云端渲染
本地渲染	local-render.md	已安装bun + ffmpeg
模式与工作流	recipes.md	制作虚拟主播、角色一致性、幻灯片、唇形同步
模型选择	models.md	选择模型、查看定价、时长限制
组件属性	components.md	需要任何组件的详细属性说明
提示词优化	prompting.md	用户需要电影级/高质量结果
REST API	gateway-api.md	单一资产生成或渲染API细节
调试	common-errors.md	出现失败或意外结果
完整示例	templates.md	需要可直接复制使用的完整模板