fal-generate

fal.ai 生成

使用 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

上传流程（两步）：

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 添加到允许的域名。