> ## 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.
# Lucy 2.1 Realtime
> Transform yourself into any character in realtime with AI-powered video editing at 720p
Lucy 2.1 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.1 maps your movements and expressions onto that identity in real time.
Use Lucy 2.1 as your default realtime editing model. It supports character reference and text-only editing in the same integration.
## Quick start
### Installation
```bash theme={null}
npm install @decartai/sdk
```
```bash theme={null}
pip install decart
```
Add the JitPack repository to your `settings.gradle.kts`:
```kotlin settings.gradle.kts theme={null}
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}
```
Then add the dependency to your app's `build.gradle.kts`:
```kotlin build.gradle.kts theme={null}
dependencies {
implementation("com.github.DecartAI:decart-android:0.2.0")
}
```
### Transform into a character
```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";
const model = models.realtime("lucy-2.1");
// 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.1
const realtimeClient = await client.realtime.connect(stream, {
model,
mirror: "auto",
onRemoteStream: (transformedStream) => {
document.getElementById("output").srcObject = transformedStream;
},
initialState: {
prompt: {
text: "Change the wall's color to light blue, natural consistent paint finish.",
enhance: true,
},
},
});
// Upload a reference image and transform
await realtimeClient.set({
prompt: "Substitute the character in the video with the person in the reference image.",
image: characterImage, // File, Blob, or URL string
enhance: true,
});
```
```python theme={null}
import asyncio
from decart import DecartClient, models
from decart.types import ModelState, Prompt
async def main():
async with DecartClient(api_key="your-api-key-here") as client:
model = models.realtime("lucy-2.1")
realtime = await client.realtime.connect(
stream=media_stream,
model=model,
on_remote_stream=lambda s: display(s),
initial_state=ModelState(
prompt=Prompt(
text="Change the wall's color to light blue, natural consistent paint finish.",
enhance=True,
),
),
)
# Upload a reference image and transform
with open("character.jpg", "rb") as f:
await realtime.set(
prompt="Substitute the character in the video with the person in the reference image.",
image=f,
enhance=True,
)
asyncio.run(main())
```
```kotlin theme={null}
import ai.decart.sdk.DecartClient
import ai.decart.sdk.DecartClientConfig
import ai.decart.sdk.RealtimeModels
import ai.decart.sdk.realtime.ConnectOptions
import ai.decart.sdk.realtime.InitialPrompt
val model = RealtimeModels.LUCY_2_1
val client = DecartClient(context, DecartClientConfig(apiKey = "your-api-key"))
client.realtime.initialize(eglBase)
// Create camera track using model dimensions
val videoSource = client.realtime.createVideoSource(isScreencast = false)!!
val videoTrack = client.realtime.createVideoTrack("camera", videoSource)!!
val enumerator = Camera2Enumerator(context)
val cameraName = enumerator.deviceNames.first { enumerator.isFrontFacing(it) }
val capturer = enumerator.createCapturer(cameraName, null)
capturer.initialize(
SurfaceTextureHelper.create("CaptureThread", client.realtime.getEglBaseContext()),
context,
videoSource.capturerObserver
)
capturer.startCapture(model.width, model.height, model.fps)
// Connect to Lucy 2.1
client.realtime.connect(
localVideoTrack = videoTrack,
options = ConnectOptions(
model = model,
onRemoteVideoTrack = { track ->
remoteRenderer.addSink(track)
},
initialPrompt = InitialPrompt(
text = "Change the wall's color to light blue, natural consistent paint finish.",
enhance = true,
),
)
)
// Upload a reference image and transform
val characterBase64 = Base64.encodeToString(characterBytes, Base64.NO_WRAP)
client.realtime.setImage(
imageBase64 = characterBase64,
prompt = "Substitute the character in the video with the person in the reference image.",
enhance = true
)
```
Pass the prompt and/or reference image in `initialState` so the first frame is already transformed — otherwise viewers briefly see the raw camera feed.
## Portrait mode (9:16)
Lucy 2.1 supports both landscape (16:9) and portrait (9:16) video input. On mobile devices (iOS/Android), portrait mode works automatically — the OS maps the front camera to a vertical stream regardless of the constraints you pass.
For desktop browsers or external webcams, swap `width` and `height` when calling `getUserMedia` to request a portrait stream:
```typescript theme={null}
const model = models.realtime("lucy-2.1");
const stream = await navigator.mediaDevices.getUserMedia({
video: {
frameRate: { ideal: model.fps },
width: { ideal: model.height }, // swap: use height as width
height: { ideal: model.width }, // swap: use width as height
facingMode: "user",
},
});
const client = createDecartClient({ apiKey: "your-api-key-here" });
const realtimeClient = await client.realtime.connect(stream, {
model,
onRemoteStream: (transformedStream) => {
document.getElementById("output").srcObject = transformedStream;
},
});
```
Portrait mode is ideal for mobile webcams and vertical video content. On mobile (iOS/Android), you don't need to swap dimensions — the OS maps the front camera to a vertical stream automatically regardless of the constraints you pass.
## Use cases
Become any character live on camera — no costume needed. Stream as your favorite game, anime, or movie character.
Let customers see products on themselves in realtime. Upload a model photo and map it onto the customer's live feed.
Transform your appearance for Twitch, YouTube, or TikTok Live. Switch characters on the fly without interrupting your stream.
Produce character-driven video content without actors or costumes. Change your look between shots with a single API call.
Appear as a custom avatar in meetings. Your facial expressions and head movements transfer naturally to the reference character.
Build apps where users transform into characters in realtime — photo booths, AR filters, virtual events.
## How character reference works
Lucy 2.1 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.
Establish a WebRTC connection with your camera stream, just like any other realtime model.
Provide any portrait photo — a character, a celebrity, or a generated face. The model extracts the visual identity from this image.
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 replace the session state — include all fields you want to keep:
```typescript JavaScript theme={null}
// Change to a new character
await realtimeClient.set({
prompt: "Substitute the character in the video with the person in the reference image.",
image: newCharacterImage,
enhance: true,
});
// Set a new image only (clears any previous prompt)
await realtimeClient.set({ image: newCharacterImage });
// Set a new prompt only (clears any previous image)
await realtimeClient.set({ prompt: "Add dark sunglasses to the person's face." });
// Clear the reference image (fall back to text-only editing)
await realtimeClient.set({ image: null });
```
```python Python theme={null}
# Change to a new character
with open("new_character.jpg", "rb") as f:
await realtime.set(
prompt="Substitute the character in the video with the person in the reference image.",
image=f,
enhance=True,
)
# Set a new image only (clears any previous prompt)
with open("another.jpg", "rb") as f:
await realtime.set(image=f)
# Set a new prompt only (clears any previous image)
await realtime.set(prompt="Add dark sunglasses to the person's face.")
```
```kotlin Android theme={null}
// Change to a new character
val newCharacterBase64 = Base64.encodeToString(newCharacterBytes, Base64.NO_WRAP)
client.realtime.setImage(
imageBase64 = newCharacterBase64,
prompt = "Substitute the character in the video with the person in the reference image.",
enhance = true
)
// Set a new image only
client.realtime.setImage(imageBase64 = newCharacterBase64)
// Set a new prompt only (text-only editing)
client.realtime.setPrompt("Add dark sunglasses to the person's face.")
// Clear the reference image (fall back to text-only editing)
client.realtime.setImage(imageBase64 = null)
```
`set()` replaces the entire state — fields you omit are cleared. Always include every field you want to keep. This avoids intermediate states and ensures prompt and image stay in sync.
## Text-only editing
Lucy 2.1 works without a reference image too. Use text prompts to add, modify, or remove elements in your live video:
```typescript JavaScript theme={null}
// No reference image needed for text-only edits
await realtimeClient.set({ prompt: "Add a small dog running around in the background." });
await realtimeClient.set({ prompt: "Change the background to a sandy beach with clear blue water." });
await realtimeClient.set({ prompt: "Change the person's hair color to bright blonde." });
```
```python Python theme={null}
# No reference image needed for text-only edits
await realtime.set(prompt="Add a small dog running around in the background.")
await realtime.set(prompt="Change the background to a sandy beach with clear blue water.")
await realtime.set(prompt="Change the person's hair color to bright blonde.")
```
```kotlin Android theme={null}
// No reference image needed for text-only edits
client.realtime.setPrompt("Add a small dog running around in the background.")
client.realtime.setPrompt("Change the background to a sandy beach with clear blue water.")
client.realtime.setPrompt("Change the person's hair color to bright blonde.")
```
See the [prompting guide](#prompting-guide) below for the best prompt structures for each edit type.
## Prompting guide
Lucy 2.1 responds best when your prompts follow specific patterns for each edit type. There are four supported operations, each with its own structure.
| Edit type | Prompt template |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| **Character transformation** | "Substitute the character in the video with \." |
| **Add** | "Add \ to \." |
| **Replace** | "Change \