genmedia

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

genmedia CLI: fal.ai endpoint runner

genmedia CLI：fal.ai端点运行器

genmedia

is the agent-first CLI for fal.ai. It works in a terminal for humans (pretty output) and equally well for agents (structured JSON when piped or with

--json

). All other skills in this repo call

genmedia

for execution, they do not wrap the fal.ai HTTP API directly.

For the full command surface (every flag, every option, every example), see references/full-reference.md.

genmedia

是面向Agent的fal.ai专属CLI工具。它既适用于人类在终端中使用（输出美观格式），也能完美适配Agent使用（通过管道或添加

--json

参数输出结构化JSON）。本仓库中所有其他技能均通过调用

genmedia

执行操作，而非直接封装fal.ai的HTTP API。

如需查看完整命令集（所有参数、选项及示例），请参阅references/full-reference.md。

Critical rules

核心规则

Always use
--json
when an agent will read the output. Pretty mode is for humans only.

Never invent endpoint IDs. Use

genmedia models "<query>"

to discover,

genmedia models --endpoint_id <id>

to verify.

Inspect schema before running.
```
genmedia schema <endpoint_id> --json
```
shows the exact field names. Guessed flags fail with 422.
Save files with
--download
, not curl. The CLI handles authentication, naming, and file format detection.
Use
--async
for long-running generation. Image work usually completes inline; video/audio/3D usually need queue + status polling.

当Agent需要读取输出时，务必使用
--json
参数。美观格式仅面向人类用户。
请勿自行编造端点ID。 使用
```
genmedia models "<query>"
```
发现端点，使用
```
genmedia models --endpoint_id <id>
```
验证。
运行前先查看schema。
```
genmedia schema <endpoint_id> --json
```
会显示精确的字段名称。猜测参数会导致422错误。
使用
--download
保存文件，而非curl。 CLI会处理认证、命名和文件格式检测。
针对长时间运行的生成任务使用
--async
参数。图像生成通常可同步完成；视频/音频/3D生成通常需要队列+状态轮询。

Command index

命令索引

Command	Purpose
`genmedia setup`	Configure API key, output mode, auto-update
`genmedia models <query>`	Search the catalog (or `--category` , or `--endpoint_id` )
`genmedia schema <endpoint_id>`	Inspect inputs/outputs (compact or `--format openapi` )
`genmedia run <endpoint_id> --<param> <value>`	Execute a model
`genmedia status <endpoint_id> <request_id>`	Poll an async job (with `--result` , `--logs` , `--cancel` , `--download` )
`genmedia upload <path-or-url>`	Upload a local file or remote URL to the fal.ai CDN
`genmedia pricing <endpoint_id>`	Check cost per call
`genmedia docs <query>`	Search fal.ai documentation
`genmedia init`	Install the default skill bundle into `.agents/skills/` or `.claude/skills/`
`genmedia skills <list	install
`genmedia version` / `genmedia update`	Check or apply CLI updates

命令	用途
`genmedia setup`	配置API密钥、输出模式、自动更新
`genmedia models <query>`	搜索目录（或使用 `--category` 、 `--endpoint_id` 参数）
`genmedia schema <endpoint_id>`	查看输入/输出（简洁格式或使用 `--format openapi` ）
`genmedia run <endpoint_id> --<param> <value>`	执行模型
`genmedia status <endpoint_id> <request_id>`	轮询异步任务（支持 `--result` 、 `--logs` 、 `--cancel` 、 `--download` 参数）
`genmedia upload <path-or-url>`	将本地文件或远程URL上传至fal.ai CDN
`genmedia pricing <endpoint_id>`	查看单次调用成本
`genmedia docs <query>`	搜索fal.ai文档
`genmedia init`	将默认技能包安装至 `.agents/skills/` 或 `.claude/skills/` 目录
`genmedia skills <list	install
`genmedia version` / `genmedia update`	检查或应用CLI更新

Quick patterns

快速使用模式

Run a model and download the result

运行模型并下载结果

bash

genmedia run fal-ai/flux/dev \
 --prompt "a cat on the moon" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json

bash

genmedia run fal-ai/flux/dev \
 --prompt "a cat on the moon" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json

Async + poll

异步任务+轮询

bash

SUBMIT=$(genmedia run fal-ai/veo3.1 --prompt "a dog running" --async --json)
REQ=$(echo "$SUBMIT" | jq -r '.request_id')
genmedia status fal-ai/veo3.1 "$REQ" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json

bash

SUBMIT=$(genmedia run fal-ai/veo3.1 --prompt "a dog running" --async --json)
REQ=$(echo "$SUBMIT" | jq -r '.request_id')
genmedia status fal-ai/veo3.1 "$REQ" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json

Upload then run

上传后运行模型

bash

URL=$(genmedia upload ./photo.jpg --json | jq -r '.url')
genmedia run fal-ai/nano-banana-pro/edit \
 --image_urls "$URL" \
 --prompt "make the sky stormy" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json

bash

URL=$(genmedia upload ./photo.jpg --json | jq -r '.url')
genmedia run fal-ai/nano-banana-pro/edit \
 --image_urls "$URL" \
 --prompt "make the sky stormy" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json

Discover when the user names a fuzzy task

用户模糊任务时的发现操作

bash

genmedia models "background removal product image" --json
genmedia models --category text-to-video --limit 5 --json
genmedia docs "webhook callbacks" --json

bash

genmedia models "background removal product image" --json
genmedia models --category text-to-video --limit 5 --json
genmedia docs "webhook callbacks" --json

Setup (first-time only)

首次设置

genmedia

is not installed:

bash

curl https://genmedia.sh/install -fsS | bash # Linux / macOS
irm https://genmedia.sh/install.ps1 | iex # Windows PowerShell
genmedia setup --non-interactive --api-key "$FAL_KEY"

For full setup details (output modes, auto-update,

.env

loading) see full-reference.md.

若未安装

genmedia

：

bash

curl https://genmedia.sh/install -fsS | bash # Linux / macOS
irm https://genmedia.sh/install.ps1 | iex # Windows PowerShell
genmedia setup --non-interactive --api-key "$FAL_KEY"

如需完整设置详情（输出模式、自动更新、

.env

加载），请参阅full-reference.md。