# Scene Finder

> Search any video with a text prompt - Scene Finder locates the matching moments and returns their time segments and extracted frames.


## Overview

- **Endpoint**: `https://fal.run/fal-ai/scene-finder`
- **Model ID**: `fal-ai/scene-finder`
- **Category**: vision
- **Kind**: inference
**Tags**: video, scene detection, video search, moment retrieval, vision, video understanding



## Pricing

 Scene Finder is billed by the length of the input video — $0.0042 per second of input video.

For more details, see [fal.ai pricing](https://fal.ai/pricing).

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.


### Input Schema

The API accepts the following input parameters:


- **`video_url`** (`string`, _required_):
  URL of the video to search through.
  - Examples: "https://v3b.fal.media/files/b/0a913346/ZbEaRKcU1dMNYkHl9g1Zz_T4QEyOJ3R3WzuQS9.mp4"

- **`prompt`** (`string`, _required_):
  Text description of the event or scene to find in the video.
  - Examples: "a dog with only one eye open", "blonde woman with her bag"

- **`frames_per_second`** (`integer`, _optional_):
  Frames per second to sample from the video. Higher values give more precision but use more memory. Default value: `2`
  - Default: `2`
  - Range: `1` to `8`

- **`frame_selection`** (`FrameSelectionEnum`, _optional_):
  Which frame(s) to extract from each detected segment. 'mid' returns the midpoint frame, 'start' the first frame, 'end' the last frame, 'all' returns start + mid + end. Default value: `"mid"`
  - Default: `"mid"`
  - Options: `"mid"`, `"start"`, `"end"`, `"all"`



**Required Parameters Example**:

```json
{
  "video_url": "https://v3b.fal.media/files/b/0a913346/ZbEaRKcU1dMNYkHl9g1Zz_T4QEyOJ3R3WzuQS9.mp4",
  "prompt": "a dog with only one eye open"
}
```

**Full Example**:

```json
{
  "video_url": "https://v3b.fal.media/files/b/0a913346/ZbEaRKcU1dMNYkHl9g1Zz_T4QEyOJ3R3WzuQS9.mp4",
  "prompt": "a dog with only one eye open",
  "frames_per_second": 2,
  "frame_selection": "mid"
}
```


### Output Schema

The API returns the following output format:

- **`segments`** (`list<EventSegment>`, _required_):
  Detected event time segments.
  - Array of EventSegment
  - Examples: [{"start":10.4,"end":12.5}]

- **`images`** (`list<Image>`, _required_):
  Extracted frames from each detected segment based on frame_selection.
  - Array of Image



**Example Response**:

```json
{
  "segments": [
    {
      "start": 10.4,
      "end": 12.5
    }
  ],
  "images": [
    {
      "url": "",
      "content_type": "image/png",
      "file_name": "z9RV14K95DvU.png",
      "file_size": 4404019,
      "width": 1024,
      "height": 1024
    }
  ]
}
```


## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://fal.run/fal-ai/scene-finder \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
     "video_url": "https://v3b.fal.media/files/b/0a913346/ZbEaRKcU1dMNYkHl9g1Zz_T4QEyOJ3R3WzuQS9.mp4",
     "prompt": "a dog with only one eye open"
   }'
```

### Python

Ensure you have the Python client installed:

```bash
pip install fal-client
```

Then use the API client to make requests:

```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/scene-finder",
    arguments={
        "video_url": "https://v3b.fal.media/files/b/0a913346/ZbEaRKcU1dMNYkHl9g1Zz_T4QEyOJ3R3WzuQS9.mp4",
        "prompt": "a dog with only one eye open"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

### JavaScript

Ensure you have the JavaScript client installed:

```bash
npm install --save @fal-ai/client
```

Then use the API client to make requests:

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

const result = await fal.subscribe("fal-ai/scene-finder", {
  input: {
    video_url: "https://v3b.fal.media/files/b/0a913346/ZbEaRKcU1dMNYkHl9g1Zz_T4QEyOJ3R3WzuQS9.mp4",
    prompt: "a dog with only one eye open"
  },
  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);
```


## Additional Resources

### Documentation

- [Model Playground](https://fal.ai/models/fal-ai/scene-finder)
- [API Documentation](https://fal.ai/models/fal-ai/scene-finder/api)
- [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/scene-finder)

### fal.ai Platform

- [Platform Documentation](https://docs.fal.ai)
- [Python Client](https://docs.fal.ai/clients/python)
- [JavaScript Client](https://docs.fal.ai/clients/javascript)