1---
2name: fal-ai-video-toolkit
3description: Generate videos, animate images, transfer motion, create speaking avatars, and edit/upscale images via fal.ai. Supports Kling (O3, v3 Pro, Turbo), Seedance 1.5 Pro, HeyGen Avatar, and Seedream (v4.5, v5). Use when the user wants to generate video from image, do motion transfer, make a photo speak, or upscale/edit images with fal.ai.
4compatibility: "Runtimes: codex, claude-code, openclaw · OS: linux, darwin, win32"
5---
6 
7# fal.ai Video & Image Toolkit
8 
9Unified CLI for video generation, motion transfer, speaking avatars, and image editing via fal.ai.
10 
11## Quick start
12 
13```bash
14uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
15  --image ./photo.png \
16  --model kling-o3 \
17  --prompt "a person walking forward confidently" \
18  --duration 10 \
19  --out ./output.mp4
20```
21 
22## Available models
23 
24| Shortcut | Endpoint | Type | Price |
25|----------|----------|------|-------|
26| `kling-o3` | `fal-ai/kling-video/o3/standard/image-to-video` | image-to-video | $0.084/s |
27| `kling-v3-pro` | `fal-ai/kling-video/v3/pro/image-to-video` | image-to-video | $0.112/s |
28| `kling-turbo` | `fal-ai/kling-video/v2.5-turbo/pro/image-to-video` | image-to-video | $0.07/s |
29| `seedance` | `fal-ai/bytedance/seedance/v1.5/pro/image-to-video` | image-to-video | ~$0.26/5s |
30| `kling-motion` | `fal-ai/kling-video/v3/pro/motion-control` | motion transfer | $0.126/s |
31| `kling-motion-std` | `fal-ai/kling-video/v3/standard/motion-control` | motion transfer | cheaper |
32| `heygen` | `fal-ai/heygen/avatar4/image-to-video` | speaking avatar | $0.10/s |
33| `seedream-v5` | `fal-ai/bytedance/seedream/v5/lite/edit` | image edit/upscale | $0.035/img |
34| `seedream-v4` | `fal-ai/bytedance/seedream/v4.5/edit` | image edit/transform | $0.04/img |
35| `grok-text` | `xai/grok-imagine-video/text-to-video` | text-to-video | see fal |
36| `grok-image` | `xai/grok-imagine-video/image-to-video` | image-to-video | see fal |
37| `grok-edit` | `xai/grok-imagine-video/edit-video` | video-to-video edit | see fal |
38 
39Or pass any full fal endpoint as `--model fal-ai/...`.
40 
41## Credentials
42 
43Resolved in order: `--api-key` > `--api-key-file` > `FAL_KEY` > `FAL_API_KEY` > `FAL_AI_KEY` > `FAL_KEY_ID`+`FAL_KEY_SECRET`
44 
45## Usage patterns
46 
47### Image to video (Kling O3, default)
48 
49```bash
50uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
51  --image ./photo.png \
52  --model kling-o3 \
53  --prompt "description of desired motion" \
54  --duration 10 \
55  --no-audio \
56  --out ./video.mp4
57```
58 
59### Image to video (Seedance 1.5 Pro, with audio)
60 
61```bash
62uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
63  --image ./photo.png \
64  --model seedance \
65  --prompt "description of motion" \
66  --duration 10 \
67  --resolution 1080p \
68  --out ./video.mp4
69```
70 
71### Motion transfer
72 
73```bash
74uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
75  --image ./person.png \
76  --video ./dance_reference.mp4 \
77  --model kling-motion \
78  --orientation video \
79  --prompt "photorealistic person following the motion naturally" \
80  --out ./motion_output.mp4
81```
82 
83### Motion transfer from a source video's frame
84 
85```bash
86uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
87  --extract-first-frame-from-video ./identity-source.mp4 \
88  --extract-frame-time 00:00:00.500 \
89  --video ./dance_reference.mp4 \
90  --model kling-motion-std \
91  --orientation image \
92  --prompt "photorealistic subject, keep identity from the extracted frame, follow the source performance naturally" \
93  --out ./motion_from_video.mp4
94```
95 
96### Motion transfer + Telegram delivery
97 
98```bash
99uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
100  --extract-first-frame-from-video ./identity-source.mp4 \
101  --extract-frame-time 00:00:00.500 \
102  --video ./dance_reference.mp4 \
103  --model kling-motion-std \
104  --orientation image \
105  --prompt "photorealistic subject, keep identity from the extracted frame, follow the source performance naturally" \
106  --out ./motion_from_video.mp4 \
107  --telegram-target @mychat \
108  --telegram-thread-id 42 \
109  --telegram-message "render ready"
110```
111 
112### Grok Imagine text-to-video
113 
114```bash
115uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
116  --model grok-text \
117  --prompt "cinematic handheld shot of a storm rolling over Kyiv rooftops" \
118  --duration 6 \
119  --resolution 720p \
120  --aspect-ratio 16:9 \
121  --out ./grok-text.mp4
122```
123 
124### Grok Imagine image-to-video
125 
126```bash
127uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
128  --image ./start_frame.png \
129  --model grok-image \
130  --prompt "subtle camera push-in, hair moving in the wind, natural motion" \
131  --duration 6 \
132  --resolution 720p \
133  --aspect-ratio 9:16 \
134  --out ./grok-image.mp4
135```
136 
137### Grok Imagine from a reference video's first frame
138 
139```bash
140uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
141  --extract-first-frame-from-video ./reference.mp4 \
142  --model grok-image \
143  --prompt "continue the scene with smooth realistic motion" \
144  --duration 6 \
145  --out ./grok-from-frame.mp4
146```
147 
148### Grok Imagine video edit
149 
150```bash
151uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
152  --video ./reference.mp4 \
153  --model grok-edit \
154  --prompt "convert this clip into a moody neon cyberpunk scene" \
155  --resolution 720p \
156  --out ./grok-edit.mp4
157```
158 
159### Speaking avatar (HeyGen)
160 
161```bash
162uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
163  --image ./face.png \
164  --model heygen \
165  --prompt "Hello! Welcome to the show" \
166  --talking-style expressive \
167  --resolution 720p \
168  --aspect-ratio 9:16 \
169  --out ./speaking.mp4
170```
171 
172### Image upscale (Seedream v5 to 2K)
173 
174```bash
175uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
176  --image ./photo.png \
177  --model seedream-v5 \
178  --prompt "enhance quality, sharpen details, keep original appearance" \
179  --out ./upscaled.png
180```
181 
182### Image transform (Seedream v4.5, replace character)
183 
184```bash
185uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
186  --image ./scene.png \
187  --model seedream-v4 \
188  --prompt "Replace the character with a photorealistic person, keep same pose and background" \
189  --image-size 2048x2048 \
190  --out ./transformed.png
191```
192 
193### Start + end frame video
194 
195```bash
196uv run --with fal-client {baseDir}/scripts/fal_video_toolkit.py \
197  --image ./start_frame.png \
198  --end-image ./end_frame.png \
199  --model kling-o3 \
200  --prompt "smooth transition between poses" \
201  --duration 5 \
202  --out ./transition.mp4
203```
204 
205## Key flags
206 
207| Flag | Description |
208|------|-------------|
209| `--model` | Model shortcut or full fal endpoint |
210| `--duration` | Video length in seconds |
211| `--orientation` | `image` or `video` (motion control) |
212| `--resolution` | `480p`/`720p`/`1080p` (Seedance, HeyGen) |
213| `--aspect-ratio` | `16:9`, `9:16`, `1:1` etc |
214| `--no-audio` | Disable audio generation |
215| `--no-safety` | Disable client safety checker |
216| `--negative-prompt` | What to exclude (Kling) |
217| `--talking-style` | `stable` or `expressive` (HeyGen) |
218| `--image-size` | Output size for Seedream (e.g. `2048x2048`) |
219| `--end-image` | End frame for transition videos |
220| `--extract-first-frame-from-video` | Extract frame from a reference video and use it as `--image` |
221| `--extract-frame-time` | Timestamp for the extracted frame (default `00:00:00`) |
222| `--telegram-target` | Send the finished media to Telegram after download |
223| `--telegram-thread-id` | Optional Telegram topic/thread id for delivery |
224| `--telegram-reply-to` | Optional Telegram message id to reply to |
225| `--telegram-message` | Optional Telegram caption/message |
226| `--json-out` | Save raw API response for debugging |
227 
228## Guardrails
229 
230- Start with the best possible image. Models transfer motion better than they fix bad composites.
231- For motion control, match the source image pose to the first frame of the reference video.
232- Keep examples generic; pass file paths, Telegram targets, and thread ids explicitly instead of baking personal values into the skill.
233- Images >5MB must be resized before Kling motion control: `ffmpeg -y -i big.png -vf "scale=1080:1920:force_original_aspect_ratio=decrease" small.png`
234- Multiple motion transfers or image-to-video calls are independent — run them in parallel for multi-scene workflows.
235- Keep prompts short, positive, and direct.
236- Seedance duration must be a string (`"10"` not `10`), the script handles this automatically.
237- Grok Imagine video endpoints on fal.ai do not currently expose a documented `enable_safety_checker` or NSFW toggle. The script warns instead of silently pretending `--no-safety` works there.
238- For full model specs and parameters, see `references/fal-models.md`.
239