Trying to change only the background can erase the parts that already worked

Sometimes you like the hand movement and camera motion in a product demo, but want only the background to be brighter. Generating the video again from scratch can also change the product position and speed, and even when the logo appears. Even if the edited version performs better, it becomes hard to explain what caused it.

Ray 3.2's video_edit takes an existing video as its source and re-renders the entire clip according to a natural-language instruction. It does not replace selected pixels or a single scene like a traditional editor, but it can reuse the original motion as a condition, allowing you to build an editing loop that changes only the background while keeping validated motion as the baseline.

The goal is not to get a finished version in one pass. It is to inspect the full clip to see whether only the desired element changed, then compare the original only with edits that pass quality review.

Run your first edit with a 5-second clip

For the first run, follow Luma Agents' official Video editing guide. You need a Luma developer account and API key, available billing capacity, Python 3.9 or later, and an externally accessible MP4 URL. The official Python SDK requires Python 3.9 or later.

When using a public URL or inline data as a source, the file must be 200 MB or smaller and the video must be 18 seconds or shorter. The URL must be externally accessible and provide a video MIME type such as video/mp4. Since 18 seconds is the maximum allowed length, start your first check with a 5-second clip that you can review quickly.

  1. Check your Python version and install the SDK. In a macOS or Linux terminal, run python3 --version below to confirm that it is 3.9 or later, then install luma-agents in that same environment.
  2. Create an account and generate an API key on the Luma developer platform. After signing in, issue a key in the developer dashboard and set it as the LUMA_AGENTS_API_KEY environment variable in that same terminal session. Luma() reads this value during initialization and raises an error if it is missing. Do not put the key directly in a Python file or shared document.
  3. Save the Python code below as edit_video.py. Replace the example.com address with your own externally accessible MP4 URL. The prompt specifies one variable only: change the background while preserving the package color, texture, shape, logo, camera motion, and hand movement.
  4. In the same terminal where you set the API key, run python3 edit_video.py. The script submits a job and polls its status until it becomes completed or failed. If it has not finished after about 10 minutes, it exits with the job ID instead of waiting indefinitely.
  5. Save the completed MP4 immediately and view it side by side with the original. The output URL may expire after one hour. Count it as your first edit only if the bright background is the only change and every other preservation requirement holds throughout the clip.
# macOS or Linux terminal
python3 --version
python3 -m pip install luma-agents
export LUMA_AGENTS_API_KEY="YOUR_ISSUED_API_KEY"
# edit_video.py
import time
from luma_agents import Luma

client = Luma()
job = client.generations.create(
    model="ray-3.2",
    type="video_edit",
    prompt="Change only the background to a bright studio. Preserve the original package color and texture, tumbler shape, position and size of the white logo, camera movement, and hand movement opening the lid.",
    source={
        "url": "https://example.com/tumbler-demo-5s.mp4",
        "media_type": "video/mp4"
    },
    video={
        "resolution": "720p",
        "edit": {"auto_controls": True}
    }
)

deadline = time.monotonic() + 600
while job.state not in ("completed", "failed"):
    if time.monotonic() >= deadline:
        print("Timed out. Job ID:", job.id)
        raise TimeoutError("The video job did not finish within 10 minutes.")
    time.sleep(2)
    job = client.generations.get(job.id)

if job.state == "completed":
    print(job.output[0].url)
else:
    print(job.failure_reason, job.failure_code)
# Run in the same terminal
python3 edit_video.py

The URL, tumbler setup, and 10-minute limit above are examples showing the input format for a first run. Replace them with an actual public MP4; usage-based charges may apply. If it times out, record the printed job ID and check its status again later. This review confirmed only the request structure in the official documentation and SDK; it did not measure actual generation quality, duration, or cost.

Creating a file is not the same as a successful edit

The official recommended setting for a first request is auto_controls=true. Switch to manual strength or signal-specific controls only when the result breaks the product shape or motion. Automatic controls and individual controls cannot be used together.

Edit situationNext settingReview criterion
First editauto_controls=trueSpecify only one background change and review the full transformation
Stay closer to the originaladhere_1~adhere_3Confirm that the product shape remains while the background change is not too weak
Middle ground between preservation and changeflex_1~flex_3Re-review form, logo, and contact scenes
Reinterpret the scene substantiallyreimagine_1~reimagine_3Decide whether it is better suited to concept exploration than a comparison experiment

For finer adjustment, pose, depth, normals, trajectory, and face signals are available. There is no comparative evidence that any one preset is better for every product demo. It is better to first identify what actually failed under automatic controls, then change one setting at a time.

completed means only technical completion

If the background changed but the product color, logo, and hand movement changed too, the editing experiment failed. Regardless of API status, a person must compare the entire clip with the original.

Add keyframes only when precision matters

You can attach guide images at moments when the product first appears or the logo is prominently visible. The official API accepts up to 64 keyframes and an equal-length keyframe_indexes array, mapping each image to a specific frame in the source video.

A keyframe is not a mask that edits only that scene. It is a reference image that communicates the target state at a specific point while the whole clip is re-rendered. For example, you can extract a logo close-up frame, change only its background accurately in an image editor, and attach that image to its original frame index.

Do not fill all 64; anchor the moments where failure is most costly first

64 is an allowed maximum, not a recommended count. On the first attempt, start with one or two important points such as the product reveal and logo close-up, so it is easier to see which guide affected the result.

keyframes and keyframe_indexes must have the same number of items. Indexes cannot be duplicated and must fall within the source-frame range. Even with keyframes, small labels or UI text are not guaranteed to be preserved exactly, so you must review the entire result again.

86% is not average performance for product demos

The figure of a conversion-rate improvement of more than 86% came from a single landing-page case for the online tutoring service TutorVista. It split new visitors 50:50 between the existing page and a page with an autoplay video, then reported a relative improvement of more than 86% over the original after repeatedly optimizing elements such as muting and post-play animation.

The original source does not describe the video used as a product demo. It also does not disclose sample size, absolute conversion rates, test duration, or the individual effect of each changed element. Therefore, the 86% figure cannot be carried over as average product-demo-video performance, the effect of adding a video alone, or a target for another site.

Broader observational data also did not guarantee higher conversion merely because a video was present. Unbounce analyzed about 35,000 customer landing pages in each of three separate periods from late 2020 to early 2021. Across 10 industries, pages with video generally performed similarly or worse. This was not a randomized controlled experiment, so it cannot establish that video caused the decline, but it at least does not support the formula “add video = higher conversion.”

A/B-test only edits that pass quality review

To interpret the effect of an edit, keep the page copy, CTA wording, and traffic conditions unchanged, and split only the video into original A and edited B. If the question is the background, do not change package color and texture, video length, or hand movement. The TutorVista case separated the control page and variation, and Unbounce also recommends directly comparing video variations on each site.

Choose one final metric that matches the real business goal: completed sign-ups, purchases, or demo bookings. Use play-start rate, drop-off by segment, completion rate, and CTA clicks as supporting metrics to identify the next edit target, rather than to declare a winner. Required sample size varies with the current conversion rate, traffic, and the minimum difference you want to detect, so you should not apply figures from external cases as-is.

Decide which versions to reject before comparing them

Do not include an edit in a conversion experiment if any of the following changed unintentionally: product shape, package color, logo, small text, contact between the hand and product, or camera movement. Even if an edit with multiple changes wins, it is difficult to reuse for the next production decision.

Ray 3.2 does not automatically raise conversion rates. What it reduces is the cost of throwing away footage that worked and starting over. If you specify only one background change from a validated original and inspect the whole clip, you can carry changes that actually worked for your visitors into the next demo instead of relying on an external 86% figure.