> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.decart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompting Guide

> How to write effective prompts for Lucy 2.5 — templates, examples, and troubleshooting for every edit type.

Lucy 2.5 transforms video from a simple written prompt. Strong prompts describe the visible edit you want: what should be added, replaced, removed, restyled, transformed, animated, or preserved.

Think of the prompt as short creative direction. You do not need technical language. You do need clear visual details.

Lucy 2.5 can also make effects feel physically present. For more grounded results, describe how an edit interacts with the subject, their motion, and the environment: light reflects on skin, smoke wraps around shoulders, particles bounce off surfaces, and clothing moves with the body.

<Note>
  Lucy 2.5 expects prompts in a specific structured format. Prompt enhancement (`enhance: true`) automatically rewrites your input - along with any reference image - into that structure, so keep it enabled. It is on by default.
</Note>

## Core prompting principles

Strong prompts answer five questions:

* **What should change?** Name the person, object, garment, background, material, or effect.
* **What should it become?** Describe the new visual result.
* **Where should it apply?** Anchor the edit to a body part, object, garment, surface, or background.
* **How should it interact?** For physical effects, describe how it attaches, follows, wraps, reflects, casts light, or responds to motion.
* **What should stay the same?** Preserve the person's identity, face, hair, pose, camera angle, motion, room, or background when needed.

Keep prompts clear and compact. A useful target is 2–4 concise sentences, not a long paragraph.

Use visible identifiers instead of frame position. If several similar objects appear, identify the target by color, material, pattern, text, logo, shape, or another visible detail.

## Use reference images intentionally

Reference images work better when the prompt says which part of the image matters and how to apply it. Treat the reference image as visual material, and the prompt as the instruction.

A reference image can supply a specific item to add to the video, or an overall art style for the whole video.

Good reference images usually:

* Show the item clearly
* Avoid extra people when possible
* Avoid cluttered backgrounds
* Show the full shape of the garment, product, character, or object
* Avoid folded, hidden, or partially blocked items

Do not rely on an empty prompt. Even with a strong reference image, a bit more instruction helps Lucy 2.5 understand the edit.

|             |                                                                    |
| ----------- | ------------------------------------------------------------------ |
| **Better**  | `"Put the black leather jacket from the reference on the person."` |
| **Riskier** | `"Put this on the person."`                                        |

When using a reference image:

* Name the specific item, character, or style to use
* Describe the details that matter: color, material, texture, shape, pattern, logo placement, or fit
* Apply it to a visible target in the video
* Ignore unrelated reference details — the reference person's face, pose, lighting, or background

## Prompt templates

Start with one of these structures, then add the details that matter.

| Edit type                     | Template                                                                                                                                                       |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Character transformation**  | `"Replace the character in the video with <description>."`                                                                                                     |
| **Add object**                | `"Add <description of object> to <where it should appear>."`                                                                                                   |
| **Replace object or feature** | `"Replace <thing in the video> with <new thing or reference image subject>."`                                                                                  |
| **Change attribute**          | `"Change <object or feature> to <new color, material, texture, or style>."`                                                                                    |
| **Remove object**             | `"Remove <object>, leaving <what should appear in its place>."`                                                                                                |
| **Change background**         | `"Change the background to <scene with visible activity>."`                                                                                                    |
| **Restyle the whole video**   | `"Transform the entire scene into <style>. The final video should show <specific visual traits>, while preserving the original subjects, layout, and motion."` |

## Character transformation

Use character transformation when the person in the video should become a different person, creature, or designed character. If you use a reference image, describe the character's appearance in the prompt.

**"Replace the character in the video with <span style={{color: '#527a2e'}}>\<description of character></span>."**

Examples:

* *Replace the character with <span style={{color: '#527a2e'}}>a silver-armored space explorer with a reflective blue visor, white gloves, glowing shoulder lights, and a short navy cape.</span>*
* *Replace the character with <span style={{color: '#527a2e'}}>a cheerful cartoon chef wearing a tall white hat, red neck scarf, double-breasted jacket, and round glasses.</span>*
* *Replace the character with <span style={{color: '#527a2e'}}>the person in the reference image, keeping their short curly black hair, gold earrings, green jacket, and warm smile.</span>*

<Tip>
  Mention important details that may not be obvious in the reference image, such as a tail, shield, wings, backpack, or cape.
</Tip>

## Add objects

Use add prompts when a new prop, accessory, object, or creature should appear in the video. Describe what to add and how it should relate to the subject or scene.

**"Add <span style={{color: '#527a2e'}}>\<description of object></span> to <span style={{color: '#96603a'}}>\<where it should appear></span>."**

Examples:

* *Add <span style={{color: '#527a2e'}}>a translucent blue hologram of a tiny city floating</span> <span style={{color: '#96603a'}}>above the person's open palm</span>, casting a soft blue glow on their fingers.*
* *Add <span style={{color: '#527a2e'}}>a red sequined cone hat with white fluffy trim</span> to <span style={{color: '#96603a'}}>the person's head</span>.*
* *Add <span style={{color: '#527a2e'}}>the plush green backpack from the reference image, attached</span> <span style={{color: '#96603a'}}>to the person's shoulders</span> and shifting with their body as they move.*

<Tip>
  Useful placement words: "on," "attached to," "floating above," "wrapped around," "resting on," and "following."
</Tip>

## Replace objects or features

Use replace prompts when something visible in the video should become something else. Name both the target and the replacement.

**"Replace <span style={{color: '#96603a'}}>\<thing in the video></span> with <span style={{color: '#527a2e'}}>\<new thing or reference image subject></span>."**

Examples:

* *Replace <span style={{color: '#96603a'}}>the person's sunglasses</span> with <span style={{color: '#527a2e'}}>oversized heart-shaped pink glasses from the reference image.</span>*
* *Replace <span style={{color: '#96603a'}}>the person's jacket</span> with <span style={{color: '#527a2e'}}>a glossy yellow raincoat with black buttons and a high collar.</span> Keep the person's identity, face, and hair unchanged.*
* *Replace <span style={{color: '#96603a'}}>the person's nose</span> with <span style={{color: '#527a2e'}}>the carrot from the reference image.</span>*

<Note>
  Be specific using visible details. "The white sneaker with red laces" is clearer than "the shoe."
</Note>

## Change attribute

Use appearance prompts when the object stays in place but its visual qualities change: color, texture, material, pattern, lighting, or finish.

**"Change <span style={{color: '#96603a'}}>\<object or feature></span> to <span style={{color: '#527a2e'}}>\<new color, material, texture, or style></span>."**

Examples:

* *Change <span style={{color: '#96603a'}}>the person's sweater</span> to <span style={{color: '#527a2e'}}>red knit fabric with a small white emblem on the chest.</span>*
* *Change <span style={{color: '#96603a'}}>the wall's color</span> to <span style={{color: '#527a2e'}}>light blue with a smooth matte paint finish.</span>*
* *Change <span style={{color: '#96603a'}}>the table surface</span> to <span style={{color: '#527a2e'}}>polished dark marble with subtle white veins.</span>*

<Tip>
  For clothing edits, useful details include fabric, fit, sleeve length, neckline, logo or text, buttons, zippers, and placement.
</Tip>

## Remove objects

Use remove prompts when an object should disappear. For cleaner results, say what should appear in its place.

**"Remove <span style={{color: '#96603a'}}>\<object></span>, leaving <span style={{color: '#527a2e'}}>\<what should appear in its place></span>."**

Examples:

* *Remove <span style={{color: '#96603a'}}>the soccer ball on the grass</span>, leaving <span style={{color: '#527a2e'}}>uninterrupted green grass in its place.</span>*
* *Remove <span style={{color: '#96603a'}}>the coffee mug from the desk</span>, leaving <span style={{color: '#527a2e'}}>the wooden tabletop visible.</span>*
* *Remove <span style={{color: '#96603a'}}>the poster from the wall</span>, leaving <span style={{color: '#527a2e'}}>a smooth white wall in its place.</span>*

<Note>
  If there are multiple similar objects, identify the target by visible details such as color, material, size, pattern, or text.
</Note>

## Change background

Use background prompts when the subject should stay visible but the environment should change. Describe the setting and what is happening in it.

**"Change the background to <span style={{color: '#527a2e'}}>\<scene with visible activity></span>."**

Examples:

* *Change the background to <span style={{color: '#527a2e'}}>a Manhattan street scene with people walking on the sidewalk, yellow taxis passing, storefront lights, and soft afternoon shadows.</span>*
* *Change the background to <span style={{color: '#527a2e'}}>a beach scene with waves gently crashing on the shore and sunlight reflecting on the water.</span> Keep the person's identity, face, and clothing unchanged.*
* *Change the background to <span style={{color: '#527a2e'}}>a snowy park where kids are playing in the snow and snowflakes fall through the air.</span>*

<Tip>
  Do not only name the place. Add motion, weather, lighting, or activity.
</Tip>

## Restyle the entire video

Restyle a video when you want a new art style across the whole clip. A restyle changes the entire picture at once, unlike a targeted edit. A strong restyle prompt covers four things:

* The style to apply
* Whether to change the whole video or just one part
* What the final video should look like
* Concrete visual traits: color palette, texture, line style, material, brushwork, or level of detail

**"Transform the entire scene into <span style={{color: '#527a2e'}}>\<style></span>. The final video should show <span style={{color: '#527a2e'}}>\<specific visual traits></span>, while preserving the original subjects, layout, and motion."**

Examples:

* *Transform the entire scene into <span style={{color: '#527a2e'}}>a watercolor painting style. The final video should show soft translucent color washes, visible paper texture, loose ink outlines, muted pastel colors, and simplified forms,</span> while preserving the original subjects, layout, and motion.*
* *Transform the entire scene into <span style={{color: '#527a2e'}}>an anime style. The final video should show bold clean linework, flat cel-shaded color blocks, vibrant saturated colors, and simplified backgrounds,</span> while preserving the original subjects, layout, and motion.*
* *Transform the entire scene into <span style={{color: '#527a2e'}}>a charcoal sketch style. The final video should show rough graphite shading, visible paper texture, loose hatching, and high-contrast black-and-white tones,</span> while preserving the original subjects, layout, and motion.*

<Note>
  Skip vague words like "realistic," "cinematic," "beautiful," or "seamless." They add no detail and make the result less predictable. With a reference image, describe only its visual style — colors, brushwork, and texture. Ignore its pose, lighting, and background.
</Note>

Layered prompts combine multiple changes. They are easier to control when each change belongs to a different visual layer — background, person, clothing, object, or effect.

**"Change <span style={{color: '#527a2e'}}>\<background layer></span>. Change <span style={{color: '#527a2e'}}>\<subject layer></span>. Add <span style={{color: '#527a2e'}}>\<effect layer></span>."**

Examples:

* *Change the background to a colorful ice cream shop. Change the person's hair to swirled vanilla soft serve. Change their shirt to a waffle-cone texture. Add colorful sprinkles falling around the person and bouncing lightly off their shoulders.*
* *Change the background to a moonlit forest. Replace the person's jacket with a dark velvet cloak. Add small glowing fireflies floating around their shoulders.*
* *Change the room into a futuristic control center. Add a transparent helmet to the person's head. Add soft blue interface lights reflecting on their face and visor.*

<Tip>
  Put each edit in its own sentence. If the result is unstable, test the main change first, then add the other layers.
</Tip>

## Common prompt mistakes

* **Avoid process language.** Describe the result, not the model operation.
* **Avoid vague quality words.** Words like "realistic," "natural," "seamless," "cinematic," "beautiful," and "high quality" are less useful than concrete visual details.
* **Avoid unrelated lighting or mood instructions.** If you are changing a jacket, describe the jacket.
* **Avoid several unrelated edits in one prompt.** Test the outfit, background, hairstyle, and lighting changes separately before combining them.
* **Avoid mixing several art styles in one restyle.** Pick one style, describe its traits, and switch styles one at a time.
* **Avoid identifying targets by frame position.** Use visible details like color, material, pattern, text, logo, shape, or distinctive markings.
* **Avoid negative instructions** such as "don't add a hat." The model may still focus on the object you mention. Describe what you want to see instead.
* **Avoid long event chains** such as "bubbles float around the person's head, pop into glitter, turn into birds, and fly into the sky." Short physical interactions are easier to maintain.

## Dos and don'ts

| Do                                                                                                                                                                                                                                 | Don't                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `"Add a silver crown floating above the person's head."`                                                                                                                                                                           | `"Make it royal."`                                       |
| `"Remove the coffee mug from the desk, leaving the wooden tabletop visible."`                                                                                                                                                      | `"Remove the mug."`                                      |
| `"Change the background to a beach with waves crashing, sunlight on the water, and pale sand."`                                                                                                                                    | `"Make it a beach."`                                     |
| `"Glowing blue sparks emit from the person's fingertips, trail with their hand motion, and reflect on the person's fingers."`                                                                                                      | `"A magical thing happens around the hands."`            |
| `"Use the black cropped jacket from the reference, including the glossy leather texture and silver zipper. Apply it to the person's jacket."`                                                                                      | `"Use the reference image."`                             |
| `"Replace the shirt with a red silk blouse. Keep the person's identity, face, and hair unchanged."`                                                                                                                                | `"Change the person into someone wearing a red blouse."` |
| `"Transform the entire scene into a watercolor painting style. The final video should show translucent color washes, visible paper texture, and muted pastel colors, while preserving the original subjects, layout, and motion."` | `"Make this Pixar style."`                               |

## Troubleshooting

| Result                                          | Try this                                                                                                             |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **The edit applies to the wrong object**        | Identify the target with visible details: "the red jacket," "the glass cup," "the white sneaker with red laces."     |
| **The reference image is not followed closely** | Describe the most important visual details from the reference image in the prompt.                                   |
| **The output changes too much**                 | Limit the prompt to one edit and name what should stay the same.                                                     |
| **The person's face or identity changes**       | Add "Keep the person's identity and face unchanged" or name the facial and hair details to preserve.                 |
| **The result is too generic**                   | Add color, material, texture, size, shape, style, or motion details.                                                 |
| **The effect looks pasted on**                  | Add physical cues: where it casts light, what it bounces off, what it wraps around, or how it moves with the person. |
| **A restyle flickers between styles**           | Pick one style and describe its traits — palette, linework, texture. Avoid combining several styles in one prompt.   |