genmedia

genmedia CLI：fal.ai エンドポイント実行ツール

genmedia は fal.ai 向けのエージェントファーストな CLI です。人間がターミナルで使う場合は見やすく出力し、エージェント向けにはパイプで渡す場合や --json を指定した場合に構造化 JSON を出力します。このリポジトリのほかのすべてのスキルは、実行に genmedia を使用し、fal.ai HTTP API を直接ラップすることはありません。

すべてのコマンド、フラグ、オプション、例については、references/full-reference.md を参照してください。

重要なルール

1. エージェントが出力を読み取る場合は、必ず --json を指定してください。 見やすい形式の出力は人間向けです。
2. デフォルト品質のリクエストでは、スマートルーティングを優先してください。 genmedia run "<prompt>"（エンドポイント指定なし、--prompt も不要）はプロンプトを分類し、モダリティごとに適切なデフォルトへルーティングします。ユーザーがモデルを指定した場合、デフォルト以外の動作（特定のスタイル、品質ティア、パラメーター）を求めた場合、またはタスクに対してスマートルーティングのデフォルトが適切でない場合に限り、明示的にエンドポイントを検索してください。
3. エンドポイント ID を決して推測しないでください。 特定のエンドポイントが必要な場合は、genmedia models "<query>" を使用して検索し（推定されたモダリティで自動フィルタリング）、genmedia models --endpoint_id <id> で確認してください。
4. カスタムパラメーターを指定して実行する前に、スキーマを確認してください。 genmedia schema <endpoint_id> --json で正確なフィールド名を確認できます。スマートルーティングに必要なのは prompt のみです。明示的にエンドポイントを指定してカスタムパラメーターを使う場合は、事前にスキーマを確認してください。フラグを推測すると 422 エラーになります。
5. ファイルの保存には curl ではなく --download を使用してください。 CLI が認証、ファイル名、ファイル形式の判定を処理します。
6. 生成に時間がかかる場合は --async を使用してください。 画像は通常その場で完了しますが、動画、音声、3D では通常、キューへの登録とステータスのポーリングが必要です。

コマンド一覧

コマンド	用途
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 の更新を確認または適用します

クイックパターン

スマートルーティング（デフォルト品質のリクエストに推奨）

CLI はプロンプトをモダリティ（image / video / music / tts / 3d）で分類し、適切なデフォルトのエンドポイントを選択します。出力には routed ブロックが含まれるため、実際に実行されたエンドポイントを確認できます。

genmedia run "a cat on the moon" --json
genmedia run "a 5-second clip of a robot dancing" --json
genmedia run "narrate this paragraph in a calm voice" --json

エンドポイント ID を明示的に指定すれば、いつでも上書きできます（/ を含む位置引数）。

genmedia run fal-ai/flux/pro --prompt "a cat on the moon" --json

ユーザーが曖昧なタスクを指定した場合や、特定のエンドポイントを求めた場合に検索する

genmedia models "<query>" は、スマートルーターと同じ分類器を使って --category を自動的に適用するため、結果が適切なモダリティに絞られます。無効にするには --no-classify を、上書きするには --category <cat> を指定してください。

genmedia models "background removal product image" --json
genmedia models --category text-to-video --limit 5 --json
genmedia models "video models with character consistency" --no-classify --json
genmedia docs "webhook callbacks" --json

特定のモデルを実行して結果をダウンロードする

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

非同期実行とポーリング

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

スマートルーティングは非同期実行にも対応しています。応答には routed と endpoint_id が含まれるため、status でどのエンドポイントをポーリングすべきか確認できます。

SUBMIT=$(genmedia run "a 30-second video of waves" --async --json)
REQ=$(echo "$SUBMIT" | jq -r '.request_id')
EP=$(echo "$SUBMIT" | jq -r '.endpoint_id')
genmedia status "$EP" "$REQ" --download "./out/" --json

アップロードしてから実行する

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

セットアップ（初回のみ）

genmedia がインストールされていない場合：

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 を参照してください。