<SYSTEM>Recipes: prebuilt multi-step video and image workflows such as product ads and ad localization</SYSTEM>

---

# Recipes

> Recipes are Runway-built endpoints with our prompting and workflow expertise packaged in — polished results like product ads and product swaps, without building or maintaining the workflow yourself. At scale.

Recipes are Runway-built endpoints with our prompting and workflow expertise packaged in. You get polished results without building or maintaining the workflow yourself.

Create product ads from a single image, swap a product into an existing video, generate on-brand campaign imagery, and more. Send a few reference inputs and a Recipe returns a finished, production-ready asset — at scale.

## When to use a Recipe

Use a **Recipe** when you want a polished result for a known use case and prefer a single call over building and maintaining the workflow yourself. Recipes package Runway’s prompting and workflow expertise — model selection, prompt engineering, and post-processing — into one endpoint, so you can generate consistent assets at scale.

Use a **base model** (see [Models](/guides/models)) when you need full control over the generation pipeline, are building a custom creative workflow, or your use case isn’t covered by an existing Recipe.

## What you can build

### Product advertising

Turn a single product photo into polished product shot videos and ad-style campaign images, ready for paid and organic channels.

### Brand-consistent imagery

Generate on-brand stock images and campaign visuals from a handful of style reference photos — no studio shoot required.

### Social and UGC content

Produce UGC-style promo videos featuring an influencer reference and your product, at the scale and pace social channels demand.

### Multi-shot storytelling

Generate multi-shot videos that cut between scenes for richer product narratives and brand spots.

## Available Recipes

[Product Ad ](/recipes/product-ad)Generate product shot videos from reference images.

[Product Swap ](/recipes/product-swap)Swap the product in a reference video for the one in a reference image.

[Product UGC ](/recipes/product-ugc)Generate UGC-style promo videos from an influencer reference and a product reference.

[Multi-Shot Video ](/recipes/multi-shot-video)Generate multi-shot videos that cut between scenes.

[Ad Localization ](/recipes/ad-localization)Localize an ad image for a target language while preserving visual creative.

[Marketing Stock Image ](/recipes/marketing-stock-image)Generate on-brand stock images from style reference photos.

[Product Campaign Image ](/recipes/product-campaign-image)Generate product ad-style campaign images.

## Get started

[Using the API ](/guides/using-the-api)How tasks work across the API — submit a request, poll for status, and retrieve your output. Recipes follow the same workflow.

[Reference media guidelines ](/recipes/reference-media)Prepare reference images and videos that produce the best results.

[API Reference ](/api)Browse every Recipe endpoint in the interactive API explorer.

---

# Ad Localization

> The Ad Localization Recipe localizes an existing ad image for a target language — preserving visual creative and layout while adapting on-screen messaging.

The **Ad Localization** Recipe localizes an existing ad image for a target language. Provide a reference ad and a `targetLanguage` code — the Recipe returns a localized version that keeps the visual creative and layout while adapting on-screen text.

## How it works

Provide a `referenceImage` of the ad to localize and a `targetLanguage` ISO-style code (for example `ja` for Japanese or `es` for Spanish). The Recipe returns a task you wait on for the localized output image.

## 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.      |
| `referenceImage` | Yes      | Reference ad image to localize, as `{ uri }`.                                                                                     |
| `targetLanguage` | Yes      | Target language code — for example `ja`, `es`, `zh`, `zh-Hant`, `fr`, `de`, `ko`, `pt`, `ar`, and others supported by the Recipe. |

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

## Example

* Node

  ```ts
  import RunwayML from '@runwayml/sdk';


  const client = new RunwayML();


  const task = await client.recipes.adLocalization({
    version: '2026-06',
    referenceImage: { uri: 'https://example.com/source-ad.jpg' },
    targetLanguage: 'ja',
  }).waitForTaskOutput();


  console.log(task);
  ```

* Python

  ```python
  from runwayml import RunwayML


  client = RunwayML()


  task = client.recipes.ad_localization(
    version='2026-06',
    reference_image={'uri': 'https://example.com/source-ad.jpg'},
    target_language='ja',
  ).wait_for_task_output()


  print(task)
  ```

* cURL

  ```sh
  curl -X POST https://api.dev.runwayml.com/v1/recipes/ad_localization \
    -d '{
      "version": "2026-06",
      "referenceImage": { "uri": "https://example.com/source-ad.jpg" },
      "targetLanguage": "ja"
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
    -H "X-Runway-Version: 2024-11-06"
  ```

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

## Tips for best results

* Use a high-resolution source ad with readable on-screen text.
* Pick the `targetLanguage` that matches the market you are localizing for — codes are ISO-style (for example `ja`, not `Japanese`).
* Source ads with clear typography and contrast localize more reliably than heavily stylized layouts.
* See [Reference media guidelines](/recipes/reference-media) for image input guidance.

## Reference

[Ad Localization API Reference ](/api#tag/Recipes/paths/~1v1~1recipes~1ad_localization/post)See the full request and response schema in the interactive explorer.

## Related

* [Marketing Stock Image](/recipes/marketing-stock-image) — on-brand stock imagery
* [Product Campaign Image](/recipes/product-campaign-image) — campaign visuals from a product photo

---

# Marketing Stock Image

> The Marketing Stock Image Recipe generates polished, on-brand marketing stock images from a text brief and an optional brand logo — with control over how many images are returned and quality vs. latency controls.

The **Marketing Stock Image** Recipe generates polished marketing stock images from a text brief. Describe the subject, audience, channel, and mood you need — and optionally supply a brand logo to guide the look — and it returns campaign-ready imagery without a photoshoot.

## How it works

Provide a `prompt` describing the marketing image you want, and optionally a brand logo as `referenceImage` to steer the result. The Recipe generates one or more finished marketing stock images and returns a task you wait on for the output.

By default, the Recipe returns **4** images at **`high`** quality. Use `outputCount` to request fewer variations (1–4), and `quality` (`low`, `medium`, or `high`) to trade off speed and cost against fidelity.

## 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.                                                   |
| `prompt`         | Yes      | Marketing image brief. Describe the subject, audience, channel, desired mood, setting, and any constraints (max 3500 characters).                                              |
| `referenceImage` | No       | Optional brand logo image to guide the result, as `{ uri }`.                                                                                                                   |
| `outputCount`    | No       | Number of images to generate, from `1` to `4`. Defaults to `4`. Each additional image adds credits at the selected `quality` tier; prompt processing is a fixed cost per call. |
| `quality`        | No       | Generation quality: `low`, `medium`, or `high`. Defaults to `high`. Lower values are faster and cheaper — see [Expected latency](#expected-latency) below.                     |

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

## Expected latency

With `outputCount` set to `1`, typical end-to-end task times look like this:

| `quality` | Typical time    |
| --------- | --------------- |
| `low`     | \~40–45 seconds |
| `medium`  | \~65–75 seconds |
| `high`    | \~3 minutes     |

Times vary with prompt complexity and system load. Higher `outputCount` values increase total task time because the Recipe generates each image separately.

## Example

* Node

  ```ts
  import RunwayML from '@runwayml/sdk';


  const client = new RunwayML();


  const task = await client.recipes.marketingStockImage({
    version: '2026-06',
    prompt: 'Premium lifestyle photo for a sustainable travel backpack campaign, urban morning commute, natural copy space on the left',
    referenceImage: { uri: 'https://example.com/brand-logo.png' },
  }).waitForTaskOutput();


  console.log(task);
  ```

* Python

  ```python
  from runwayml import RunwayML


  client = RunwayML()


  task = client.recipes.marketing_stock_image(
    version='2026-06',
    prompt='Premium lifestyle photo for a sustainable travel backpack campaign, urban morning commute, natural copy space on the left',
    reference_image={'uri': 'https://example.com/brand-logo.png'},
  ).wait_for_task_output()


  print(task)
  ```

* cURL

  ```sh
  curl -X POST https://api.dev.runwayml.com/v1/recipes/marketing_stock_image \
    -d '{
      "version": "2026-06",
      "prompt": "Premium lifestyle photo for a sustainable travel backpack campaign, urban morning commute, natural copy space on the left",
      "referenceImage": { "uri": "https://example.com/brand-logo.png" }
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
    -H "X-Runway-Version: 2024-11-06"
  ```

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

## Single image example

When you only need one option — or want a faster, lower-cost generation — set `outputCount` to `1` and choose a lower `quality`:

* Node

  ```ts
  import RunwayML from '@runwayml/sdk';


  const client = new RunwayML();


  const task = await client.recipes.marketingStockImage({
    version: '2026-06',
    prompt: 'Premium lifestyle photo for a sustainable travel backpack campaign, urban morning commute, natural copy space on the left',
    referenceImage: { uri: 'https://example.com/brand-logo.png' },
    outputCount: 1,
    quality: 'medium',
  }).waitForTaskOutput();


  console.log(task);
  ```

* Python

  ```python
  from runwayml import RunwayML


  client = RunwayML()


  task = client.recipes.marketing_stock_image(
    version='2026-06',
    prompt='Premium lifestyle photo for a sustainable travel backpack campaign, urban morning commute, natural copy space on the left',
    reference_image={'uri': 'https://example.com/brand-logo.png'},
    output_count=1,
    quality='medium',
  ).wait_for_task_output()


  print(task)
  ```

* cURL

  ```sh
  curl -X POST https://api.dev.runwayml.com/v1/recipes/marketing_stock_image \
    -d '{
      "version": "2026-06",
      "prompt": "Premium lifestyle photo for a sustainable travel backpack campaign, urban morning commute, natural copy space on the left",
      "referenceImage": { "uri": "https://example.com/brand-logo.png" },
      "outputCount": 1,
      "quality": "medium"
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
    -H "X-Runway-Version: 2024-11-06"
  ```

## Tips for best results

* Be specific in the brief — name the subject, audience, channel, mood, and setting, and call out any composition needs like copy space.
* Supply a brand logo as `referenceImage` when you need the output to align with your brand.
* Omit `outputCount` and `quality` for the default set of four high-quality variations; lower either when you want faster iterations or lower cost per call.
* Generate a few variations and curate, the same way you’d select from a stock library.
* See [Reference media guidelines](/recipes/reference-media) for more.

## Reference

[Marketing Stock Image API Reference ](/api#tag/Recipes/paths/~1v1~1recipes~1marketing_stock_image/post)See the full request and response schema in the interactive explorer.

## Related

* [Product Campaign Image](/recipes/product-campaign-image) — product-focused campaign visuals
* [Product Ad](/recipes/product-ad) — product shot videos

---

# Multi-Shot Video

> The Multi-Shot Video Recipe generates videos that cut between multiple shots, reusing Runway's multi-shot workflow to tell richer product and brand stories.

The **Multi-Shot Video** Recipe generates videos composed of multiple shots that cut between scenes, reusing Runway’s multi-shot workflow. Use it when a single continuous take isn’t enough — product narratives, brand spots, and sequences that need variety and pacing.

## How it works

Choose a mode. In **auto** mode, you provide a single story prompt and the Recipe decomposes it into a set of shots for you. In **custom** mode, you provide your own shot list of 3–5 shots and the Recipe polishes and assembles them. Either way, the Recipe returns a task you wait on for the finished output.

## Inputs

| Input        | Required    | Description                                                                                                                                                                              |
| ------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`       | Yes         | `auto` decomposes a story prompt into shots; `custom` polishes a shot list you provide.                                                                                                  |
| `version`    | Yes         | Workflow version. Use a dated version like `2026-06` to pin behavior, or `unsafe-latest` to track the newest stable version.                                                             |
| `prompt`     | auto only   | Story prompt to decompose into shots (max 2500 characters).                                                                                                                              |
| `shots`      | custom only | An ordered list of 3–5 shots, each with a `prompt` (3–512 characters) and a `duration` in seconds. Per-shot durations must sum to `duration`.                                            |
| `firstFrame` | No          | Optional image used as the first frame of the output video, as `{ uri }`.                                                                                                                |
| `ratio`      | No          | Output dimensions. 720p ratios (`1280:720`, `720:1280`, `960:960`) use the standard tier; 1080p ratios (`1920:1080`, `1080:1920`, `1440:1440`) use the pro tier. Defaults to `1280:720`. |
| `duration`   | No          | Total output length in seconds: `5`, `10`, or `15`. Defaults to 10.                                                                                                                      |
| `audio`      | No          | Whether to generate audio. Defaults to `true`.                                                                                                                                           |

## Example

Auto mode decomposes a single story prompt into shots:

* Node

  ```ts
  import RunwayML from '@runwayml/sdk';


  const client = new RunwayML();


  const task = await client.recipes.multiShotVideo({
    version: '2026-06',
    mode: 'auto',
    prompt: 'A lone astronaut discovers a glowing forest on a distant planet',
    duration: 10,
    ratio: '1280:720',
  }).waitForTaskOutput();


  console.log(task);
  ```

* Python

  ```python
  from runwayml import RunwayML


  client = RunwayML()


  task = client.recipes.multi_shot_video(
    version='2026-06',
    mode='auto',
    prompt='A lone astronaut discovers a glowing forest on a distant planet',
    duration=10,
    ratio='1280:720',
  ).wait_for_task_output()


  print(task)
  ```

* cURL

  ```sh
  curl -X POST https://api.dev.runwayml.com/v1/recipes/multi_shot_video \
    -d '{
      "version": "2026-06",
      "mode": "auto",
      "prompt": "A lone astronaut discovers a glowing forest on a distant planet",
      "duration": 10,
      "ratio": "1280:720"
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
    -H "X-Runway-Version: 2024-11-06"
  ```

Custom mode polishes and assembles a shot list you provide. Per-shot durations must sum to `duration`:

* Node

  ```ts
  import RunwayML from '@runwayml/sdk';


  const client = new RunwayML();


  const task = await client.recipes.multiShotVideo({
    version: '2026-06',
    mode: 'custom',
    duration: 10,
    ratio: '1280:720',
    shots: [
      { prompt: 'Wide establishing shot of the product on a kitchen counter at sunrise', duration: 3 },
      { prompt: 'Close-up of a hand picking up the product', duration: 3 },
      { prompt: 'Product hero shot rotating against a clean background', duration: 4 },
    ],
  }).waitForTaskOutput();


  console.log(task);
  ```

* Python

  ```python
  from runwayml import RunwayML


  client = RunwayML()


  task = client.recipes.multi_shot_video(
    version='2026-06',
    mode='custom',
    duration=10,
    ratio='1280:720',
    shots=[
      {'prompt': 'Wide establishing shot of the product on a kitchen counter at sunrise', 'duration': 3},
      {'prompt': 'Close-up of a hand picking up the product', 'duration': 3},
      {'prompt': 'Product hero shot rotating against a clean background', 'duration': 4},
    ],
  ).wait_for_task_output()


  print(task)
  ```

* cURL

  ```sh
  curl -X POST https://api.dev.runwayml.com/v1/recipes/multi_shot_video \
    -d '{
      "version": "2026-06",
      "mode": "custom",
      "duration": 10,
      "ratio": "1280:720",
      "shots": [
        { "prompt": "Wide establishing shot of the product on a kitchen counter at sunrise", "duration": 3 },
        { "prompt": "Close-up of a hand picking up the product", "duration": 3 },
        { "prompt": "Product hero shot rotating against a clean background", "duration": 4 }
      ]
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
    -H "X-Runway-Version: 2024-11-06"
  ```

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

* Write one clear idea per shot — keep each shot’s prompt focused on a single scene.
* In custom mode, order shots the way you want them to play; the Recipe preserves sequence.
* In custom mode, make sure each shot’s `duration` adds up to the total `duration`.
* Reuse the same product or style language across shots for visual consistency.
* See [Reference media guidelines](/recipes/reference-media) for more.

## Reference

[Multi-Shot Video API Reference ](/api#tag/Recipes/paths/~1v1~1recipes~1multi_shot_video/post)See the full request and response schema in the interactive explorer.

## Related

* [Product Ad](/recipes/product-ad)
* [Product Swap](/recipes/product-swap)

---

# Product Ad

> The Product Ad Recipe generates cinematic product ad videos from reference images of your product, optional style references, and creative direction.

The **Product Ad** Recipe turns reference images of your product into a polished, cinematic product ad video. Provide one or more product photos, optional style references, and creative direction, and the Recipe returns ad-ready motion you can drop into paid and organic channels.

## How it works

Submit one or more product images, then guide the result with optional style references, `productInfo`, and a `userConcept` describing the creative direction. The Recipe analyzes the product, builds a storyboard, and renders a short video. It returns a task you wait on for the finished output.

## Inputs

| Input           | Required | Description                                                                                                                                              |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`       | Yes      | Workflow version. Pin to `2026-07` (current public version) or `2026-06`. Use `unsafe-latest` to track the newest stable version.                        |
| `productImages` | Yes      | One to ten reference images of the product as `{ uri }` objects, ideally from multiple angles. The first image is used as the primary product reference. |
| `styleImages`   | No       | Up to four style reference images (`{ uri }`) defining lighting, palette, and mood. Treated as a moodboard when multiple are provided.                   |
| `productInfo`   | No       | Product description and specifications to inform creative direction (max 2500 characters).                                                               |
| `userConcept`   | No       | Creative direction — brand voice, scene specifics, lighting, camera motion, and narrative (max 3500 characters).                                         |
| `ratio`         | No       | Output aspect ratio: `1280:720`, `720:1280`, `960:960`, `834:1112`, `1920:1080`, `1080:1920`, `1440:1440`, or `1248:1664`.                               |
| `duration`      | No       | Output length in seconds (4–15). Defaults to 10.                                                                                                         |
| `audio`         | No       | Whether to generate audio. Defaults to `false`.                                                                                                          |

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

## Example

* Node

  ```ts
  import RunwayML from '@runwayml/sdk';


  const client = new RunwayML();


  const task = await client.recipes.productAd({
    version: '2026-07',
    productImages: [
      { uri: 'https://example.com/product-front.jpg' },
      { uri: 'https://example.com/product-side.jpg' },
    ],
    productInfo: 'Organic cold-pressed juice, 12oz glass bottle',
    userConcept: 'Bright, refreshing summer campaign with slow dolly moves',
    duration: 10,
  }).waitForTaskOutput();


  console.log(task);
  ```

* Python

  ```python
  from runwayml import RunwayML


  client = RunwayML()


  task = client.recipes.product_ad(
    version='2026-07',
    product_images=[
      {'uri': 'https://example.com/product-front.jpg'},
      {'uri': 'https://example.com/product-side.jpg'},
    ],
    product_info='Organic cold-pressed juice, 12oz glass bottle',
    user_concept='Bright, refreshing summer campaign with slow dolly moves',
    duration=10,
  ).wait_for_task_output()


  print(task)
  ```

* cURL

  ```sh
  curl -X POST https://api.dev.runwayml.com/v1/recipes/product_ad \
    -d '{
      "version": "2026-07",
      "productImages": [
        { "uri": "https://example.com/product-front.jpg" },
        { "uri": "https://example.com/product-side.jpg" }
      ],
      "productInfo": "Organic cold-pressed juice, 12oz glass bottle",
      "userConcept": "Bright, refreshing summer campaign with slow dolly moves",
      "duration": 10
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
    -H "X-Runway-Version: 2024-11-06"
  ```

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

* **Show the product from multiple angles.** Supply reference images of the product from multiple angles — front, back, and sides — so the model can depict it accurately and consistently throughout the video.
* Use high-resolution product photos with the product clearly isolated from its background.
* Keep the product centered and unobstructed; avoid busy backgrounds in the reference.
* Use `userConcept` to describe the scene and direction — let the product images define what the product looks like.
* See [Reference media guidelines](/recipes/reference-media) for more.

## Reference

[Product Ad API Reference ](/api#tag/Recipes/paths/~1v1~1recipes~1product_ad/post)See the full request and response schema in the interactive explorer.

## Related

* [Product Campaign Image](/recipes/product-campaign-image) — still campaign images instead of video
* [Product UGC](/recipes/product-ugc) — influencer-style promo videos

---

# Product Campaign Image

> The Product Campaign Image Recipe generates four fashion campaign images from a product image and a style brief — hero visuals ready for placements.

The **Product Campaign Image** Recipe generates four fashion campaign images from a single product image and a style brief. It produces polished, hero-style visuals — while preserving your product across each image — that you can use across landing pages, ads, and social placements.

## How it works

Provide a product image to preserve across the campaign and a `prompt` describing the creative direction. The Recipe generates four on-brand campaign images and returns a task you wait on for the 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.          |
| `image`   | Yes      | Product image to preserve across the generated campaign, as `{ uri }`.                                                                |
| `prompt`  | Yes      | Style / creative brief for the campaign, e.g. “High-key fashion editorial, gorpcore-meets-blokecore-meets-Y2K” (max 3500 characters). |

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

## Example

* Node

  ```ts
  import RunwayML from '@runwayml/sdk';


  const client = new RunwayML();


  const task = await client.recipes.productCampaignImage({
    version: '2026-06',
    image: { uri: 'https://example.com/product.jpg' },
    prompt: 'High-key fashion editorial, gorpcore-meets-blokecore-meets-Y2K',
  }).waitForTaskOutput();


  console.log(task);
  ```

* Python

  ```python
  from runwayml import RunwayML


  client = RunwayML()


  task = client.recipes.product_campaign_image(
    version='2026-06',
    image={'uri': 'https://example.com/product.jpg'},
    prompt='High-key fashion editorial, gorpcore-meets-blokecore-meets-Y2K',
  ).wait_for_task_output()


  print(task)
  ```

* cURL

  ```sh
  curl -X POST https://api.dev.runwayml.com/v1/recipes/product_campaign_image \
    -d '{
      "version": "2026-06",
      "image": { "uri": "https://example.com/product.jpg" },
      "prompt": "High-key fashion editorial, gorpcore-meets-blokecore-meets-Y2K"
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
    -H "X-Runway-Version: 2024-11-06"
  ```

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

## Tips for best results

* Use a high-resolution product photo with the product cleanly isolated from its background.
* Be specific in the brief — name the aesthetic, styling, and mood you want the campaign to convey.
* Generate a set and curate; the Recipe returns four variations to choose from.
* See [Reference media guidelines](/recipes/reference-media) for more.

## Reference

[Product Campaign Image API Reference ](/api#tag/Recipes/paths/~1v1~1recipes~1product_campaign_image/post)See the full request and response schema in the interactive explorer.

## Related

* [Product Ad](/recipes/product-ad) — the video counterpart
* [Marketing Stock Image](/recipes/marketing-stock-image) — brand stock imagery

---

# Product Swap

> 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

* Node

  ```ts
  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);
  ```

* Python

  ```python
  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)
  ```

* 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"
  ```

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

[Product Swap API Reference ](/api#tag/Recipes/paths/~1v1~1recipes~1product_swap/post)See the full request and response schema in the interactive explorer.

## Related

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

---

# Product UGC

> The Product UGC Recipe generates UGC-style promo videos from a reference image of a creator and a reference image of the product they promote.

The **Product UGC** Recipe generates vertical, user-generated-content–style promo videos. Provide a reference image of the on-camera creator and a reference image of the product, and the Recipe produces an authentic, social-ready clip of the creator promoting the product.

## How it works

Submit a character image (the person presenting) and a product image, plus optional `productInfo` and `userConcept` to steer the script and tone. The Recipe generates a UGC-style video in the casual, handheld aesthetic that performs well on social channels. 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.            |
| `characterImage` | Yes      | Image of the creator who appears on camera, as `{ uri }`. Aspect ratio (width / height) must be between 0.4 and 4.                      |
| `productImage`   | Yes      | Image of the product being promoted, as `{ uri }`. Aspect ratio (width / height) must be between 0.4 and 4.                             |
| `productInfo`    | No       | Product details and creative brief — what the product is, key benefits, and anything the script should reference (max 2500 characters). |
| `userConcept`    | No       | Creative direction — tone, voice register, a specific message, or an entire dialog script (max 3500 characters).                        |
| `duration`       | No       | Output length in seconds (4–15). Defaults to 15.                                                                                        |
| `ratio`          | No       | Output aspect ratio: `720:1280` or `1080:1920`.                                                                                         |
| `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

* Node

  ```ts
  import RunwayML from '@runwayml/sdk';


  const client = new RunwayML();


  const task = await client.recipes.productUgc({
    version: '2026-06',
    characterImage: { uri: 'https://example.com/creator.jpg' },
    productImage: { uri: 'https://example.com/product.jpg' },
    productInfo: 'Wireless game controller with haptic feedback triggers',
    userConcept: 'Enthusiastic creator tone, demonstrate the product in hand',
    duration: 15,
  }).waitForTaskOutput();


  console.log(task);
  ```

* Python

  ```python
  from runwayml import RunwayML


  client = RunwayML()


  task = client.recipes.product_ugc(
    version='2026-06',
    character_image={'uri': 'https://example.com/creator.jpg'},
    product_image={'uri': 'https://example.com/product.jpg'},
    product_info='Wireless game controller with haptic feedback triggers',
    user_concept='Enthusiastic creator tone, demonstrate the product in hand',
    duration=15,
  ).wait_for_task_output()


  print(task)
  ```

* cURL

  ```sh
  curl -X POST https://api.dev.runwayml.com/v1/recipes/product_ugc \
    -d '{
      "version": "2026-06",
      "characterImage": { "uri": "https://example.com/creator.jpg" },
      "productImage": { "uri": "https://example.com/product.jpg" },
      "productInfo": "Wireless game controller with haptic feedback triggers",
      "userConcept": "Enthusiastic creator tone, demonstrate the product in hand",
      "duration": 15
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
    -H "X-Runway-Version: 2024-11-06"
  ```

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

* Use a clear, well-lit reference of the creator with the face visible and unobstructed.
* Provide a clean product image so the product reads clearly when the creator presents it.
* Use `userConcept` to set the tone or supply a full script when you need specific messaging.
* Make sure you have the rights and consent to use any person’s likeness as a reference.
* See [Reference media guidelines](/recipes/reference-media) for more.

## Reference

[Product UGC API Reference ](/api#tag/Recipes/paths/~1v1~1recipes~1product_ugc/post)See the full request and response schema in the interactive explorer.

## Related

* [Product Ad](/recipes/product-ad) — product shot videos without a creator
* [Multi-Shot Video](/recipes/multi-shot-video)

---

# Reference media guidelines

> Recipes are only as good as the reference images and videos you feed them. Follow these guidelines to capture product, style, and talent references that produce the best results.

Every Recipe is driven by **reference media** — the images and videos that anchor the output to your product, brand, or talent. Strong references are the single biggest lever on output quality. This page covers how to prepare each type.

For accepted file formats, sizes, and limits, see [Inputs](/assets/inputs). For how to pass references as URLs or base64 data URIs, see [Using the API](/guides/using-the-api#uploading-base64-encoded-images-as-data-uris).

## General principles

* **Resolution** — use the highest-quality source you have. Low-resolution or heavily compressed references degrade the output.
* **Isolation** — the subject of a reference should be clearly the focus, free of clutter and distractions.
* **Lighting** — even, neutral lighting reproduces most faithfully. Harsh shadows and color casts can carry into the result.
* **One subject per reference** — avoid references with multiple competing subjects unless the Recipe specifically calls for it.

## Product images

Used by [Product Ad](/recipes/product-ad), [Product Swap](/recipes/product-swap), [Product Campaign Image](/recipes/product-campaign-image), and [Product UGC](/recipes/product-ugc).

* Center the product and keep it unobstructed.
* Prefer a clean or plain background so the product is easy to isolate.
* Capture the angle you want featured; the Recipe works from what it can see.
* Avoid heavy reflections, watermarks, or overlaid text on the product.

## Style reference images

Used by [Marketing Stock Image](/recipes/marketing-stock-image) and [Product Campaign Image](/recipes/product-campaign-image).

* Choose references that share a consistent palette, lighting, and mood.
* Provide a few complementary images rather than one — a small, cohesive set defines the style more reliably.
* Don’t mix conflicting aesthetics in a single request; generate separately and curate.

## Talent and influencer references

Used by [Product UGC](/recipes/product-ugc).

* Use a clear, well-lit reference with the face visible and unobstructed.
* Choose a neutral expression and framing unless you want a specific look carried through.
* **Rights and consent**: only use references of people you have permission to depict. You are responsible for the rights to any likeness you submit. See [Content moderation](/api-details/moderation) for usage policies.

## Reference videos

Used by [Product Swap](/recipes/product-swap) and [Multi-Shot Video](/recipes/multi-shot-video).

* Pick a source video where the subject is clearly visible and consistently framed.
* Stable footage with steady motion produces cleaner results than shaky or rapidly cut clips.
* For Product Swap, match the new product’s category and rough shape to the one in the video for the most natural swap.

## Next steps

[Inputs ](/assets/inputs)Accepted file types, sizes, and upload limits.

[Browse all Recipes ](/recipes)See the full set of Recipes and their specific inputs.