> ## Documentation Index > Fetch the complete documentation index at: https://docs.reactor.inc/llms.txt > Use this file to discover all available pages before exploring further. # X2 Prompt Guide > How to prompt X2 for live transformations, reference-guided edits, and drag-controlled motion. X2 is a live conditional video model. It does not build the whole scene from text: the source supplies the scene and motion, an optional reference image supplies appearance, the prompt defines the transformation, and an optional control signal guides motion. ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} SOURCE = scene, composition, identity, and motion REFERENCE = desired character, clothing, or visual style PROMPT = transformation, action, and preservation boundary CONTROL = spatial trajectory ``` This division of responsibility is the foundation of reliable prompting. Do not spend the prompt describing content the model can already see in the source or reference. Use it to state exactly what changes, how it behaves, and what remains stable. ## The core prompt pattern A strong X2 prompt follows this pattern: ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} [CAPABILITY PREFIX] [EXACT TARGET] + [ONE VISIBLE CHANGE OR ACTION] + [SPATIAL OR PHYSICAL RELATIONSHIP] + [SHORT PRESERVATION BOUNDARY] ``` For example: ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 视频中人物衣服替换成参考图中衣服 仅替换画面中央人物的外套。服装随身体自然变形；保留面部、发型、动作、背景和镜头。 ``` In English: > Change only the central person's jacket to the outfit in the reference image. The clothing follows > the body naturally. Preserve the face, hair, motion, background, and camera. The ideal prompt is the shortest instruction that clearly establishes: * **Target:** the exact subject, object, garment, or region being controlled * **Change:** one dominant visible transformation or action * **Relationship:** contact, direction, tracking, or motion behavior * **Boundary:** the important parts of the source that must remain stable ## Stable capability prefixes X2 supports free-form prompts, but its model guide recommends exact Chinese prefixes for its reference-guided capabilities. Keep the prefix verbatim and place the scene-specific instruction on the following line. The prefix is prompt text, not a separate API mode. | Intent | Stable prefix | Inputs | Scope | | --------------------- | ------------------ | ---------------------------------------- | -------------------------------------------------- | | Character replacement | `视频中角色替换成参考图中角色` | Source video and character reference | Character only | | Clothing replacement | `视频中人物衣服替换成参考图中衣服` | Source video and clothing reference | Clothing only | | Style transfer | `视频风格变为参考图指定的风格` | Source video and style reference | Character, clothing, and background | | Trajectory animation | `让画面自然动起来` | Still or video source and control signal | Motion | | Dimension interaction | `指定角色在场景中互动` | Camera source and character reference | Adds an interactive character | | Free prompting | No prefix | Source; reference optional | Effects, objects, backgrounds, and transformations | Use the Chinese prefix even when the rest of the instruction is English. For maximum consistency, use concise Simplified Chinese for the scene-specific instruction too. ## Instructions, not keyword lists The source already contains the subject, setting, framing, lighting, and motion. Prompt the change, not a new scene from scratch.
Make this magical, cinematic, epic, dramatic, high quality.
A burning crystalline fireball materializes in the person's open right palm and sheds sparks as the hand moves. Preserve the person's face, clothing, room, and camera.
The stronger version names a visible result, anchors it to a precise location, explains how it behaves, and defines a boundary. Additional style adjectives would not make it more controllable. ## Character replacement Use one clear reference image for the target character. The source person's expressions, gaze, pose, and movements become the performance that the new character follows. ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 视频中角色替换成参考图中角色 将画面左侧人物替换为参考图角色。保留原人物的表情、视线、姿势和动作；右侧人物、背景和镜头保持不变。 ``` When several people are visible, name the target spatially: "the person on the left," "the seated person," or "the person in the white shirt." Avoid pronouns such as "him" or "her" unless only one person can possibly match. X2 can replace multiple people with different characters when the reference contains multiple characters. Keep the subject count and left-to-right arrangement in the source and reference as unambiguous as possible. ## Clothing replacement The clothing reference can show a garment against a clean background or a person wearing the target outfit. Use the clothing prefix whenever identity, face, and hair must stay unchanged. ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 视频中人物衣服替换成参考图中衣服 仅替换画面中央人物的服装。布料随身体动作自然变形；保留面部、发型、身体比例、姿势和场景。 ``` For a partial replacement, name the garment and protect the rest: ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 视频中人物衣服替换成参考图中衣服 仅将人物的黑色夹克替换为参考图中的外套。裤子、鞋子、面部和背景保持不变。 ``` ## Whole-scene style transfer Style transfer intentionally permits the subject, clothing, and background to change together. The reference image carries the visual vocabulary; the prompt defines scope and continuity. ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 视频风格变为参考图指定的风格 人物、服装和背景统一采用参考图风格。保留原视频的构图、人物动作、空间位置和镜头运动。 ``` Do not use the style prefix when the character or clothing alone should change. A whole-frame style instruction gives the model permission to repaint the whole frame. ## Dimension interaction Dimension interaction introduces a reference character into a live physical scene and lets it respond to people or objects already there. ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 指定角色在场景中互动 参考图角色出现在空着的右手旁，并自然回应手部动作。保持人物、房间和镜头不变。 ``` The source setup matters as much as the prompt: * Start against a plain background. * Avoid human faces while the reference character is first forming. Otherwise, the character may be mapped onto a person already in the frame. * Let the generated character stabilize before people enter and interact with it. * Describe one interaction with a hand, surface, or environmental object. ## Free prompting Free prompting covers effects, object replacement, background changes, and transformations that do not need a capability prefix. Favor a concrete result state anchored to a visible body part or source object. **Effect** ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 右手掌心出现一颗燃烧的火球。火焰和火星随手部移动；保持脸部、衣服、房间和镜头不变。 ``` > A burning fireball appears in the right palm. The flame and sparks follow the hand. Preserve the > face, clothing, room, and camera. **Object replacement** ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 将左手中的白色毛绒球替换成一只可爱的小猫。小猫与手部保持自然接触；人物和背景保持不变。 ``` > Replace the white plush ball in the left hand with a cute kitten. Keep natural contact with the > hand. Preserve the person and background. **Body-anchored effect** ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 双眼持续射出明亮的红色激光。激光随视线方向移动；保留面部身份、身体、背景和镜头。 ``` > Bright red lasers extend from both eyes and follow the direction of the gaze. Preserve facial > identity, body, background, and camera. Concrete result-state language such as "a fireball is in the person's palm" is usually stronger than abstract direction such as "make the scene feel powerful." ## Drag and trajectory control For trajectory-controlled generation, the prompt names **what** follows the trajectory and the control signal supplies **where** it moves. ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} 让画面自然动起来 红色纸飞机沿拖拽轨迹飞行并自然倾斜，背景城市保持固定。 ``` A reliable drag instruction contains four elements: ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} [CONTROLLED SUBJECT] follows the active drag trajectory, [PHYSICAL RESPONSE], [ANCHORED RELATIONSHIP], [STABLE ENVIRONMENT]. ``` Examples: ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} The koi follows the active drag trajectory, bending naturally as it swims behind the reeds and through the stone arch, while the pond and camera remain fixed. ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} Only the blue-tipped front tentacle follows the active drag trajectory and curls toward the lever, while the octopus body stays planted and the background remains fixed. ``` The native control representation is a black video containing soft white points at the controlled positions. Black frames mean no active control signal. Multiple points are supported when the integration supplies them, although an application may expose only one pointer. For a clean gesture: 1. Start directly on the intended subject or body part. 2. Drag slowly along a broad, smooth path. 3. Hold the endpoint briefly before release so it survives the model's chunk cadence. 4. Expect the generated output to lag behind the physical pointer. The control signal guides motion. It is not a reliable object selector, cloning command, or event trigger. Fast clicks and short drags may end before the model has incorporated the intended destination. ### Drag state is not prompt state The active prompt persists while generation runs. If it says that petals "continuously fall," the model can keep producing that motion even after the drag signal disappears. Temporal phrases such as "while dragging" and "when released" do not turn a persistent instruction into a guaranteed press-and-release state machine.
While the drag is held, cherry blossom petals continuously fall from the sky. When the drag is released, the falling stops.
Only the cherry blossom petals follow the active drag trajectory. Their movement is caused exclusively by the control point. With no control point, the petals remain still. The sky, branches, camera, and everything else remain fixed.
The stronger prompt removes the unconditional visual instruction "continuously fall" and binds the petals' movement to the control signal. It improves the behavior, but it still does not provide strict application logic. When exact hold-and-release behavior matters, switch the complete prompt with the input state: | State | Prompt | | ------------ | -------------------------------------------------------------------------------------------------- | | Pointer down | `Cherry blossom petals fall and follow the active drag trajectory. Everything else remains fixed.` | | Pointer up | `The cherry blossom petals are motionless. The entire scene is still.` | Prompt changes land at generation boundaries, so a short settling delay is normal. Always send the complete replacement instruction; avoid relative follow-ups such as "now stop the petals." ## Choosing source and reference inputs Prompt quality cannot compensate for an ambiguous source or reference. **Source video** * Keep the controlled subject large enough to identify and away from the frame edge. * Prefer stable framing and slow or moderate motion. * Make clothing visible for clothing replacement and expressions visible for character replacement. * Preserve the source aspect ratio before the session begins. Cropping and resolution negotiation are media-pipeline concerns, not prompt problems. **Reference image** * Use one isolated, readable subject whenever possible. * Use the reference for appearance and the prompt for behavior and relationships. * Match the desired viewing angle and framing when identity or garment structure matters. * Do not spend the prompt exhaustively redescribing details already visible in the reference. ## An iteration ladder Start short. Add detail only to solve a visible failure: 1. Send the stable capability prefix. 2. Add the exact target and transformation. 3. Add one motion or physical-relationship clause. 4. Add one preservation boundary. If the prompt does not take effect: * Reduce motion in the source. Fast source motion makes prompt alignment harder. * Wait longer. Some transformations take several generation chunks to become visible. * Rephrase the target and action with more concrete nouns and verbs. * Generate again. X2 has some run-to-run variation. If the edit is still weak, strengthen the target noun and action before adding adjectives. ## Troubleshooting | Failure | Best correction | | ------------------------------------------ | ------------------------------------------------------------------------------ | | Nothing changes | Use a stronger visible action, slow the source, wait, then retry | | Wrong person changes | Name position, clothing, or another visible discriminator | | Too much of the frame changes | Use a narrower capability prefix and add one preservation boundary | | Character identity is weak | Improve the reference instead of lengthening the prompt | | Clothing replacement changes the face | Use the clothing prefix and explicitly preserve face and hair | | A summoned character maps onto a person | Begin with a plain, face-free source until the character settles | | Drag motion jitters or misses the endpoint | Slow the path, simplify the subject, and hold the endpoint briefly | | Background moves during drag | Name the controlled subject and explicitly fix the background and camera | | An effect continues after release | Remove unconditional motion language or switch prompts with the input state | | The frame is cropped | Fix the source canvas or session aspect ratio; prompting cannot restore pixels | ## Common pitfalls * **Several edits in one prompt.** Character replacement, wardrobe change, style transfer, and a background swap compete. Choose one dominant transformation. * **A vague target.** "Make it move" is ambiguous. Name the red paper glider, the left person's jacket, or the white ball in the hand. * **Pronouns in a crowded frame.** Spatial descriptions are more reliable than "him," "her," or "it." * **Keyword piles.** "Cinematic, epic, magical, 8K" does not define a controllable edit. * **Long negative lists.** Name the important preservation boundary instead of cataloguing every forbidden change. * **Multi-stage stories.** "First this happens, then..." is harder to sustain than one visible action or result state. * **Describing the reference twice.** Let the reference supply appearance; use the prompt for its role in the source scene. * **Treating the pointer as a button.** It provides spatial conditioning, not guaranteed event semantics. * **Relative mid-stream instructions.** A new prompt replaces the active prompt. Restate the whole instruction rather than saying "make it more dramatic" or "stop that." ## The one-sentence rule When in doubt, use this structure: > One exact subject performs one visible action or transformation, with one physical relationship > and one preservation boundary. That sentence is usually a better starting point than a long cinematic description. Add detail only when a specific failure shows you what the model still needs to know.