Falai

Prerequisites

• A fal.ai API key (get one at https://fal.ai/dashboard/keys)
• Go 1.24 or newer (for building the CLI binary during install)
• Internet access to reach the fal.ai API

How to use this skill

The skill provides three helper scripts at ~/.claude/skills/falai/scripts/:

• detect-config.sh — checks if the API key is configured
• invoke.sh — runs a JSON action against the CLI binary
• init-config.sh — interactive API key setup (for non-Claude users)

1. Check configuration

Before running any action, check if the API key is configured:

~/.claude/skills/falai/scripts/detect-config.sh

On success, this prints the config file path. On failure, it exits non-zero and the first-run flow should be used.

2. First-run self-setup (if detect-config fails)

If detect-config.sh exits non-zero, walk the user through setup:

1. Announce the flow: explain that the fal.ai skill needs an API key to generate images, videos, and audio.

2. Collect the API key via AskUserQuestion: ask for the fal.ai API key. Direct the user to https://fal.ai/dashboard/keys if they don't have one. NEVER echo or display the API key in output. The API key MUST be treated as a secret.

3. Write the config file to ~/.config/falai/config.yaml:

   mkdir -p ~/.config/falai && chmod 700 ~/.config/falai
   cat > ~/.config/falai/config.yaml << EOF
   api_key: "THE_KEY_HERE"
   timeout: 300
   EOF
   chmod 600 ~/.config/falai/config.yaml
   

4. Verify with a ping:

   echo '{"action":"ping"}' | ~/.claude/skills/falai/scripts/invoke.sh
   

   Expect {"ok":true,...} with "status":"ok". If the response shows AUTH_ERROR, the key is invalid.

5. Report ready and continue with the original request.

3. Invoking actions (the normal case)

Once configured, every action is a single invoke.sh call. Pass the JSON payload on stdin or as the first argument.

# JSON on stdin
echo '{"action":"ping"}' | ~/.claude/skills/falai/scripts/invoke.sh

# JSON as argument
~/.claude/skills/falai/scripts/invoke.sh '{"action":"generate-image","model":"flux/schnell","prompt":"a cat in space"}'

# With download
~/.claude/skills/falai/scripts/invoke.sh '{"action":"generate-image","model":"flux/schnell","prompt":"sunset over mountains","download":true,"output_dir":"./output"}'

4. Action reference

Full action reference with required fields, optional fields, and response shapes: reference/actions.md. Copy-paste examples: reference/examples.md.

Rule: before constructing a payload for an action you have not used in the current session, consult reference/actions.md. Do not guess field names.

Supported actions:

• System: ping, list-models
• Image: generate-image (text-to-image and image-to-image)
• Video: generate-video (text-to-video and image-to-video)
• Speech: generate-speech (text-to-speech and voice changing)
• Music: generate-music (text-to-music)
• Transcription: transcribe (audio-to-text)
• Jobs: check-job, get-job-result (async job management)

5. Model recommendation guide

When the user asks to generate content without specifying a model, use AskUserQuestion to present appropriate choices. Here are the recommended defaults by use case:

Quick image generation (fastest):

• flux/schnell — fast, good quality, best default for quick iteration
• fast-sdxl — very fast, lower quality

High-quality images:

• flux-pro/v1.1-ultra — highest quality, supports aspect ratios
• flux-2-pro — professional next-gen quality
• hidream-i1-full — HiDream 17B, detailed images, supports negative prompts

Image editing:

• flux-2-pro/edit — edit images with text instructions (requires image_urls)
• flux-2/edit — affordable image editing (requires image_urls)

Style transfer:

• ghiblify — Studio Ghibli anime style (requires image_url)
• cartoonify — Pixar-style cartoon (requires image_url)
• star-vector — SVG vectorization (requires image_url)

Video from image (image-to-video):

• veo2 — Google Veo2, high quality
• veo3 — Google Veo3, latest generation
• kling-video-v3-image — Kling V3, very high quality
• minimax/video-01-subject-reference — preserves subject identity
• luma-dream-machine — Luma Labs
• seedance-2.0-image — ByteDance Seedance

Video from text (text-to-video):

• minimax/video-01-director — with camera movement control
• minimax/video-01 — high resolution, high frame rate
• minimax/hailuo-02 — latest Minimax model
• kling-video-v3-text — Kling V3 from text
• hunyuan-video — Tencent Hunyuan
• seedance-2.0-text — ByteDance Seedance from text

Text-to-speech:

• elevenlabs/tts/turbo-v2.5 — ElevenLabs, highest quality
• minimax-tts/text-to-speech — Minimax TTS
• chatterbox-tts — Chatterbox, open model
• elevenlabs-dialog — ElevenLabs multi-speaker dialog

Music:

• minimax-music-v2 — Minimax music generation
• stable-audio-25 — Stability AI music

Transcription:

• elevenlabs/speech-to-text/scribe-v2 — ElevenLabs with speaker diarization

Voice changing:

• elevenlabs-voice-changer — change voice characteristics (requires audio_url)

Video to audio:

• mmaudio-v2 — generate audio from video content

When multiple models fit the user's request, present 2-3 options via AskUserQuestion with brief descriptions of the tradeoffs (speed vs quality, cost, style).

6. Error handling

Exit codes from invoke.sh:

• 0 — success. stdout contains the JSON result.
• 1 — bad input, missing action, or binary not found.
• 2 — config error (missing API key).
• 3 — API error (fal.ai returned an error, job failed, timeout).

Error responses have the shape:

{"ok": false, "error": "description", "code": "ERROR_CODE"}

Error codes: INVALID_INPUT, INVALID_MODEL, UNKNOWN_ACTION, CONFIG_ERROR, AUTH_ERROR, API_ERROR, HANDLER_ERROR, MISSING_BINARY.

When you see an error, consult reference/errors.md for cause and fix. Do not retry blindly.

7. Cost awareness

Generation requests cost real money against the user's fal.ai balance. Before running expensive operations:

• Confirm batch operations — if generating more than 3 items in a sequence
• Confirm video generation — video models are typically more expensive than image models
• Confirm high-quality models — pro and ultra models cost more than standard ones
• Check model choice — suggest cheaper alternatives when the task doesn't require the highest quality

A user asking to "generate an image" is implicit consent for a single generation. Batch generation or expensive model choices should be confirmed.

8. Update procedure

When the fal package in braibot is updated with new models, rebuild the skill:

cd /path/to/claude-skill-falai
go get -u github.com/karamble/braibot@latest
go build -o skill/bin/falai-cli ./cmd/falai-cli/
./install.sh --force

After updating, run list-models to see newly available models. New models registered in the fal package are automatically available without any CLI code changes.

9. Common workflows

Generate a quick image:

1. list-models (optional — to show the user available image models)
2. generate-image with model: "flux/schnell", prompt, optional download: true
3. Share the URL or local path with the user

Generate a high-quality image:

1. Ask the user which model they prefer via AskUserQuestion (flux-pro/v1.1-ultra, flux-2-pro, or hidream-i1-full)
2. generate-image with the chosen model and prompt
3. Download if requested

Create a video from an image:

1. Ask the user which video model to use (veo2, kling, minimax, etc.)
2. generate-video with model, image_url, prompt (for motion guidance)
3. Wait for completion (video generation takes longer, 30s-5min)
4. Download the result

Text-to-speech:

1. generate-speech with model: "elevenlabs-tts-turbo-v2.5", text: "...", optional voice settings in options
2. Download the audio file

Transcribe audio:

1. transcribe with model: "elevenlabs-scribe-v2", audio_url: "..."
2. Return the transcribed text

Check a long-running job:

1. Note the response_url from the initial submission (in stderr progress output)
2. check-job with response_url to see current status
3. get-job-result once status is COMPLETED

10. Limitations

• API key required. A fal.ai account with API access is needed. The skill cannot generate anything without a valid key.
• Async operations. All generation goes through fal.ai's queue. Jobs may take seconds to minutes depending on model and queue load.
• URL expiration. fal.ai media URLs are temporary and expire. Use download: true to save files locally for permanent access.
• Rate limits. fal.ai may rate-limit requests. If you see rate limit errors, wait and retry.
• Model availability. Models may be temporarily unavailable on fal.ai's side. Check the fal.ai status page if a model consistently fails.
• No streaming. The CLI polls for completion. Progress updates go to stderr but the final result is only available once the job completes.

Reference files

Actions and models:

• reference/actions.md — full action reference
• reference/models.md — model catalog by category
• reference/examples.md — copy-paste JSON payloads
• reference/errors.md — error codes and fixes
• reference/troubleshooting.md — common issues

Configuration:

• templates/config.yaml.example — config file schema

Helper scripts:

• scripts/detect-config.sh — checks config exists
• scripts/invoke.sh — runs JSON actions
• scripts/init-config.sh — interactive API key setup