fal

https://fal.ai/docs/
Admin
fal is a generative media platform providing 600+ ready-to-use AI models, serverless GPU...
Tokens:1,357,093
Snippets:10,387
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### Quick Start: Python subscribe example

Source: https://fal.ai/docs/model-api-reference/video-generation-api/kling-video-o1-standard-image-to-video

Uses fal_client.subscribe to run the model with a prompt and start image URL, logging progress updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/kling-video/o1/standard/image-to-video",
    arguments={
        "prompt": "Create a magical timelapse transition. The snow melts rapidly to reveal green grass, and the tree branches burst into bloom with pink flowers in real-time. The lighting shifts from cold winter light to warm spring sunshine. The camera pushes in slowly towards the tree. Disney-style magical transformation, cinematic, 8k.",
        "start_image_url": "https://v3b.fal.media/files/b/rabbit/NaslJIC7F2WodS6DFZRRJ.png"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start

Source: https://fal.ai/docs/api-reference/client-libraries/javascript

Example of using fal.subscribe to run a model and get the result.

```APIDOC
## Quick Start

```javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/flux/dev", {
  input: {
    prompt: "a cat wearing a hat",
    image_size: "landscape_4_3"
  },
  logs: true,
  onQueueUpdate: (status) => console.log(`Status: ${status.status}`)
});

console.log(result.data.images[0].url);
```
```

--------------------------------

### Quick Start: cURL request example

Source: https://fal.ai/docs/model-api-reference/video-generation-api/kling-video-o1-standard-image-to-video

Sends a POST request to the endpoint with the prompt and start image URL, using an API key for authorization.

```bash
curl --request POST \
  --url https://fal.run/fal-ai/kling-video/o1/standard/image-to-video \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "prompt": "Create a magical timelapse transition. The snow melts rapidly to reveal green grass, and the tree branches burst into bloom with pink flowers in real-time. The lighting shifts from cold winter light to warm spring sunshine. The camera pushes in slowly towards the tree. Disney-style magical transformation, cinematic, 8k.",
  "start_image_url": "https://v3b.fal.media/files/b/rabbit/NaslJIC7F2WodS6DFZRRJ.png"
}'
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/bria-embed-product

Python example using fal_client to subscribe to the 'bria/embed-product' endpoint. It prints logs and the result.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "bria/embed-product",
    arguments={},
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start: Python subscribe example

Source: https://fal.ai/docs/model-api-reference/3d-api/hunyuan-3d-v3.1-part

Python example using fal_client.subscribe to call the endpoint with an input file URL and log progress updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/hunyuan-3d/v3.1/part",
    arguments={
        "input_file_url": "https://v3b.fal.media/files/b/0a8bf92a/XECcItG5QHt0LViFTRCON_converted.fbx"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start: Python subscribe example for more-detailed-caption

Source: https://fal.ai/docs/model-api-reference/vision-api/florence-2-large

Python example using fal_client.subscribe to run the more-detailed-caption endpoint with an image URL and log progress.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/florence-2-large/more-detailed-caption",
    arguments={
        "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/car.jpg"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start Python Example for Kling Video O1 Standard Video-to-Video Reference

Source: https://fal.ai/docs/model-api-reference/video-generation-api/kling-video-o1-standard-video-to-video

Python client example using fal_client.subscribe to run the model. Includes an on_queue_update callback that prints log messages while the request is in progress.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/kling-video/o1/standard/video-to-video/reference",
    arguments={
        "prompt": "Based on @Video1, generate the next shot. keep the style of the video",
        "video_url": "https://v3b.fal.media/files/b/panda/oVdiICFXY03Vbam-08Aj8_output.mp4"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start JavaScript Example for Kling Video O1 Standard Video-to-Video Reference

Source: https://fal.ai/docs/model-api-reference/video-generation-api/kling-video-o1-standard-video-to-video

JavaScript client example using fal.subscribe from @fal-ai/client. Logs progress messages and prints the result data and request ID.

```javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/kling-video/o1/standard/video-to-video/reference", {
  input: {
      prompt: "Based on @Video1, generate the next shot. keep the style of the video",
      video_url: "https://v3b.fal.media/files/b/panda/oVdiICFXY03Vbam-08Aj8_output.mp4"
    },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);
```

--------------------------------

### Quick Start - Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/flux-dev

Python example using fal_client.subscribe to run the fal-ai/flux/dev/image-to-image model. Includes an on_queue_update callback to print logs.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/flux/dev/image-to-image",
    arguments={
        "image_url": "https://fal.media/files/koala/Chls9L2ZnvuipUTEwlnJC.png",
        "prompt": "A cat dressed as a wizard with a background of a mystic forest."
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### start() method example

Source: https://fal.ai/docs/documentation/serverless/distributed/api-reference

Example of using start() within an app's setup() method to initialize workers.

```python
class MyApp(fal.App):
    num_gpus = 2
    
    async def setup(self):
        self.runner = DistributedRunner(
            worker_cls=MyWorker,
            world_size=self.num_gpus,
        )
        
        # Start workers and pass model path to their setup()
        await self.runner.start(model_path="/data/models/flux")
        
        # Workers are now ready to process requests
```

--------------------------------

### Using preload_files in setup()

Source: https://fal.ai/docs/documentation/serverless/optimizations/parallel-file-loading

Example of calling the preload_files helper at the start of setup() before loading the model.

```python
def setup(self):
    preload_files("/data/models/my-model")
    self.model = load_model("/data/models/my-model")
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/video-generation-api/kling-video-o3-standard-reference-to-video

Subscribe to the fal-ai/kling-video/o3/standard/reference-to-video endpoint with empty arguments and log progress updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/kling-video/o3/standard/reference-to-video",
    arguments={},
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start - Python

Source: https://fal.ai/docs/model-api-reference/video-generation-api/veo3.1-lite

Subscribe to the fal-ai/veo3.1/lite endpoint with a prompt and log progress updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/veo3.1/lite",
    arguments={
        "prompt": "A massive blue whale glides through crystal-clear deep ocean water, sunlight rays piercing through the surface above, bioluminescent plankton scattered around, cinematic slow motion"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### DistributedRunner and DistributedWorker example usage

Source: https://fal.ai/docs/documentation/serverless/distributed/overview

Shows how to define a custom worker extending DistributedWorker, create a DistributedRunner in an fal.App setup, and invoke the worker with a request. The worker loads a model in setup() and generates output in __call__(). The runner is started with model_path and uses num_gpus=4.

```python
from fal.distributed import DistributedRunner, DistributedWorker

class MyWorker(DistributedWorker):
    def setup(self, model_path):
        # Load model on this GPU (called once per worker)
        self.model = load_model(model_path).to(self.device)
    
    def __call__(self, prompt, **kwargs):
        # Process request (called for each request)
        return self.model.generate(prompt)

class MyApp(fal.App):
    num_gpus = 4  # Use 4 GPUs
    
    async def setup(self):
        # Create and start the runner
        self.runner = DistributedRunner(
            worker_cls=MyWorker,
            world_size=self.num_gpus
        )
        await self.runner.start(model_path="/data/model")
    
    @fal.endpoint("/")
    async def run(self, request: MyRequest):
        # Invoke workers for each request
        result = await self.runner.invoke({
            "prompt": request.prompt,
        })
        return result
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/video-generation-api/topaz-upscale

Python example using fal_client.subscribe to run the Topaz Upscale model. It includes an on_queue_update callback to print logs and submits a video_url argument.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/topaz/upscale/video",
    arguments={
        "video_url": "https://v3.fal.media/files/kangaroo/y5-1YTGpun17eSeggZMzX_video-1733468228.mp4"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/z-image-turbo-tiling

Python example using fal_client.subscribe to generate a tiling image. It includes an on_queue_update callback to print progress logs.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/z-image/turbo/tiling",
    arguments={
        "prompt": "A hyper-realistic, high-resolution 4k texture of an ancient weathered brick wall heavily overgrown with lush green moss and soft lichens. The bricks are aged, featuring deep earthy tones, natural cracks, and gritty textures. Vibrant emerald moss fills the mortar lines and spills over the rough surfaces of the stones. Uniform, flat cinematic lighting ensures no harsh shadows, highlighting the intricate organic details and damp stone surfaces. The composition is a perfectly balanced overhead view, showcasing a rich tapestry of botanical growth and masonry craftsmanship with professional clarity and hyper-detailed grit."
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Remote execution with fal.App subclass and setup method

Source: https://fal.ai/docs/documentation/development/app-lifecycle

Shows a fal.App subclass that is pickled locally and instantiated remotely. CONFIG is a small dictionary that gets pickled and shipped. The diffusers import inside setup() runs remotely where the package is installed via requirements. The StableDiffusionXLPipeline is loaded into GPU memory on the runner.

```python
import fal

CONFIG = {"model_name": "stabilityai/sdxl-base"}

class MyApp(fal.App):
    machine_type = "GPU-A100"
    requirements = ["torch", "diffusers"]

    def setup(self):
        from diffusers import StableDiffusionXLPipeline
        self.pipe = StableDiffusionXLPipeline.from_pretrained(
            CONFIG["model_name"]
        ).to("cuda")

    @fal.endpoint("/")
    def generate(self, input: dict) -> dict:
        result = self.pipe(input["prompt"]).images[0]
        return {"image": result}
```

--------------------------------

### FluxWorker setup() example

Source: https://fal.ai/docs/documentation/serverless/distributed/api-reference

Example of overriding setup() to load a Flux model, disable progress bar for non-main workers, and print status messages.

```python
class FluxWorker(DistributedWorker):
    def setup(self, model_path: str = "/data/flux", **kwargs):
        """Initialize the Flux model on this GPU"""
        import torch
        from diffusers import FluxPipeline
        
        self.rank_print(f"Loading Flux on {self.device}")
        
        self.pipeline = FluxPipeline.from_pretrained(
            model_path,
            torch_dtype=torch.bfloat16,
        ).to(self.device)
        
        # Disable progress bar for non-main workers
        if self.rank != 0:
            self.pipeline.set_progress_bar_config(disable=True)
        
        self.rank_print("Model loaded successfully")
```

--------------------------------

### Quick Start with Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/bria-reimagine

Subscribe to the fal-ai/bria/reimagine endpoint with a prompt and log progress updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/bria/reimagine",
    arguments={
        "prompt": "A 2d illustration of a dog in a vibrant park"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Install @fal-ai/server-proxy

Source: https://fal.ai/docs/documentation/model-apis/inference/client-setup

Installs the server proxy package for client-side setup.

```bash
npm install @fal-ai/server-proxy
```

--------------------------------

### gpus method example

Source: https://fal.ai/docs/api-reference/python-sdk/api-reference

Example of getting GPU usage for an app and printing the total and GPU breakdown.

```python
usage = client.apps.gpus("fal-ai/flux")
print(usage["total"])  # e.g. 21
print(usage["gpus"])   # e.g. {"B200": 21}
```

--------------------------------

### Quick Start with Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/flux-pro-kontext-multi

Subscribe to the fal-ai/flux-pro/kontext/multi model using the fal_client library. The example shows how to handle queue updates and pass a prompt with multiple image URLs.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/flux-pro/kontext/multi",
    arguments={
        "prompt": "Put the little duckling on top of the woman's t-shirt.",
        "image_urls": [
            "https://v3.fal.media/files/penguin/XoW0qavfF-ahg-jX4BMyL_image.webp",
            "https://v3.fal.media/files/tiger/bml6YA7DWJXOigadvxk75_image.webp"
        ]
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### skills.retrieve example

Source: https://fal.ai/docs/documentation/agent/sdk/methods

Example of using agent.skills.retrieve to read a visible fal or installed skill by ID, then logging its body.

```typescript
import { agent } from "./client.ts";

const skill =
  await agent.skills.retrieve("SKILL_ID");
console.log(skill.body);
```

--------------------------------

### Quick Start - Python

Source: https://fal.ai/docs/model-api-reference/video-generation-api/bytedance-seedance-2.0-reference-to-video

Subscribe to the model using fal_client with a prompt and log updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "bytedance/seedance-2.0/reference-to-video",
    arguments={
        "prompt": "An octopus finds a football in the ocean and excitedly calls its octopus friends to come and play. Cut scene to an octopus football game under the sea."
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Install fal with pinned version

Source: https://fal.ai/docs/examples/serverless/cut-cold-starts

Install fal version 1.78.2, pinned to match the example's requirements.txt.

```bash
pip install fal==1.78.2  # keep pinned to this example's requirements.txt
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/bria-text-to-image

Subscribe to the fal-ai/bria/text-to-image/hd endpoint with a prompt and log progress updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/bria/text-to-image/hd",
    arguments={
        "prompt": "A lone figure stands on the edge of a serene cliff at sunset, gazing out over a vast, mystical valley. The figure is clad in flowing robes that ripple in the gentle breeze, silhouetted against the golden and lavender hues of the sky. Below, a cascading waterfall pours into a sparkling river winding through a forest of bioluminescent trees. The scene blends the awe of nature with a touch of otherworldly wonder, inviting reflection and imagination."
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start: Python subscription example

Source: https://fal.ai/docs/model-api-reference/video-generation-api/kling-video-o3-pro-text-to-video

Uses fal_client.subscribe to run the model with logs and a queue update handler. Prints the result after completion.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/kling-video/o3/pro/text-to-video",
    arguments={},
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### 200 response example for get file ACL

Source: https://fal.ai/docs/platform-apis/v1/storage/files/acl/get

Example of a successful response containing the default decision and user-specific rules.

```json
{
  "default": "forbid",
  "rules": [
    {
      "user": "my-teammate",
      "decision": "allow"
    }
  ]
}
```

--------------------------------

### skills.uninstall example

Source: https://fal.ai/docs/documentation/agent/sdk/methods

Example of using agent.skills.uninstall to remove an installed user skill and its disabled preference entry. Fal skills cannot be uninstalled.

```typescript
import { agent } from "./client.ts";

await agent.skills.uninstall("SKILL_ID");
```

--------------------------------

### Python Quick Start

Source: https://fal.ai/docs/model-api-reference/image-generation-api/ideogram-character

Python example using fal_client.subscribe to run the fal-ai/ideogram/character/edit endpoint. Includes an on_queue_update callback to print progress logs. Requires the fal_client package and a FAL key.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/ideogram/character/edit",
    arguments={
        "prompt": "woman holding bag",
        "image_url": "https://v3.fal.media/files/panda/-LC_gNNV3wUHaGMQT3klE_output.png",
        "mask_url": "https://v3.fal.media/files/panda/jVDAgSkpsZFDP080ceSZJ_woman_face_mask.png",
        "reference_image_urls": [
            "https://v3.fal.media/files/kangaroo/0rinwnj_Kn9Fsu2dK-aKm_image.png"
        ]
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start: JavaScript subscribe example for more-detailed-caption

Source: https://fal.ai/docs/model-api-reference/vision-api/florence-2-large

JavaScript example using @fal-ai/client to subscribe to the more-detailed-caption endpoint, logging progress and output.

```javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/florence-2-large/more-detailed-caption", {
  input: {
      image_url: "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/car.jpg"
    },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/topaz-upscale

Subscribe to the fal-ai/topaz/upscale/image endpoint with an image URL and log progress updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/topaz/upscale/image",
    arguments={
        "image_url": "https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/bria-product-shot

Subscribes to the fal-ai/bria/product-shot endpoint with an image URL and logs progress updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/bria/product-shot",
    arguments={
        "image_url": "https://storage.googleapis.com/falserverless/bria/bria_product_fg.jpg"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Load FlashPack file in fal app setup

Source: https://fal.ai/docs/documentation/serverless/optimizations/flashpack

Example fal app that loads a FlashPack file from /data in setup() using assign_from_file.

```python
import fal
from flashpack import assign_from_file
from pydantic import BaseModel

class Input(BaseModel):
    prompt: str

class MyModel(fal.App):
    machine_type = "GPU-A100"
    requirements = ["flashpack", "torch", "diffusers"]

    def setup(self):
        import torch
        from my_model import build_model

        self.model = build_model()
        assign_from_file(self.model, "/data/models/my-model.flashpack")

    @fal.endpoint("/")
    def generate(self, input: Input) -> dict:
        return self.model(input.prompt)
```

--------------------------------

### device property usage example

Source: https://fal.ai/docs/documentation/serverless/distributed/api-reference

Example of using self.device in a worker's setup() to load a model onto the worker's GPU.

```python
class MyWorker(DistributedWorker):
    def setup(self):
        # Load model on this worker's GPU
        self.model = MyModel().to(self.device)
        print(f"Model loaded on {self.device}")
```

--------------------------------

### Quick Start - Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/bytedance-seedream-v5-lite

Python example using fal_client.subscribe to run the Seedream 5.0 Lite model. It includes an on_queue_update callback to print progress logs and prints the final result.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/bytedance/seedream/v5/lite/text-to-image",
    arguments={
        "prompt": "Realistic DSLR photograph of anthropomorphic Penkingese dog enjoying a bowl of ramen on the Great Wall of China with the words \"Seedream 5.0 Lite available on fal\" visible at the top."
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start - Python (fal_client.subscribe)

Source: https://fal.ai/docs/model-api-reference/video-generation-api/kling-video-v2.1-standard

Python example using fal_client.subscribe to run the Kling Video V2.1 Standard image-to-video endpoint. It includes an on_queue_update callback that prints in-progress log messages, and prints the result after completion.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/kling-video/v2.1/standard/image-to-video",
    arguments={
        "prompt": "As the sun dips below the horizon, painting the sky in fiery hues of orange and purple, powerful waves relentlessly crash against jagged, dark rocks, their white foam a stark contrast to the deepening twilight; the textured surface of the rocks, wet and glistening, reflects the vibrant colors, creating a mesmerizing spectacle of nature's raw power and breathtaking beauty",
        "image_url": "https://storage.googleapis.com/falserverless/model_tests/kling/kling-image-to-video.jpg"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/flux-pro-kontext

Subscribe to the fal-ai/flux-pro/kontext model with a prompt and image URL, logging queue updates.

```Python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/flux-pro/kontext",
    arguments={
        "prompt": "Put a donut next to the flour.",
        "image_url": "https://v3.fal.media/files/rabbit/rmgBxhwGYb2d3pl3x9sKf_output.png"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start: Python

Source: https://fal.ai/docs/model-api-reference/video-generation-api/bytedance-video-stylize

Subscribe to the fal-ai/bytedance/video-stylize endpoint with a style and image URL, logging queue updates.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/bytedance/video-stylize",
    arguments={
        "style": "Manga style",
        "image_url": "https://v3.fal.media/files/kangaroo/-KmSPIcXeGA3Z_iiH4C75_tmph2ry_0_8.png"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### start()

Source: https://fal.ai/docs/documentation/serverless/distributed/api-reference

Starts all distributed worker processes and initializes them. This method must be called before using invoke() or stream(), and is typically called once in the app's setup() method.

```APIDOC
## start()

### Description
Starts all distributed worker processes and initializes them. This method must be called before using `invoke()` or `stream()`. It's typically called once in your app's `setup()` method.

### Method
async def start(self, timeout: int = 1800, **kwargs: Any) -> None

### Parameters
- **timeout** (`int`) - Optional - Maximum time (in seconds) to wait for all workers to be ready. Default: `1800` (30 minutes).
- **`**kwargs`** - Optional - Additional keyword arguments passed to each worker's `setup()` method.

### Raises
- `RuntimeError`: If processes are already running or fail to start.
- `TimeoutError`: If workers don't become ready within the timeout period.

### Example
```python
class MyApp(fal.App):
    num_gpus = 2
    
    async def setup(self):
        self.runner = DistributedRunner(
            worker_cls=MyWorker,
            world_size=self.num_gpus,
        )
        
        # Start workers and pass model path to their setup()
        await self.runner.start(model_path="/data/models/flux")
        
        # Workers are now ready to process requests
```

### What it does
1. Spawns `world_size` worker processes (one per GPU)
2. Each worker runs its `setup()` method with the provided `**kwargs`
3. Waits for all workers to signal "READY"
4. Starts the keepalive timer if configured
5. Returns when all workers are initialized and ready
```

--------------------------------

### genmedia docs

Source: https://fal.ai/docs/documentation/setting-up/genmedia

Searches the fal documentation for guides, API references, and examples.

```APIDOC
## genmedia docs

### Description
Search the fal documentation for guides, API references, and examples.

### Usage
```
genmedia docs "how to use webhooks"
```
```

--------------------------------

### Quick Start with Python

Source: https://fal.ai/docs/model-api-reference/video-generation-api/kling-video-o3-pro-reference-to-video

Subscribe to the Kling Video O3 Pro Reference To Video model using the fal_client Python library. The on_queue_update callback prints log messages while the request is in progress.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/kling-video/o3/pro/reference-to-video",
    arguments={},
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

--------------------------------

### Quick Start with JavaScript

Source: https://fal.ai/docs/model-api-reference/image-generation-api/flux-pro-kontext-multi

Subscribe to the fal-ai/flux-pro/kontext/multi model using the @fal-ai/client library. The example shows how to handle queue updates and pass a prompt with multiple image URLs.

```javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/flux-pro/kontext/multi", {
  input: {
      prompt: "Put the little duckling on top of the woman's t-shirt.",
      image_urls: [
        "https://v3.fal.media/files/penguin/XoW0qavfF-ahg-jX4BMyL_image.webp",
        "https://v3.fal.media/files/tiger/bml6YA7DWJXOigadvxk75_image.webp"
      ]
    },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);
```

--------------------------------

### search_docs

Source: https://fal.ai/docs/documentation/setting-up/mcp

Searches the fal documentation for guides, API references, and code examples.

```APIDOC
## search_docs

### Description
Search the fal documentation for guides, API references, and code examples.

### Parameters
- **query** (string) - Required - What you're looking for, e.g. `"how to upload a file"`, `"queue API"`, `"LoRA training"`
```

--------------------------------

### Quick Start: JavaScript subscribe example

Source: https://fal.ai/docs/model-api-reference/3d-api/hunyuan-3d-v3.1-part

JavaScript example using @fal-ai/client to subscribe to the endpoint, logging progress updates and printing the result data and request ID.

```javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/hunyuan-3d/v3.1/part", {
  input: {
      input_file_url: "https://v3b.fal.media/files/b/0a8bf92a/XECcItG5QHt0LViFTRCON_converted.fbx"
    },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);
```

--------------------------------

### Example app with setup, endpoint, handle_exit, and teardown

Source: https://fal.ai/docs/documentation/development/app-lifecycle

Shows a complete fal.App lifecycle example. setup() loads a model and opens a database connection. The endpoint checks self.exit on each iteration to stop early when SIGTERM arrives. handle_exit() sets the flag, and teardown() closes the database connection after the request finishes.

```python
import threading
import fal

class MyApp(fal.App):
    machine_type = "GPU-A100"

    def setup(self):
        self.model = load_model()
        self.db = connect_to_database()
        self.exit = threading.Event()

    @fal.endpoint("/")
    def run(self, input: dict) -> dict:
        for i in range(30):
            if self.exit.is_set():
                break
            result = self.model.process_step(i)
        return {"result": result}

    def handle_exit(self):
        self.exit.set()

    def teardown(self):
        self.db.close()
```

--------------------------------

### Quick Start Python

Source: https://fal.ai/docs/model-api-reference/image-generation-api/nano-banana

Python example using fal_client.subscribe to run the nano-banana/edit model with logs and queue updates. Requires the fal_client package and an API key.

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/nano-banana/edit",
    arguments={
        "prompt": "make a photo of the man driving the car down the california coastline",
        "image_urls": [
            "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png",
            "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input-2.png"
        ]
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```
Tokens:
Raw