# ID-V2V

> Restyle a video’s scene, lighting, and visual style from edited keyframes while preserving the source subjects’ identity, expressions, gaze, and motion. Developed by Eyeline Labs and Netflix researchers.


## Overview

- **Endpoint**: `https://fal.run/fal-ai/id-v2v`
- **Model ID**: `fal-ai/id-v2v`
- **Category**: video-to-video
- **Kind**: inference
**Description**: ID-V2V is an identity-preserving video restylization model developed by researchers at Eyeline Labs and Netflix. It uses edited keyframes to guide scene, lighting, and style changes while retaining the source subjects’ likeness and performance.

Provide a source video, a restyled first-frame image, and a text prompt. Optional additional keyframes guide the appearance at chosen frame indices. The source video anchors identity, expressions, gaze, and motion; the edited frames guide the new visual treatment.

The released model builds on Wan 2.1 with VACE control. The default variant uses SAM3 subject segmentation. This fal endpoint exposes 480p and 720p output and optional keyframe controls. Dedicated video relighting is available through fal-ai/id-v2v/relight.

Project: https://eyeline-labs.github.io/ID-V2V/
Code: https://github.com/Eyeline-Labs/ID-V2V
Weights: https://huggingface.co/Eyeline-Labs/ID-V2V
License: Apache-2.0.

**Tags**: stylized, transform, editing



## Pricing

- **Price**: $0.2 per seconds

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:


- **`prompt`** (`string`, _required_):
  The prompt describing the restyled video to generate.
  - Examples: "An astronaut walking through an autumn forest"

- **`video_url`** (`string`, _required_):
  URL of the source video whose motion and framing drive the generation.
  - Examples: "https://storage.googleapis.com/falserverless/model_tests/video_models/mmaudio_input.mp4"

- **`image_url`** (`string`, _required_):
  URL of the restyled first frame. The video is regenerated in this frame's identity/style.
  - Examples: "https://storage.googleapis.com/falserverless/example_inputs/ltxv-image-input.jpg"

- **`keyframes`** (`list<Keyframe>`, _optional_):
  Optional restyled keyframes pinned at specific output frame indices to anchor identity over long videos.
  - Array of Keyframe

- **`resolution`** (`ResolutionEnum`, _optional_):
  Output resolution tier. Orientation follows the source video (720p is 1280x720 or 720x1280; 480p is 832x480 or 480x832). Default value: `"720p"`
  - Default: `"720p"`
  - Options: `"480p"`, `"720p"`

- **`num_frames`** (`integer`, _optional_):
  Maximum number of output frames. Capped at the source video's frame count. Default value: `81`
  - Default: `81`
  - Range: `17` to `241`

- **`segmentation_prompt`** (`string`, _optional_):
  Text prompt for SAM-3 subject segmentation. The segmented subject's pixels condition the generation; the rest of the frame is regenerated freely. Default value: `"person"`
  - Default: `"person"`
  - Examples: "person"

- **`num_inference_steps`** (`integer`, _optional_):
  Number of diffusion sampling steps per clip. Higher improves quality but is slower. Default value: `30`
  - Default: `30`
  - Range: `2` to `40`

- **`guidance_scale`** (`float`, _optional_):
  Classifier-free guidance scale. Controls prompt adherence versus creativity. Default value: `5`
  - Default: `5`
  - Range: `1` to `10`

- **`vace_scale`** (`float`, _optional_):
  VACE conditioning scale. Controls how strongly the source video's structure constrains the generation. Default value: `1`
  - Default: `1`
  - Range: `0` to `2`

- **`seed`** (`integer`, _optional_):
  Random seed for reproducibility. The same seed is used for every clip of a multi-clip generation.

- **`enable_safety_checker`** (`boolean`, _optional_):
  Enable safety checking of inputs and outputs. Default value: `true`
  - Default: `true`



**Required Parameters Example**:

```json
{
  "prompt": "An astronaut walking through an autumn forest",
  "video_url": "https://storage.googleapis.com/falserverless/model_tests/video_models/mmaudio_input.mp4",
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/ltxv-image-input.jpg"
}
```

**Full Example**:

```json
{
  "prompt": "An astronaut walking through an autumn forest",
  "video_url": "https://storage.googleapis.com/falserverless/model_tests/video_models/mmaudio_input.mp4",
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/ltxv-image-input.jpg",
  "keyframes": [
    {
      "image_url": "https://storage.googleapis.com/falserverless/example_inputs/ltxv-image-input.jpg",
      "frame_index": 80
    }
  ],
  "resolution": "720p",
  "num_frames": 81,
  "segmentation_prompt": "person",
  "num_inference_steps": 30,
  "guidance_scale": 5,
  "vace_scale": 1,
  "enable_safety_checker": true
}
```


### Output Schema

The API returns the following output format:

- **`video`** (`File`, _required_):
  The generated video file.
  - Examples: {"file_size":1048576,"url":"https://storage.googleapis.com/falserverless/example_outputs/scail2-output.mp4","content_type":"video/mp4","file_name":"output.mp4"}

- **`seed`** (`integer`, _required_):
  The seed used for generation.



**Example Response**:

```json
{
  "video": {
    "file_size": 1048576,
    "url": "https://storage.googleapis.com/falserverless/example_outputs/scail2-output.mp4",
    "content_type": "video/mp4",
    "file_name": "output.mp4"
  }
}
```


## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://fal.run/fal-ai/id-v2v \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
     "prompt": "An astronaut walking through an autumn forest",
     "video_url": "https://storage.googleapis.com/falserverless/model_tests/video_models/mmaudio_input.mp4",
     "image_url": "https://storage.googleapis.com/falserverless/example_inputs/ltxv-image-input.jpg"
   }'
```

### 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/id-v2v",
    arguments={
        "prompt": "An astronaut walking through an autumn forest",
        "video_url": "https://storage.googleapis.com/falserverless/model_tests/video_models/mmaudio_input.mp4",
        "image_url": "https://storage.googleapis.com/falserverless/example_inputs/ltxv-image-input.jpg"
    },
    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/id-v2v", {
  input: {
    prompt: "An astronaut walking through an autumn forest",
    video_url: "https://storage.googleapis.com/falserverless/model_tests/video_models/mmaudio_input.mp4",
    image_url: "https://storage.googleapis.com/falserverless/example_inputs/ltxv-image-input.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);
```


## Additional Resources

### Documentation

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

### fal.ai Platform

- [Platform Documentation](https://fal.ai/docs/documentation)
- [Python Client](https://fal.ai/docs/api-reference/client-libraries/python)
- [JavaScript Client](https://fal.ai/docs/api-reference/client-libraries/javascript)

### Other agent-readable surfaces

This file covers one model. To find anything else:

- [Platform overview](https://fal.ai/llms.txt): Entry points and representative endpoint IDs
- [Documentation index](https://fal.ai/docs/llms.txt): Every documentation page
- [Full documentation text](https://fal.ai/docs/llms-full.txt): The whole documentation inlined
- Any other model: `https://fal.ai/models/<endpoint-id>/llms.txt`