---
title: Product Swap
description: The Product Swap Recipe takes a reference video and reference images and swaps the product in the video for a new one — reuse a winning ad with a new product.
---

The **Product Swap** Recipe takes a reference video and replaces the product featured in it with a new product, preserving the original camera motion, lighting, and scene composition. It's the fastest way to reuse a proven ad or template across a catalog of products.

# How it works

Provide a reference video that already shows a product in action, an image of the original product being swapped out, and reference images of the new product. The Recipe swaps the product while preserving the original motion, framing, and scene. It returns a task you wait on for the finished output.

# Inputs

| Input | Required | Description |
| --- | --- | --- |
| `version` | Yes | Workflow version. Use a dated version like `2026-06` to pin behavior, or `unsafe-latest` to track the newest stable version. |
| `referenceVideo` | Yes | Reference video containing the product to swap, as `{ uri }`. Duration must be between 1.8 and 15 seconds. |
| `originalProductImage` | Yes | Image of the original product being swapped out, as `{ uri }`. |
| `newProductImages` | Yes | One to ten reference images of the new product. Each is `{ uri }` with an optional `view` of `front`, `side`, or `back`. A single pre-composed reference sheet is also supported (omit `view`). |
| `duration` | No | Output length in seconds (4–15). Defaults to 10. |
| `resolution` | No | Output resolution: `720p` or `1080p`. Defaults to `720p`. |
| `audio` | No | Whether to generate audio. Defaults to `true`. |

`uri` accepts an HTTPS URL, a Runway upload URI, or a [data URI](/assets/inputs#images).

# Example

<Tabs syncKey="language">
  <TabItem label="Node">
    <Code code={codeSample`
    import RunwayML from '@runwayml/sdk';

```
const client = new RunwayML();

const task = await client.recipes.productSwap({
  version: '2026-06',
  referenceVideo: { uri: 'https://example.com/reference-ad.mp4' },
  originalProductImage: { uri: 'https://example.com/original-product.jpg' },
  newProductImages: [
    { uri: 'https://example.com/new-product-front.jpg', view: 'front' },
    { uri: 'https://example.com/new-product-side.jpg', view: 'side' },
  ],
  duration: 10,
}).waitForTaskOutput();

console.log(task);
`.trim()} lang="ts" />
```

  </TabItem>
  <TabItem label="Python">
    <Code code={codeSample`
    from runwayml import RunwayML

```
client = RunwayML()

task = client.recipes.product_swap(
  version='2026-06',
  reference_video={'uri': 'https://example.com/reference-ad.mp4'},
  original_product_image={'uri': 'https://example.com/original-product.jpg'},
  new_product_images=[
    {'uri': 'https://example.com/new-product-front.jpg', 'view': 'front'},
    {'uri': 'https://example.com/new-product-side.jpg', 'view': 'side'},
  ],
  duration=10,
).wait_for_task_output()

print(task)
`.trim()} lang="python" />
```

  </TabItem>
  <TabItem label="cURL">
    ```sh
    curl -X POST https://api.dev.runwayml.com/v1/recipes/product_swap \
      -d '{
        "version": "2026-06",
        "referenceVideo": { "uri": "https://example.com/reference-ad.mp4" },
        "originalProductImage": { "uri": "https://example.com/original-product.jpg" },
        "newProductImages": [
          { "uri": "https://example.com/new-product-front.jpg", "view": "front" },
          { "uri": "https://example.com/new-product-side.jpg", "view": "side" }
        ],
        "duration": 10
      }' \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
      -H "X-Runway-Version: 2024-11-06"
    ```
  </TabItem>
</Tabs>

The SDK examples wait for the finished output. With cURL, poll `GET /v1/tasks/{id}` for status and the output video URL — see [Using the API](/guides/using-the-api).

# Tips for best results

* **Best for like-for-like swaps.** Product Swap works best when the new product fits the same context as the original — for example, swapping one style of water bottle for another in the same video. Swaps struggle when the reference video shows an action the new product wouldn't perform, like replacing a water bottle someone is drinking from with a hairbrush.
* **Match the new product's reference angles to the video.** When the reference video shows the product from different views, supply multiple `newProductImages` and label each with its `view` (`front`, `side`, or `back`) so the model can depict the product accurately throughout.
* Choose a reference video where the product is clearly visible and consistently framed.
* Match the new product's category and rough shape to the one in the video for the most natural swap.
* Use clean, well-lit product images with the product isolated from its background.
* See [Reference media guidelines](/recipes/reference-media) for more.

# Reference

<LinkCard
title="Product Swap API Reference"
description="See the full request and response schema in the interactive explorer."
href="/api#tag/Recipes/paths/~1v1~1recipes~1product_swap/post"
/>

# Related

* [Product Ad](/recipes/product-ad) — generate a product video from scratch
* [Multi-Shot Video](/recipes/multi-shot-video)