fal-assets

fal でゲームアセットを作成する

fal では、1 つの API キーで数百種類の生成モデルを利用できます。MOD にまだ存在しないものが必要なときは、いつでも使えます。武器のスプライト、ボス、16 方向から描画されたユニット、タイル状に敷き詰められる床、レーザーの効果音、ボス戦の音楽、音声付きのセリフなどを作成できます。

セットアップ（セッションごとに 1 回確認）

• キー。 https://fal.ai/dashboard/keys で作成します。um fal は、まず環境変数の FAL_KEY を使い、次にユーザーが um fal key set で保存したキーを使います（非表示のプロンプトを使用します。Linux ではデスクトップのキーリングを使い、secret-tool がない場合は所有者のみが読み取れる ~/.secrets/fal-key に保存します）。その次に、作業フォルダー内の .env にある FAL_KEY=... を使います。um fal key status では、キーをマスクした状態で使用中の保存先を確認できます。キーを MOD ファイルや設定ファイルに書き込まないでください。um publish check は、キーの漏えいを検出します。

• MCP。 fal のホスト型 MCP サーバーは https://mcp.fal.ai/mcp で、ヘッダーは Authorization: Bearer $FAL_KEY です。リポジトリでは、各エージェント向けに事前設定されています。

  • Claude Code：.mcp.json
  • Codex：.codex/config.toml
  • Cursor：.cursor/mcp.json
  • VS Code/Copilot：.vscode/mcp.json
  • Gemini CLI：gemini-extension.json
  • OpenCode：opencode.json

  これらはエージェントの環境から FAL_KEY を読み取ります。キーがないと、サーバーに接続できません。fal MCP ツールが見つからない場合は、ひとまず um fal を使い、その旨をユーザーに伝えてください。ユーザーは FAL_KEY を設定してエージェントを起動するか（Linux ではキーリングから次のように設定します。 export FAL_KEY="$(secret-tool lookup service fal.ai key api)"）、キーの代わりにブラウザーでサインインする fal の OAuth エンドポイントを追加できます。

  • Claude Code：claude mcp add --transport http fal-oauth https://mcp.fal.ai/mcp-relay を実行し、/mcp で認証します。
  • Codex：codex mcp add fal-oauth --url https://mcp.fal.ai/mcp-relay を実行し、次に codex mcp login fal-oauth を実行します。
  • その他：OAuth を使用し、ヘッダーを必要としない、https://mcp.fal.ai/mcp-relay の Streamable HTTP サーバー（https://fal.ai/docs/documentation/setting-up/mcp）

  クローンの外でキーを使う場合、Codex では ~/.codex/config.toml に [mcp_servers.fal]、url = "https://mcp.fal.ai/mcp"、bearer_token_env_var = "FAL_KEY" を設定します。 MCP ツール：search_models、recommend_model、get_model_schema、get_pricing、run_model、submit_job／check_job／get_job_result、upload_file、search_docs。

• fal のキーがない場合は？ 画像生成には、代わりに um comfy でローカルの ComfyUI サーバーを使います（まず um comfy status を実行し、次に um comfy image "..." --sprite を実行します）。音声、3D、動画のレシピはありません。

• Sprixen は、2D アート専用の別のホスト型サービスです。別料金のサービス（アカウント、API キー、クレジットが必要）なので、利用する前にユーザーに確認してください。um sprixen では、プロジェクトごとにアートスタイル、解像度、ビューを統一できます（um sprixen sprite "..." --style pixel_art --size 32x32）。スプライト ID から 2～12 フレームの 1 行スプライトシートを作成し（um sprixen animate <sprite_id> --type walk）、地形タイルも生成できます。キーは SPRIXEN_API_KEY または um sprixen key set で設定し、um sprixen credits で残高を確認できます。音声、3D、動画には対応していません。

• Voidless は、2D アート用の別料金のサービスです（API を利用できるプランのアカウント、API キー、クレジットが必要）。利用する前にユーザーに確認してください。um voidless sprite "..." はアセット ID を表示します。um voidless rotate <asset_id> で 8 方向の向きを追加し、um voidless animate <asset_id> --preset <key> でアセットのサイズに合わせた一連のクリップを追加できます（キーの一覧は um voidless presets で確認できます）。um voidless fetch <asset_id> は、生成せずにフレームを再ダウンロードします。キーは VOIDLESS_API_KEY または um voidless key set で設定し、um voidless credits で残高を確認できます。3D モデルから 8 方向または 16 方向の画像を作成する場合は、um render3d を参照してください。

• CLI の代替手段： pip install fal で fal api <endpoint> key=value key:=json を使えます。genmedia CLI（genmedia run ... --json --download）もエージェントで使いやすい方法です。

インターフェースの選び方

• モデルの検索（今、X に最適なモデルは何か、その入力や価格はどうか）：fal MCP の recommend_model / search_models / get_model_schema / get_pricing、または um fal search、 um fal schema <endpoint>、um fal price <endpoint> を使います。カタログは毎週更新されます。以下のデフォルトは 2026 年 9 月時点のものです。大規模なバッチ処理の前にご確認ください。
• ディスクに保存する必要があるもの（すべてのゲームアセット）：um fal <recipe> を使います。ローカルの入力を アップロードし、キューに登録して、ポーリングし、すべての出力ファイルをダウンロードします。また、エンドポイント、入力、シード、リクエスト ID を <out>/fal_manifest.jsonl に追記するため、すべてのアセットの追跡と再生成が可能です。
• 手軽な確認や単発の利用で URL だけで十分な場合：MCP の run_model を使います。

レシピ（オプションは um fal <recipe> --help で確認できます。--model でエンドポイントを上書きし、--set k=v で追加の入力を渡します）

アセット	コマンド	デフォルトのエンドポイント
スプライト／アイコン、透明な背景	um fal sprite "<subject, view, style>" --name x	openai/gpt-image-2（background=transparent）
コンセプトアート、キービジュアル、背景	um fal image "<prompt>" --aspect 16:9	fal-ai/nano-banana-2
一貫性のあるバリエーション、追加フレーム、色の変更、同じキャラクターの新しいポーズ	um fal edit "<change>" --ref base.png	fal-ai/nano-banana-2/edit
背景の削除	um fal rmbg in.png	fal-ai/birefnet/v2
あらゆる画像をきれいなピクセルアートに変換	um fal pixelate in.png --colors 24	fal-ai/image2pixel
アップスケール	um fal upscale in.png --factor 2	fal-ai/seedvr/upscale/image
シームレスに繰り返せるテクスチャ	um fal texture "mossy cobblestone"	fal-ai/z-image/turbo/tiling
PBR マップ（ベースカラー、ノーマル、ラフネス、メタリック、ハイト）	um fal pbr "rusted sheet metal"	fal-ai/patina/material
画像 → テクスチャ付き 3D モデル（GLB）	um fal model3d concept.png [--engine trellis2|hunyuan|tripo|meshy]	fal-ai/trellis-2
人型キャラクターの自動リギング、アニメーションは任意	um fal rig character.glb --animate	fal-ai/meshy/rigging
効果音	um fal sfx "plasma rifle shot, punchy" --seconds 1.2	fal-ai/elevenlabs/sound-effects/v2
音楽	um fal music "tense boss battle, chiptune, 150 bpm" --seconds 90	elevenlabs/music/v2.5
ボイスライン	um fal voice "You dare challenge me?" --voice-id Adam	fal-ai/elevenlabs/tts/eleven-v3
トレーラー／カットシーンのクリップ	um fal video still.png "camera orbits the boss"	bytedance/seedance-2.5/image-to-video
その他	um fal run <endpoint> key=value key:=json [email protected]	任意

その他の便利なエンドポイント：

• 3D：tripo3d/tripo/remesh と fal-ai/meshy/v5/remesh（ローポリ、ゲーム向け）、fal-ai/trellis-2/retexture。
• モーション：fal-ai/hunyuan-motion（テキスト → モーション）。
• アイコン：fal-ai/recraft/v4.1/text-to-vector（SVG アイコン）。
• 動画の切り抜き：pixelcut/video-background-removal。
• 音楽：google/lyria-3.5。
• 音声：fal-ai/minimax/speech-2.8-hd。

ゲームに合ったゲームアートを生成する

• まずゲーム独自のアセットを確認します： ピクセルサイズ、輪郭線、パレット、遠近法、向き、情報量などです。それらを再利用できるスタイル用のサフィックスにまとめます。Terraria の場合は、*「Terraria 風の 16 ビットピクセルアートのゲームスプライト、くっきりした濃い輪郭線、限られたパレット、中央配置、無地の白い背景、影なし、テキストなし」*のようにします。
• 視点と向きを明確に指定します： 手持ち武器なら「完全な水平の側面図で、銃口は右向き」、敵なら「左を向いた側面図」、落下する爆弾なら「真下を向いている」のように指定します。ゲームエンジンには慣例があります（Terraria のアイテムは右向き、NPC は左向きです）。後から向きを修正すると、品質が低下します。
• 背景： 透明（gpt-image-2）にするか、um sprite cutoutで塗りつぶせる単色にします。グラデーション、風景、地面の影は避けてください。ぼかした影が入ってしまった場合は、cutout で--grey／--keep-topを使います。
• プレイヤー／チームカラー： プレイヤーカラーを適用する部分に「鮮やかで彩度の高い青のアクセント」を指定し、um sprite team-mask --hue blueでマスクに変換します。
• 一連のアセットの一貫性： まずメイン画像を 1 枚生成し、それを--refとして編集エンドポイントに渡して、残りを作成します（「同じロボットで、今度は発砲中、マズルフラッシュあり」など）。1 つのプロンプトでスプライトシート全体を生成しようとしないでください。グリッドにばらつきが出ます。
• 同じオブジェクトの複数の角度やフレーム： 3D を使います。コンセプトをもとにum fal model3dを実行し、ゲームのカメラからum render3dでレンダリングします（asset-pipeline スキル）。これが、AoE2 のロボタクシーで 16 方向 × 5 種類のアニメーションを一貫して作成した方法です。
• アートには、必要な場合を除き、テキストやロゴを入れないでください： モデルはよく追加してしまいます。

ゲームエンジン向けのオーディオ

• SFX と音楽のエンドポイントは MP3 を返します。ゲームエンジンに合った形式に変換します：
  • ffmpeg -i x.mp3 -ar 44100 x.wav（XNA/tModLoader、ほとんどのゲームエンジン）；
  • ffmpeg -i x.mp3 -c:a libvorbis -q:a 5 x.ogg（Minecraft、Godot、Unity）；
  • 先に無音部分をトリミングします：-af silenceremove=start_periods=1:start_threshold=-50dB。
• ループ：um fal sfx ... --loopを使うか、音楽モデルにループ可能なトラックを依頼し、両端をクロスフェードします。
• SFX は短く（0.2-2 s）し、音量を正規化します（-af loudnorm=I=-16）。ゲーム本来のサウンドになじませるためです。

コストとマナー

• 高価なものは料金を確認します： 3D、動画、または長い音楽をまとめて生成する前に、料金を確認します（um fal price <endpoint>／MCP get_pricing）。生成が約 20 回を超える場合や、動画ほどの規模になる場合は、事前に概算コストをユーザーに伝えてください。
• 低コストで反復します： 試行中は低品質または低解像度（--quality low、--res 0.5K）を使い、採用するものを同じプロンプト（対応している場合は同じシード）でフル品質にして再生成します。
• 再現性： アセットとともにfal_manifest.jsonlを保管します。プロンプト、シード、リクエスト ID が記録されます。
• クレジット表記： MOD の README で、アセットが fal で生成されたことを明記し、モデル名を記載します。商用利用については、モデルのライセンスページを確認してください。