animato

Animato

このスキルを使う場面

• Blender を開かずに、テキストのリクエストからリグ付きの .fbx／.gltf キャラクターをアニメーション化します。
• チャットウィンドウにプロンプトをコピー＆ペーストする代わりに、キー（ANIMATO_API_KEY／GEMINI_API_KEY／OPENAI_API_KEY）を使ってアニメーションのループを無人で実行します。
• サーバーで実行する前に、LLM が作成した bpy スクリプトを確認または審査します。
• ローカルの Animato サーバーと、その /api/* エンドポイントを操作、デバッグ、またはヘルスチェックします。

リグの作成やモーションキャプチャのリターゲティング（Blender を直接使用）、リアルタイムのゲームエフェクト（game-vfx）、または完成したクリップのブラウザー再生（threejs-animation、threejs-loaders）の場合は、適切な機能に切り替えてください。

手順

Step 1: アニメーションの情報一式を記録する

呼び出しの前に、モデルファイルとその形式、アップロード済みかどうか、1 文で記述したモーションのリクエスト、使用するプロバイダー／モデル／キー、およびソースファイルを破棄してもよいかを記録します。生成されたスクリプトはアップロード済みのモデルをその場で上書きします。ソースが代替できない場合は、アップロード前にコピーしてください。.obj にはスケルトンがないため、アニメーション化できません。

Step 2: サーバーとキーを確認する

uv run fastapi run main.py   # in the Animato checkout, serves UI + API on :8000
python3 .agent-skills/animato/scripts/animato_agent.py doctor

doctor は、サーバーへの接続、キーの有無（値は決して表示しません）、およびゲートスクリプトを確認します。ANIMATO_SERVER、ANIMATO_PROVIDER（gemini | openai）、ANIMATO_LLM_ENDPOINT、ANIMATO_MODEL を設定してください。詳しくは references/agent-loop.md を参照してください。

Step 3: 生のエンドポイントではなく、ゲート付きのループを実行する

export ANIMATO_API_KEY=...   # free-tier key is enough; one inference per animation
python3 .agent-skills/animato/scripts/animato_agent.py animate \
  --file "./X Bot.fbx" --message "wave hello with the right arm, 2 seconds"

--mode local（デフォルト）では、アップロード → /api/prompt → LLM 呼び出し 1 回 → 静的ゲート → /api/run の順に実行し、プロンプトと生成されたスクリプトを --out-dir（デフォルトは animato-out/）に書き込みます。これにより、失敗した場合も確認可能な成果物が残ります。--dry-run を使うと、実行前に停止します。/api/chat ではゲートが実行される前にスクリプトが実行されることを許容できる場合に限り、--mode server を使用してください。

Step 4: 再度プロンプトを作成する前に、ゲートの出力を読む

スクリプトが却下された場合は、リクエストまたはモデルの選択が誤っていたということであり、ループを再試行すべきという意味ではありません。

python3 .agent-skills/animato/scripts/validate_bpy_script.py animato-out/X-Bot.generated.py \
  --model-path public/upload/X-Bot.fbx

ゲートは、古い Blender API、キーフレームの欠落、フレーム範囲の欠落、エクスポートの欠落、export_animations=True／bake_anim=True の指定漏れ、形式の不一致、および subprocess／os.system／eval などのホスト側呼び出しを拒否します。表の全体は references/bpy-script-contract.md を参照してください。

Step 5: HTTP ステータスだけでなく、アニメーション済みファイルを検証する

/api/run はスクリプトが失敗しても HTTP 200 を返します。ok に基づいて分岐し、output_url が読み込めること、および実際にクリップを含んでいること（gltf.animations／FBX の .animations が空でないこと、mixer.update(delta) が毎フレーム呼び出されていること）を確認してください。誤ったクリップは新しいリクエストで修正し、問題のあるクリップは確実に削除してください。

python3 .agent-skills/animato/scripts/animato_agent.py remove --filename X-Bot.fbx --name wave

Step 6: ループの結果を正しく評価する

/api/run と /api/chat は、ローカルのリモートコード実行の入口として扱ってください。信頼できるマシンのみで使用し、サンドボックスなしで公開しないでください。自動実行で 1 回のアニメーションにつき 1 回を超えて推論を行わないでください。また、ゲートを通過しただけでアニメーションが動作すると断言しないでください。ゲートは静的なチェックです。

例

オフラインでループ全体を検証する（キー不要、Blender 不要）

python3 .agent-skills/animato/scripts/selftest.py

スタブの Animato サーバーとスタブ LLM を実行し、正常系、実行をブロックするゲートによる却下、--dry-run、/api/chat モード、キー不足時の失敗、および doctor の 6 つのケースをテストします。

OpenAI 互換プロバイダーを使い、アップロード済みのモデルをアニメーション化する

ANIMATO_PROVIDER=openai ANIMATO_LLM_ENDPOINT=https://api.example.com/v1 ANIMATO_MODEL=my-model \
python3 .agent-skills/animato/scripts/animato_agent.py animate \
  --filename X-Bot.fbx --message "idle breathing loop, 3 seconds" --dry-run

サーバーが作成するプロンプトを確認する

python3 .agent-skills/animato/scripts/animato_agent.py prompt \
  --filename X-Bot.fbx --message "wave hello" --out prompt.txt

ベストプラクティス

1. アップロード前にソースモデルをコピーしてください。アニメーションのエクスポートで元のファイルがその場で置き換えられます。
2. --mode local を優先してください。実行後ではなく、実行前にスクリプトをゲートで確認できます。
3. アニメーション 1 件につき推論は 1 回にし、モデルをループさせず、リクエストまたはプロンプトを修正してください。
4. 骨の名前、軸、単位は、例のスクリプトではなく /api/prompt のダンプから取得してください。
5. 問題のある結果を診断できるよう、保存したプロンプトと生成されたスクリプトを一緒に保管してください。
6. サーバーはローカルの信頼できる環境に置き、キーは環境変数に保持して、ログや成果物には含めないでください。
7. 成功を報告する前に、エクスポートしたファイルが再生できることを確認してください。

参考資料

• references/agent-loop.md — エンドポイント、モード、環境変数、失敗時のルーティング。
• references/bpy-script-contract.md — ゲートルールと削除された API の一覧。
• references/example-bpy-script.py — ゲートを通過するスクリプトの形式。
• references/upstream.md — 出典、要件、安全上の境界。
• otdnnc/Animato