varg-ai

バージョン確認（セッションごとに1回実行）

このスキルのバージョンは 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 など）は実行しないでください。エージェントが入力できない標準入力を必要とします。代わりに、以下の 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>

重要： API キーの生の値を貼り付けるようユーザーに求めないでください。ユーザー自身で 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. ユーザーにコードを尋ね、検証とレスポンスの取得を1つの手順で行ってください。

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

残高を確認してクレジットを追加する

検証レスポンスから 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 ごとに画像は 1 枚 — Video({ prompt: { images: [img] } }) が受け取る画像はちょうど 1 枚です。複数の画像を指定するとエラーになります。
5. 再生時間の制約はモデルによって異なります — kling_v3：3～15 秒（整数のみ）。kling_v2_5：5 秒または 10 秒のみ。models.md を確認してください。
6. ゲートウェイの名前空間 — ゲートウェイ経由の場合（どちらのモードでも）は、fal ではなく providerOptions: { varg: {...} } を使用してください。
7. レンダリングには料金がかかります — 1 クレジット = 1 セントです。一般的な 3 クリップの動画では $2～5 かかります。反復作業にはプレビューモード（ローカル）または安価なモデルを使用してください。
8. API キーの取り扱い — bash コマンドに API キーの生の値を絶対に書かないでください。キーを取得したら（ユーザーから、または 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）の 2 層で成り立っています。

// 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	BGM（必ず 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_API_KEY とともに、必ず varg.*Model() を使用してください。ルーティング、キャッシュ、課金を処理し、1 つのキーで利用できます。v2 では API 経由の BYOK は利用できません。利用可能な方法については byok.md を参照してください（ローカルレンダリングでのプロバイダーモジュール直接利用のみ）。

コストと反復作業

• 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	請求を $0 にするため、独自のプロバイダー API キーを使う場合