fal

# fal.ai Model API Skill

Run 1000+ generative AI models on fal.ai.

## Arguments

- **Command:** `$0` (search | schema | run | status | result | upload)
- **Arg 1:** `$1` (model_id, search query, or file path)
- **Arg 2+:** `$2`, `$3`, etc. (additional parameters)
- **All args:** `$ARGUMENTS`

## Session Output

Save generated files to session folder:
```bash
mkdir -p ~/.fal/sessions/${CLAUDE_SESSION_ID}
```

Downloaded images/videos go to: `~/.fal/sessions/${CLAUDE_SESSION_ID}/`

---

## Authentication

Requires `FAL_KEY` environment variable. If requests fail with 401, tell user:
```
Get an API key from https://fal.ai/dashboard/keys
Then: export FAL_KEY="your-key-here"
```

---

## Command: `$0`

### If $0 = "search"

Search for models matching `$1`:

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

For category search, use:
```bash
curl -s "https://api.fal.ai/v1/models?category=$1&limit=15" \
  -H "Authorization: Key $FAL_KEY" | jq -r '.models[] | "• \(.endpoint_id) — \(.metadata.display_name)"'
```

Categories: `text-to-image`, `image-to-video`, `text-to-video`, `image-to-3d`, `training`, `speech-to-text`, `text-to-speech`

---

### If $0 = "schema"

Get input schema for model `$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'
```

Show required vs optional fields to help user understand what inputs are needed.

---

### If $0 = "run"

Run model `$1` with parameters from remaining arguments.

**Step 1: Parse parameters**
Extract `--key value` pairs from `$ARGUMENTS` after the model_id to build JSON payload.

Example: `/fal run fal-ai/flux-2 --prompt "a cat" --image_size landscape_16_9`
→ Model: `fal-ai/flux-2`
→ Payload: `{"prompt": "a cat", "image_size": "landscape_16_9"}`

**Step...

# fal-skill

A [Claude Code](https://claude.ai/code) skill for running [fal.ai](https://fal.ai) generative AI models - image generation, video, audio, 3D, and more.

## Installation

```bash
git clone https://github.com/fal-ai/fal-skill ~/.claude/skills/fal
```

## Setup

1. Get an API key from [fal.ai/dashboard/keys](https://fal.ai/dashboard/keys)

2. Add to your shell config (`~/.zshrc` or `~/.bashrc`):
   ```bash
   export FAL_KEY="your-key-here"
   ```

3. Reload your shell:
   ```bash
   source ~/.zshrc
   ```

## Usage

### Commands

| Command | Description |
|---------|-------------|
| `/fal search <query>` | Search 600+ models |
| `/fal schema <model_id>` | Get input/output schema |
| `/fal run <model_id> --param value` | Run a model |
| `/fal status <model_id> <request_id>` | Check job status |
| `/fal result <model_id> <request_id>` | Get job result |
| `/fal upload <file>` | Upload file to fal CDN |

### Examples

```bash
# Search for models
/fal search video

# See what inputs a model accepts
/fal schema fal-ai/flux-2

# Generate an image
/fal run fal-ai/flux-2 --prompt "a cat in space"
```

Or just ask Claude naturally:

> "Generate an image of a sunset over mountains"

> "Turn this photo into a video"

> "What image models are available?"

## Popular Models

| Model | Category |
|-------|----------|
| `fal-ai/flux-2` | Text to image |
| `fal-ai/flux-2-pro` | Text to image (high quality) |
| `fal-ai/kling-video/v2/image-to-video` | Image to video |
| `fal-ai/minimax/video-01/image-to-video` | Image to video |
| `fal-ai/whisper` | Speech to text |

See [models-reference.md](models-reference.md) for a full list.

## How It Works

This skill teaches Claude how to interact with fal.ai APIs using curl. When you ask Claude to generate media, it:

1. Searches for appropriate models (if needed)
2. Fetches the model schema to understand required inputs
3. Submits the job to fal's queue
4. Polls for completion
5. Downloads results to your machine

## Links

- [fa...