Get an API key from https://fal.ai/dashboard/keys
Then: export FAL_KEY="your-key-here"

# Fetch result
RESULT=$(curl -s "https://queue.fal.run/$1/requests/$REQUEST_ID" \
  -H "Authorization: Key $FAL_KEY")

# Create session output folder
mkdir -p ~/.fal/sessions/${CLAUDE_SESSION_ID}

# Download images/videos
# For images: jq -r '.images[0].url' and curl to download
# Save as: ~/.fal/sessions/${CLAUDE_SESSION_ID}/<timestamp>_<model>.png

fal.ai 模型 API 技能

在 fal.ai 上运行 1000+ 个生成式 AI 模型。

参数

• - 命令： $0（search | schema | run | status | result | upload）
• 参数 1： $1（模型 ID、搜索查询或文件路径）
• 参数 2+： $2、$3 等（附加参数）
• 所有参数： $ARGUMENTS

会话输出

将生成的文件保存到会话文件夹：
bash
mkdir -p ~/.fal/sessions/${CLAUDESESSIONID}

下载的图片/视频保存至：~/.fal/sessions/${CLAUDESESSIONID}/

---

身份验证

需要 FAL_KEY 环境变量。如果请求返回 401，请告知用户：

从 https://fal.ai/dashboard/keys 获取 API 密钥
然后执行：export FAL_KEY=your-key-here

---

命令：$0

如果 $0 = search

搜索与 $1 匹配的模型：

bash
curl -s https://api.fal.ai/v1/models?q=$1&limit=15 \
-H Authorization: Key $FALKEY | jq -r .models[] | • \(.endpointid) — \(.metadata.display_name) [\(.metadata.category)]

按类别搜索，请使用：
bash
curl -s https://api.fal.ai/v1/models?category=$1&limit=15 \
-H Authorization: Key $FALKEY | jq -r .models[] | • \(.endpointid) — \(.metadata.display_name)

类别：text-to-image、image-to-video、text-to-video、image-to-3d、training、speech-to-text、text-to-speech

---

如果 $0 = schema

获取模型 $1 的输入模式：

bash
curl -s https://api.fal.ai/v1/models?endpoint_id=$1&expand=openapi-3.0 \
-H Authorization: Key $FAL_KEY | jq .models[0].openapi.components.schemas.Input.properties

显示必填与可选字段，帮助用户了解需要哪些输入。

---

如果 $0 = run

使用剩余参数中的参数运行模型 $1。

步骤 1：解析参数
从 $ARGUMENTS 中提取模型 ID 后的 --key value 对，构建 JSON 负载。

示例：/fal run fal-ai/flux-2 --prompt a cat --imagesize landscape16_9
→ 模型：fal-ai/flux-2
→ 负载：{prompt: a cat, imagesize: landscape16_9}

步骤 2：提交到队列
bash
curl -s -X POST https://queue.fal.run/$1 \
-H Authorization: Key $FAL_KEY \
-H Content-Type: application/json \
-d

步骤 3：轮询直至完成
bash

从响应中获取 request_id，然后轮询：

while true; do
STATUS=$(curl -s https://queue.fal.run/$1/requests/$REQUEST_ID/status \
-H Authorization: Key $FAL_KEY | jq -r .status)
echo 状态：$STATUS
if [ $STATUS = COMPLETED ]; then break; fi
if [ $STATUS = FAILED ]; then echo 任务失败; break; fi
sleep 3
done

步骤 4：获取结果并保存
bash

获取结果

RESULT=$(curl -s https://queue.fal.run/$1/requests/$REQUEST_ID \
-H Authorization: Key $FAL_KEY)

创建会话输出文件夹

mkdir -p ~/.fal/sessions/${CLAUDESESSIONID}

下载图片/视频

对于图片：jq -r .images[0].url 然后使用 curl 下载

保存为：~/.fal/sessions/${CLAUDESESSIONID}/<时间戳>_<模型>.png

---

如果 $0 = status

检查模型 $1 的请求 $2 状态：

bash
curl -s https://queue.fal.run/$1/requests/$2/status?logs=1 \
-H Authorization: Key $FALKEY | jq {status: .status, queueposition: .queue_position, logs: .logs}

---

如果 $0 = result

获取模型 $1 已完成请求 $2 的结果：

bash
curl -s https://queue.fal.run/$1/requests/$2 \
-H Authorization: Key $FAL_KEY | jq .

---

如果 $0 = upload

将文件 $1 上传到 fal CDN：

bash
curl -s -X POST https://fal.run/fal-ai/storage/upload \
-H Authorization: Key $FAL_KEY \
-F file=@$1

返回用于模型请求的 URL。

---

快速参考

热门模型：

• - fal-ai/flux-2 — 快速文本转图像
• fal-ai/flux-2-pro — 高质量文本转图像
• fal-ai/kling-video/v2/image-to-video — 图像转视频
• fal-ai/minimax/video-01/image-to-video — 图像转视频
• fal-ai/whisper — 语音转文本

文本转图像的常用参数：

• - --prompt 描述 — 要生成的内容
• --imagesize landscape169 — 宽高比（square、portrait43、landscape169）
• --numimages 1 — 图像数量

调用示例：

• - /fal search video — 查找视频模型
• /fal schema fal-ai/flux-2 — 查看输入选项
• /fal run fal-ai/flux-2 --prompt a sunset over mountains
• /fal status fal-ai/flux-2 abc-123
• /fal upload ./photo.png