Product Swap

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 id you poll 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.

Example

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,
});

console.log(task);

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,
)

print(task)

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"

The recipe returns a task id. Poll GET /v1/tasks/{id} for status and the output video URL — see Using the API for the task workflow.

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 for more.

Reference

Product Swap API Reference See the full request and response schema in the interactive explorer.

Product Ad — generate a product video from scratch
Multi-Shot Video