fal-assets

使用 fal 生成游戏素材

fal 通过一个 API 密钥即可调用数百种生成式模型。当模组需要尚不存在的内容时，就可以使用它：武器精灵图、Boss、从 16 个角度渲染的单位、可平铺地板、激光音效、Boss 音乐、配音台词。

设置（每个会话检查一次）

• 密钥。 在 https://fal.ai/dashboard/keys 创建密钥。um fal 会优先从环境变量读取 FAL_KEY，然后读取用户通过 um fal key set 保存的密钥（隐藏式提示：Linux 上使用桌面密钥环，通过 libsecret 的 secret-tool；没有 secret-tool 时使用仅所有者可访问的 ~/.secrets/fal-key），最后读取工作文件夹中 .env 文件里的 FAL_KEY=...。um fal key status 会显示正在使用的密钥来源，并对密钥进行遮盖。切勿将密钥写入模组文件或配置文件；um publish check 会标记泄露的密钥。

• MCP。 fal 托管的 MCP 服务地址为 https://mcp.fal.ai/mcp，请求头为 Authorization: Bearer $FAL_KEY。仓库已为各个 Agent 预先配置好：

  • 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

  它们会从 Agent 的环境中读取 FAL_KEY，如果没有该变量，服务就无法连接。如果缺少 fal MCP 工具，请暂时使用 um fal，并告知用户。用户可以在设置好 FAL_KEY 的情况下启动 Agent（在 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
  • 其他工具：使用地址为 https://mcp.fal.ai/mcp-relay 的 Streamable HTTP 服务，并启用 OAuth，不需要请求头（https://fal.ai/docs/documentation/setting-up/mcp）

  在仓库克隆目录之外使用密钥时：在 ~/.codex/config.toml 中，Codex 需要配置 [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 帧的精灵图集（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> 会添加八个朝向；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）也适合 Agent 使用。

使用哪个接口

• 发现（当前 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>。它会上传本地输入、 排入队列、轮询状态、下载所有输出文件，并将 endpoint、输入、seed 和 request id 追加到 <out>/fal_manifest.jsonl，因此每个素材都可追踪并重新生成。
• 快速查看或一次性使用，只需要 URL 即可：MCP run_model。

配方（查看选项请运行 um fal <recipe> --help；--model 可覆盖 endpoint；--set k=v 可传入额外输入）

素材	命令	默认 endpoint
精灵图 / 图标，透明背景	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 贴图（basecolor、normal、roughness、metalness、height）	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]	任意

其他实用 endpoint：

• 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：“16-bit 像素艺术游戏精灵图，采用 Terraria 风格，清晰的深色描边，有限的调色板，居中，纯白色平面背景，无阴影，无文字”。
• **明确描述视角和朝向：**手持武器使用“完全水平的侧视图，枪口朝右”，敌人使用“从侧面看，面朝左”，下落的炸弹使用“笔直朝下”。游戏引擎通常有既定约定（Terraria 物品朝右，NPC 面朝左），之后再修正朝向会影响画质。
• **背景：**使用透明背景（gpt-image-2），或使用 um sprite cutout 可通过泛洪填充去除的纯色背景。避免渐变、风景和地面阴影。如果出现柔和阴影，可在 cutout 中使用 --grey / --keep-top。
• **玩家 / 团队颜色：**要求需要采用玩家颜色的部位带有“明亮饱和的蓝色点缀”，然后用 um sprite team-mask --hue blue 将其转换为遮罩。
• **确保一组素材风格一致：**先生成一张主图，然后使用编辑端点，以主图作为 --ref 派生其余素材（“同一台机器人，现在正在开火，有枪口闪光”）。不要用一个提示词生成整张精灵图表；网格会参差不齐。
• **同一物体需要多个角度或帧：**采用 3D。取用概念图，运行 um fal model3d，然后从游戏摄像机视角运行 um render3d（asset-pipeline skill）。AoE2 robotaxi 的 16 个一致朝向 × 5 种动画就是这样制作的。
• **除非有需要，否则美术素材中不要加入文字或徽标：**模型很喜欢添加这些内容。

为游戏引擎制作音频

• 音效和音乐端点返回 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，或请音乐模型生成可循环的曲目，并对首尾进行交叉淡化。
• 音效应保持简短（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。
• **署名：**在模组的 README 中注明素材由 fal 生成，并写明模型名称。查看模型的许可页面，确认其是否允许商业用途。