varg-ai

版本检查（每个会话运行一次）

此技能的版本为 2.0.4。每个会话首次使用前，请检查是否有更新：

curl -sf https://raw.githubusercontent.com/vargHQ/skills/main/varg-ai/SKILL.md | grep 'version:' | head -1

如果远程版本高于 2.0.4，请更新并重新阅读此文件：

npx -y skills update

设置（首次使用前必须完成）

生成任何内容前，请检查身份验证并确定渲染模式。 请勿运行交互式 CLI 工具（例如 bunx vargai init）——它们需要标准输入，而 Agent 无法提供。请改用下面基于 curl 的流程。

1. 检查 API 密钥

echo "${VARG_API_KEY:-}" && cat ~/.varg/credentials 2>/dev/null

如果已设置 VARG_API_KEY（通过环境变量或凭据文件），请跳到步骤 2。

如果两者都不存在，请对用户进行身份验证。先尝试选项 A，失败后再尝试选项 B。

选项 A：用户已有 API 密钥

询问用户是否有 VARG_API_KEY。如果有，告诉他们在终端中导出：

export VARG_API_KEY=<their_key>

**重要：**请勿要求用户将原始密钥粘贴给你。请他们自行运行 export 命令。然后跳到下面的“保存凭据”。

选项 B：通过电子邮件注册 / 登录（OTP）

1. 询问用户的电子邮件地址。
2. 向其电子邮箱发送一次性验证码：

curl -s -X POST https://app.varg.ai/api/auth/cli/send-otp \
  -H "Content-Type: application/json" \
  -d '{"email":"USER_EMAIL"}'

3. 告诉用户：“请查收收件箱，获取来自 varg.ai 的 6 位验证码”
4. 询问用户验证码，然后一步完成验证并捕获响应：

VARG_AUTH=$(curl -s -X POST https://app.varg.ai/api/auth/cli/verify-otp \
  -H "Content-Type: application/json" \
  -d '{"email":"USER_EMAIL","code":"THE_6_DIGIT_CODE"}')
export VARG_API_KEY=$(echo "$VARG_AUTH" | grep -o '"api_key":"[^"]*"' | cut -d'"' -f4)
echo "Authenticated. Balance: $(echo "$VARG_AUTH" | grep -o '"balance_cents":[0-9]*' | cut -d: -f2) credits"

响应包含 {"api_key":"varg_xxx","email":"...","balance_cents":0,"access_token":"..."}。 密钥现已存入 $VARG_API_KEY——切勿直接引用原始值。

保存凭据

设置好 VARG_API_KEY（通过任一选项）后，请将其全局保存并验证。始终引用 $VARG_API_KEY——切勿引用原始值：

mkdir -p ~/.varg && echo "{\"api_key\":\"$VARG_API_KEY\",\"email\":\"USER_EMAIL\",\"created_at\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > ~/.varg/credentials && chmod 600 ~/.varg/credentials

验证密钥是否有效：

curl -s -H "Authorization: Bearer $VARG_API_KEY" https://api.varg.ai/v2/billing/balance

你应会收到 {"available": ..., "total_balance": ..., ...}（数值以积分 / 美分为单位）。如果收到 401，说明密钥无效——请用户仔细检查。

如果项目中存在 .env 文件，也请将密钥添加进去：

echo "VARG_API_KEY=$VARG_API_KEY" >> .env

检查余额并充值

检查 verify-otp 响应中的 balance_cents，或上面余额查询中的 available。如果余额为 0（或不足以完成用户的任务），用户需要先充值才能生成内容。1 积分 = 1 美分。普通视频的费用约为 $2-5（200-500 积分）。

可用套餐：

套餐 ID	积分	价格
credits-2000	2,000	$20
credits-5000	5,000	$50
credits-10000	10,000（推荐）	$100
credits-20000	20,000	$200
credits-50000	50,000	$500
credits-100000	100,000	$1,000

询问用户想购买哪个套餐，然后：

• 如果你有 access_token（来自选项 B 的电子邮件 OTP），请捕获该令牌并创建 Stripe 结账会话：

VARG_ACCESS_TOKEN=$(echo "$VARG_AUTH" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)
curl -s -X POST https://app.varg.ai/api/billing/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VARG_ACCESS_TOKEN" \
  -H "Origin: https://app.varg.ai" \
  -d '{"packageId":"PACKAGE_ID"}'

响应：{"url":"https://checkout.stripe.com/..."}

告诉用户在浏览器中打开该 URL 完成付款。付款后会立即添加积分。

• 如果你只有 API 密钥（来自选项 A），请引导用户前往 https://app.varg.ai/dashboard 手动购买积分。

2. 确定渲染模式

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

关键规则

你所了解的 varg 很可能已经过时。编写代码前，请务必先对照此技能及其参考资料进行核实。

1. 切勿猜测模型 ID——请查阅 models.md，了解当前模型、定价和限制。
2. 媒体使用函数调用，组合使用 JSX——Image({...}) 用于创建媒体，<Clip> 用于组合时间线。切勿编写 <Image prompt="..." />。
3. 缓存至关重要——相同的提示词和参数 = 立即命中缓存，费用为 $0。迭代时，保持不变的提示词完全一致。切勿清除缓存。
4. 每个 Video 只能有一张图像——Video({ prompt: { images: [img] } }) 只能接收一张图像。多张图像会导致错误。
5. 不同模型的时长限制不同——kling_v3：3-15 秒（仅限整数）。kling_v2_5：仅限 5 或 10 秒。请查阅 models.md。
6. 网关命名空间——通过网关（两种模式均适用）时，请使用 providerOptions: { varg: {...} }，不要使用 fal。
7. 渲染需要付费——1 个积分 = 1 美分。一个典型的 3 个片段视频需要 $2-5。迭代时，请使用预览模式（本地）或低成本模型。
8. API 密钥安全——切勿将原始 API 密钥值写入 bash 命令。获取密钥后（从用户处或 OTP 响应中），立即执行 export VARG_API_KEY=...，并在之后的所有命令中使用 $VARG_API_KEY。这样可以防止密钥泄露到对话上下文和终端历史记录中。

快速开始

云端渲染（无需 bun/ffmpeg）

# Submit TSX code to the render service — returns a job: {"id": "job_xxx", "status": "queued", ...}
curl -s -X POST https://api.varg.ai/v2/render \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "const img = Image({ model: varg.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"; video at output.outputs[0].url)
curl -s https://api.varg.ai/v2/jobs/JOB_ID \
  -H "Authorization: Bearer $VARG_API_KEY"

详情请见：cloud-render.md

本地渲染（bun + ffmpeg）

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

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

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

详情请见：local-render.md

单个素材（无需视频合成）

如果只需生成单张图像、视频、语音或音乐，而不构建多片段模板：

curl -X POST https://api.varg.ai/v2/image \
  -H "Authorization: Bearer $VARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano_banana_pro", "prompt": "a sunset over mountains"}'

完整 API 参考：gateway-api.md

如何编写视频代码

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

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

组件概要

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

完整属性列表：components.md

提供方差异（云端与本地）

两种模式的所有模型都使用 varg.*。唯一的区别是导入方式：

云端渲染	本地渲染
无需导入（全局变量会自动注入）	import { ... } from "vargai/react" + import { createVarg } from "vargai/ai"
varg.imageModel("nano_banana_pro")	varg.imageModel("nano_banana_pro")
varg.videoModel("kling_v3")	varg.videoModel("kling_v3")
varg.speechModel("eleven_v3")	varg.speechModel("eleven_v3")

始终使用 varg.*Model() 和 VARG_API_KEY。它负责处理路由、缓存和计费，只需一个密钥即可使用。v2 不支持通过 API 使用 BYOK——请参阅 byok.md，了解可行的方案（仅限 local-render 中的直接提供方模块）。

成本与迭代

• 1 个积分 = 1 美分。 grok_imagine_image = 4 个积分，nano_banana_pro = 126 个积分，kling_v3（5 秒）= 221 个积分，sora_2（5 秒）= 105 个积分，语音 = 约 105 个积分。实时目录：GET https://api.varg.ai/v2/pricing（无需身份验证）。估算任意请求：POST /v2/estimate。
• 缓存可以节省费用。 迭代期间，保持不变的提示词逐字完全一致。
• 先进行预览（仅限本地模式）：--preview 会生成免费的占位内容，用于验证结构。
• 完整定价：models.md

参考资料

根据需要按需加载：

需求	参考资料	加载时机
通过 API 渲染	cloud-render.md	没有 bun/ffmpeg，或用户想要云端渲染
本地渲染	local-render.md	已安装 bun + ffmpeg
模式与工作流	recipes.md	口播视频、角色一致性、幻灯片、口型同步
模型选择	models.md	选择模型、查询价格、了解时长限制
组件属性	components.md	需要了解任何组件的详细属性
优化提示词	prompting.md	用户想要电影感或高质量效果
REST API	gateway-api.md	生成单个素材或了解 Render API 详情
调试	common-errors.md	操作失败或产生意外结果
完整示例	templates.md	需要可直接复制粘贴的完整模板
BYOK 密钥	byok.md	使用自己的服务提供商 API 密钥，实现 $0 计费