Skip to main content
Lucy 2 is our most advanced realtime video editing model. Upload a reference image and watch yourself transform into that character live. It builds on everything in our original Lucy realtime model and adds character reference: provide any face, and Lucy 2 maps your movements and expressions onto that identity in real time.
Use Lucy 2 as your default realtime editing model. It supports character reference and text-only editing in the same integration.

What makes Lucy 2 different

Lucy 1 (lucy_v2v_720p_rt)Lucy 2 (lucy_2_rt)
Text prompts✅ Add, modify, remove objects✅ Add, modify, remove objects
Character reference✅ Upload a face, become that character
Atomic state updatesset() updates prompt + image together
Lucy 2 covers both character transformation and text-only editing.

Quick start

Installation

npm install @decartai/sdk

Transform into a character

import { createDecartClient, models } from "@decartai/sdk";

const model = models.realtime("lucy_2_rt");

// Get your camera
const stream = await navigator.mediaDevices.getUserMedia({
  video: {
    frameRate: model.fps,
    width: model.width,
    height: model.height,
  },
});

const client = createDecartClient({
  apiKey: "your-api-key-here",
});

// Connect to Lucy 2
const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (transformedStream) => {
    document.getElementById("output").srcObject = transformedStream;
  },
});

// Upload a reference image and transform
await realtimeClient.set({
  prompt: "Transform into this character",
  image: characterImage, // File, Blob, or URL string
  enhance: true,
});

Use cases

Character cosplay

Become any character live on camera — no costume needed. Stream as your favorite game, anime, or movie character.

Virtual try-on

Let customers see products on themselves in realtime. Upload a model photo and map it onto the customer’s live feed.

Live streaming

Transform your appearance for Twitch, YouTube, or TikTok Live. Switch characters on the fly without interrupting your stream.

Content creation

Produce character-driven video content without actors or costumes. Change your look between shots with a single API call.

Video conferencing

Appear as a custom avatar in meetings. Your facial expressions and head movements transfer naturally to the reference character.

Interactive experiences

Build apps where users transform into characters in realtime — photo booths, AR filters, virtual events.

How character reference works

Lucy 2 uses your reference image as a visual identity target. Your live video provides the motion, expressions, and pose — the model blends the two so the output looks like the reference character performing your movements.
1

Connect with your camera

Establish a WebRTC connection with your camera stream, just like any other realtime model.
2

Upload a reference image

Provide any portrait photo — a character, a celebrity, or a generated face. The model extracts the visual identity from this image.
3

See yourself transformed

Your movements, expressions, and gestures are mapped onto the reference character in realtime. The output stream shows the character performing your actions.

Updating the reference image

You can change the character at any time without reconnecting. Use the set() method to atomically update the prompt and image together:
// Change to a new character
await realtimeClient.set({
  prompt: "Transform into this character",
  image: newCharacterImage,
  enhance: true,
});

// Update just the image
await realtimeClient.set({ image: newCharacterImage });

// Update just the prompt
await realtimeClient.set({ prompt: "Add sunglasses to the character" });

// Clear the reference image (fall back to text-only editing)
await realtimeClient.set({ image: null });
Always use set() when updating both the prompt and image. This applies both changes atomically, avoiding intermediate states where only one value has changed.

Text-only editing

Lucy 2 works without a reference image too. Use text prompts to add, modify, or remove elements in your live video:
// No reference image needed for text-only edits
await realtimeClient.set({ prompt: "Add a small dog running around" });
await realtimeClient.set({ prompt: "Change the background to a beach" });
await realtimeClient.set({ prompt: "Make the person's hair blonde" });

Reference image best practices

For the best character transformation results:
  • Use a clear, well-lit portrait — front-facing photos with neutral expressions work best
  • Match the framing — head-and-shoulders crops produce more consistent results than full-body shots
  • Supported formats — JPEG, PNG, and WebP
  • Resolution — at least 512×512 pixels recommended
  • Avoid heavy occlusion — images where the face is partially hidden may reduce quality

Connection lifecycle

Lucy 2 shares the same connection lifecycle as all realtime models. See the JavaScript SDK or Python SDK for details on:
  • Connection states (connecting, connected, generating, reconnecting, disconnected)
  • Auto-reconnect with exponential backoff
  • Error handling with DecartSDKError
  • Session tracking with generationTick events
  • Session viewing with subscribe tokens

Complete example

A full application with character switching, connection management, and error handling:
import { createDecartClient, models, type DecartSDKError } from "@decartai/sdk";

async function setupLucy2() {
  const model = models.realtime("lucy_2_rt");

  const stream = await navigator.mediaDevices.getUserMedia({
    video: {
      frameRate: model.fps,
      width: model.width,
      height: model.height,
    },
  });

  // Show the local camera feed
  document.getElementById("input-video").srcObject = stream;

  const client = createDecartClient({
    apiKey: process.env.DECART_API_KEY,
  });

  const realtimeClient = await client.realtime.connect(stream, {
    model,
    onRemoteStream: (transformedStream) => {
      document.getElementById("output-video").srcObject = transformedStream;
    },
  });

  // Track connection state
  realtimeClient.on("connectionChange", (state) => {
    document.getElementById("status").textContent = state;
  });

  // Track billing
  realtimeClient.on("generationTick", ({ seconds }) => {
    document.getElementById("usage").textContent = `${seconds}s`;
  });

  // Handle errors
  realtimeClient.on("error", (error: DecartSDKError) => {
    console.error("Lucy 2 error:", error.code, error.message);
  });

  // Character selection
  document.getElementById("character-input").addEventListener("change", async (e) => {
    const file = (e.target as HTMLInputElement).files[0];
    if (file) {
      await realtimeClient.set({
        prompt: "Transform into this character",
        image: file,
        enhance: true,
      });
    }
  });

  // Cleanup
  window.addEventListener("beforeunload", () => {
    realtimeClient.disconnect();
    stream.getTracks().forEach((track) => track.stop());
  });

  return realtimeClient;
}

setupLucy2();

Client-side authentication

For browser apps, use client tokens instead of your permanent API key. See client-side authentication for the full pattern.
// Backend: generate a short-lived token
const token = await client.tokens.create();

// Frontend: connect with the token
const frontendClient = createDecartClient({ apiKey: token.apiKey });

Technical specifications

PropertyValue
Model IDlucy_2_rt
Resolution1280×704
TransportWebRTC
Character referenceYes (JPEG, PNG, WebP)
Prompt enhancementYes (default: enabled)
Auto-reconnectYes (exponential backoff, up to 5 retries)

Next steps