fal-generate

fal.ai Generate

fal.ai 上の最先端 AI モデルを使用して、画像や動画を生成します。

スクリプト

スクリプト	用途
generate.sh	画像／動画を生成します（キューベース）
upload.sh	ローカルファイルを fal CDN にアップロードします
search-models.sh	モデルを検索して見つけます
get-schema.sh	任意のモデルの OpenAPI スキーマを取得します

キューシステム（デフォルト）

信頼性を高めるため、デフォルトですべてのリクエストにキューシステムを使用します。

User Request → Queue Submit → Poll Status → Get Result
                   ↓
              request_id

利点：

• 実行時間の長いタスク（動画）がタイムアウトしません
• いつでもステータスを確認できます
• キュー内のリクエストをキャンセルできます
• 接続が切れても結果を取得できます

コンテンツの生成

bash /mnt/skills/user/fal-generate/scripts/generate.sh [options]

基本的な使い方（キューモード）

# Image - submits to queue, waits for completion
bash generate.sh --prompt "A serene mountain landscape" --model "fal-ai/nano-banana-pro"

# Video - same, but takes longer
bash generate.sh --prompt "Ocean waves crashing" --model "fal-ai/veo3.1"

# Image-to-Video
bash generate.sh \
  --prompt "Camera slowly zooms in" \
  --model "fal-ai/kling-video/v2.6/pro/image-to-video" \
  --image-url "https://example.com/image.jpg"

非同期モード（すぐに返す）

時間のかかる動画ジョブでは、--async を使用すると request_id をすぐに取得できます。

# Submit and return immediately
bash generate.sh --prompt "Epic battle scene" --model "fal-ai/veo3.1" --async

# Output:
# Request ID: abc123-def456
# Request submitted. Use these commands to check:
#   Status: ./generate.sh --status "abc123-def456" --model "fal-ai/veo3.1"
#   Result: ./generate.sh --result "abc123-def456" --model "fal-ai/veo3.1"

キュー操作

# Check status
bash generate.sh --status "request_id" --model "fal-ai/veo3.1"
# → IN_QUEUE (position: 3) | IN_PROGRESS | COMPLETED

# Get result (when COMPLETED)
bash generate.sh --result "request_id" --model "fal-ai/veo3.1"

# Cancel (only if still queued)
bash generate.sh --cancel "request_id" --model "fal-ai/veo3.1"

生成中にログを表示する

bash generate.sh --prompt "A sunset" --model "fal-ai/nano-banana-pro" --logs
# Status: IN_QUEUE (position: 2)
# Status: IN_PROGRESS
#   > Loading model...
#   > Generating image...
# Status: COMPLETED

ファイルのアップロード

オプション 1：--file で自動アップロード

# Local file is automatically uploaded to fal CDN
bash generate.sh \
  --file "/path/to/photo.jpg" \
  --model "fal-ai/kling-video/v2.6/pro/image-to-video" \
  --prompt "Camera zooms in slowly"

オプション 2：upload.sh で手動アップロード

# Upload first
URL=$(bash upload.sh --file "/path/to/photo.jpg")
# → https://v3.fal.media/files/xxx/photo.jpg

# Then generate
bash generate.sh --image-url "$URL" --model "..." --prompt "..."

オプション 3：既存の URL を使用

# Any public URL works
bash generate.sh --image-url "https://example.com/image.jpg" ...

対応ファイル形式：

• 画像：jpg、jpeg、png、gif、webp
• 動画：mp4、mov、webm
• 音声：mp3、wav、flac

アップロードの流れ（2 段階）：

1. POST rest.alpha.fal.ai/storage/auth/token?storage_type=fal-cdn-v3
   → {"token": "...", "base_url": "https://v3b.fal.media"}

2. POST {base_url}/files/upload
   Authorization: Bearer {token}
   → {"access_url": "https://v3b.fal.media/files/..."}

最大ファイルサイズ： 100MB（シンプルアップロード）

引数リファレンス

引数	説明	デフォルト
--prompt, -p	テキストによる説明	（必須）
--model, -m	モデル ID	fal-ai/nano-banana-pro
--image-url	I2V 用の入力画像 URL	-
--file, --image	ローカルファイル（自動アップロード）	-
--size	square、portrait、landscape	landscape_4_3
--num-images	画像の枚数	1

モードオプション：

引数	説明
（デフォルト）	キューモード：送信し、完了するまでポーリングします
--async	キューに送信し、request_id をすぐに返します
--sync	同期モード（動画には推奨されません）
--logs	ポーリング中に生成ログを表示します

キュー操作：

引数	説明
--status ID	キュー内のリクエストのステータスを確認します
--result ID	完了したリクエストの結果を取得します
--cancel ID	キュー内のリクエストをキャンセルします

詳細設定：

引数	説明	デフォルト
--poll-interval	ステータス確認の間隔（秒）	2
--timeout	待機する最大秒数	600
--lifecycle N	オブジェクトの有効期限（秒）	-
--schema [MODEL]	OpenAPI スキーマを取得します	-

モデルを探す

最適な最新モデルを見つけるには、検索 API を使用します。

# Search by category
bash search-models.sh --category "text-to-image"
bash search-models.sh --category "text-to-video"
bash search-models.sh --category "image-to-video"

# Search by keyword
bash search-models.sh --query "flux"
bash search-models.sh --query "kling video"

または、関連するキーワードを指定して search_models MCP ツールを使用します。

カテゴリ： text-to-image、image-to-image、text-to-video、image-to-video、text-to-speech、speech-to-text

モデルスキーマを取得する（OpenAPI）

重要： 任意のモデルの正確なパラメーターを確認するには、スキーマを取得してください。

# Get schema
bash get-schema.sh --model "fal-ai/nano-banana-pro"

# Show only input parameters
bash get-schema.sh --model "fal-ai/kling-video/v2.6/pro/image-to-video" --input

# Quick schema via generate.sh
bash generate.sh --schema "fal-ai/veo3.1"

API エンドポイント：

https://fal.ai/api/openapi/queue/openapi.json?endpoint_id={model-id}

出力

キュー送信時のレスポンス：

{
  "request_id": "abc123-def456",
  "status": "IN_QUEUE",
  "response_url": "https://queue.fal.run/.../requests/abc123-def456",
  "status_url": "https://queue.fal.run/.../requests/abc123-def456/status",
  "cancel_url": "https://queue.fal.run/.../requests/abc123-def456/cancel"
}

最終結果：

{
  "images": [{ "url": "https://v3.fal.media/files/...", "width": 1024, "height": 768 }]
}

結果をユーザーに提示する

画像：

![Generated Image](https://v3.fal.media/files/...)
• 1024×768 | Generated in 2.2s

動画：

[Click to view video](https://v3.fal.media/files/.../video.mp4)
• Duration: 5s | Generated in 45s

非同期送信：

Request submitted to queue.
• Request ID: abc123-def456
• Model: fal-ai/veo3
• Check status: --status "abc123-def456"

オブジェクトの有効期間（任意）

生成されたファイルにアクセスできる期間を設定します。

# Files expire after 1 hour (3600 seconds)
bash generate.sh --prompt "..." --lifecycle 3600

# Files expire after 24 hours
bash generate.sh --prompt "..." --lifecycle 86400

トラブルシューティング

タイムアウトエラー

Error: Timeout after 600s
Request ID: abc123-def456

解決策： --status と --result を使って手動で確認するか、--timeout を増やしてください。

API キーエラー

Error: FAL_KEY not set

解決策： ./generate.sh --add-fal-key を実行するか、export FAL_KEY=your_key を実行してください。

ネットワークエラー（claude.ai）

claude.ai/settings/capabilities に移動し、許可ドメインに *.fal.ai を追加してください。