feat: canonical model names, lucy-2.1, and deprecation warnings

examples/bun-cli/cli.ts

@@ -13,7 +13,7 @@ const inputImage = Bun.file(inputPath);
 
 console.log("Editing image...");
 const image = await client.process({
-  model: models.image("lucy-pro-i2i"),
+  model: models.image("lucy-image-2"),
   prompt,
   data: inputImage,
 });

examples/express-api/src/server.ts

@@ -37,7 +37,7 @@ app.post("/api/image/edit", async (req, res) => {
     }
 
     const blob = await client.process({
-      model: models.image("lucy-pro-i2i"),
+      model: models.image("lucy-image-2"),
       prompt,
       data: parseBase64DataUrl(imageDataUrl, "image"),
     });
@@ -60,7 +60,7 @@ app.post("/api/video/generate", async (req, res) => {
     }
 
     const job = await client.queue.submit({
-      model: models.video("lucy-pro-v2v"),
+      model: models.video("lucy-clip"),
       prompt,
       data: parseBase64DataUrl(videoDataUrl, "video"),
     });
@@ -103,7 +103,7 @@ app.post("/api/video/generate-sync", async (req, res) => {
     }
 
     const result = await client.queue.submitAndPoll({
-      model: models.video("lucy-pro-v2v"),
+      model: models.video("lucy-clip"),
       prompt,
       data: parseBase64DataUrl(videoDataUrl, "video"),
     });

examples/express-proxy/README.md

@@ -70,7 +70,7 @@ const client = createDecartClient({
 });
 
 const blob = await client.process({
-  model: models.image('lucy-pro-i2i'),
+  model: models.image('lucy-image-2'),
   prompt: 'Turn this into a watercolor painting',
   data: sourceFile,
 });

examples/express-proxy/public/index.html

@@ -276,7 +276,7 @@ <h1>🎨 Decart SDK Proxy Example</h1>
           showStatus('Editing image...', 'info');
 
           const blob = await decartClient.process({
-            model: models.image('lucy-pro-i2i'),
+            model: models.image('lucy-image-2'),
             prompt,
             data: sourceImage,
           });

examples/hono-edge/src/index.ts

@@ -52,7 +52,7 @@ app.post("/api/image/generate", async (c) => {
     }
 
     const blob = await client.process({
-      model: models.image("lucy-pro-i2i"),
+      model: models.image("lucy-image-2"),
       prompt,
       data: parseBase64DataUrl(imageDataUrl, "image"),
     });
@@ -76,7 +76,7 @@ app.post("/api/video/generate", async (c) => {
     }
 
     const job = await client.queue.submit({
-      model: models.video("lucy-pro-v2v"),
+      model: models.video("lucy-clip"),
       prompt,
       data: parseBase64DataUrl(videoDataUrl, "video"),
     });

examples/nextjs-proxy/README.md

@@ -56,7 +56,7 @@ const client = createDecartClient({
 });
 
 const blob = await client.process({
-  model: models.image("lucy-pro-i2i"),
+  model: models.image("lucy-image-2"),
   prompt: "Turn this into a watercolor painting",
   data: sourceFile,
 });

examples/nextjs-proxy/app/page.tsx

@@ -23,7 +23,7 @@ export default function Home() {
     try {
       const client = createDecartClient({ proxy: PROXY_ROUTE });
       const blob = await client.process({
-        model: models.image("lucy-pro-i2i"),
+        model: models.image("lucy-image-2"),
         prompt,
         data: sourceImage,
       });

examples/nextjs-realtime/README.md

@@ -43,8 +43,8 @@ pnpm dev
 
 ## Models
 
-This example uses `mirage_v2` for style transformation. You can also use:
+This example uses `lucy-restyle-2` for style transformation. You can also use:
 
-- `mirage` - MirageLSD video restyling model (older)
-- `lucy_v2v_720p_rt` - Lucy for video editing (add objects, change elements)
-- `lucy_2_rt` - Lucy 2 for video editing with reference image support (better quality)
+- `lucy-restyle` - MirageLSD video restyling model (older)
+- `lucy` - Lucy for video editing (add objects, change elements)
+- `lucy-2` - Lucy 2 for video editing with reference image support (better quality)

examples/nextjs-realtime/components/video-stream.tsx

@@ -23,7 +23,7 @@ export function VideoStream({ prompt }: VideoStreamProps) {
 
     async function start() {
       try {
-        const model = models.realtime("mirage_v2");
+        const model = models.realtime("lucy-restyle-2");
 
         setStatus("requesting camera...");
         const stream = await navigator.mediaDevices.getUserMedia({

examples/react-vite-weather-outfit/README.md

@@ -1,6 +1,6 @@
 # React + Vite Weather Outfit
 
-A simple React + Vite demo that generates weather-appropriate outfits from an input photo using the Decart SDK (image-to-image with the `lucy-pro-i2i` model).
+A simple React + Vite demo that generates weather-appropriate outfits from an input photo using the Decart SDK (image-to-image with the `lucy-image-2` model).
 
 ## Setup
 
@@ -35,9 +35,9 @@ pnpm dev
 ## How it works
 
 1. The chosen image (sample or uploaded) is sent to Decart.
-2. The `lucy-pro-i2i` model applies a prompt.
+2. The `lucy-image-2` model applies a prompt.
 3. The processed image is returned.
 
 ## Model
 
-`lucy-pro-i2i` — image-to-image style/editing model used to restyle outfits for the selected weather.
+`lucy-image-2` — image-to-image style/editing model used to restyle outfits for the selected weather.

examples/react-vite-weather-outfit/src/App.tsx

@@ -36,7 +36,7 @@ function App() {
     setResultFile(undefined);
     try {
       const resultBlob = await client.process({
-        model: models.image("lucy-pro-i2i"),
+        model: models.image("lucy-image-2"),
         data: imageFile,
         prompt: `A person wearing an outfit for ${condition.toLowerCase()} conditions`,
       });

examples/react-vite/README.md

@@ -41,8 +41,8 @@ pnpm dev
 
 ## Models
 
-This example uses `mirage_v2` for style transformation. You can also use:
+This example uses `lucy-restyle-2` for style transformation. You can also use:
 
-- `mirage` - MirageLSD video restyling model (older)
-- `lucy_v2v_720p_rt` - Lucy for video editing (add objects, change elements)
-- `lucy_2_rt` - Lucy 2 for video editing with reference image support (better quality)
+- `lucy-restyle` - MirageLSD video restyling model (older)
+- `lucy` - Lucy for video editing (add objects, change elements)
+- `lucy-2` - Lucy 2 for video editing with reference image support (better quality)

examples/react-vite/src/components/VideoStream.tsx

@@ -16,7 +16,7 @@ export function VideoStream({ prompt }: VideoStreamProps) {
 
     async function start() {
       try {
-        const model = models.realtime("mirage_v2");
+        const model = models.realtime("lucy-restyle-2");
 
         setStatus("requesting camera...");
         const stream = await navigator.mediaDevices.getUserMedia({

examples/sdk-core/README.md

@@ -31,15 +31,15 @@ pnpm tsx image/image-to-image.ts
 
 Image models use the synchronous Process API - they return immediately with a Blob.
 
-- `image/image-to-image.ts` - Transform existing image with a prompt (`lucy-pro-i2i`)
+- `image/image-to-image.ts` - Transform existing image with a prompt (`lucy-image-2`)
 
 ### Video Generation
 
 Video models use the asynchronous Queue API - jobs are submitted and polled for completion.
 
-- `video/video-to-video.ts` - Transform existing video with a prompt (`lucy-pro-v2v`)
-- `video/video-editing.ts` - Edit video with prompt, reference image, or both (`lucy-2-v2v`)
-- `video/long-form-video-restyle.ts` - Transform existing video with `lucy-restyle-v2v`
+- `video/video-to-video.ts` - Transform existing video with a prompt (`lucy-clip`)
+- `video/video-editing.ts` - Edit video with prompt, reference image, or both (`lucy-2`)
+- `video/long-form-video-restyle.ts` - Transform existing video with `lucy-restyle-2`
 - `video/manual-polling.ts` - Manual job status polling
 
 ### Realtime (Browser-only)
@@ -64,7 +64,7 @@ See `examples/nextjs-realtime` or `examples/react-vite` for runnable demos.
 ```typescript
 // Image-to-image (edit image with prompt)
 const blob = await client.process({
-  model: models.image("lucy-pro-i2i"),
+  model: models.image("lucy-image-2"),
   prompt: "Transform to watercolor style",
   data: imageBlob,
 });
@@ -75,7 +75,7 @@ const blob = await client.process({
 ```typescript
 // Automatic polling (video-to-video)
 const result = await client.queue.submitAndPoll({
-  model: models.video("lucy-pro-v2v"),
+  model: models.video("lucy-clip"),
   prompt: "Make it look like a watercolor painting",
   data: videoBlob,
   onStatusChange: (job) => console.log(job.status),
@@ -91,7 +91,7 @@ const blob = await client.queue.result(job.job_id);
 
 ```typescript
 const realtimeClient = await client.realtime.connect(stream, {
-  model: models.realtime("mirage_v2"),
+  model: models.realtime("lucy-restyle-2"),
   onRemoteStream: (transformedStream) => { ... },
   initialState: { prompt: { text: "anime style", enhance: true } },
 });
@@ -106,7 +106,7 @@ realtimeClient.disconnect();
 ```typescript
 // Option 1: Use playAudio() to inject audio
 const realtimeClient = await client.realtime.connect(null, {
-  model: models.realtime("live_avatar"),
+  model: models.realtime("live-avatar"),
   onRemoteStream: (videoStream) => { ... },
   initialState: {
     image: "https://example.com/avatar.png",
@@ -118,7 +118,7 @@ await realtimeClient.playAudio(audioBlob);
 // Option 2: Use mic input directly
 const micStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
 const realtimeClient = await client.realtime.connect(micStream, {
-  model: models.realtime("live_avatar"),
+  model: models.realtime("live-avatar"),
   onRemoteStream: (videoStream) => { ... },
   initialState: {
     image: avatarFile,

examples/sdk-core/image/image-to-image.ts

@@ -16,7 +16,7 @@ run(async () => {
   // const referenceImage = fs.readFileSync("reference.png");
 
   const blob = await client.process({
-    model: models.image("lucy-pro-i2i"),
+    model: models.image("lucy-image-2"),
     prompt: "Transform to watercolor painting style",
     data: new Blob([inputImage]),
     // reference_image: new Blob([referenceImage]),

examples/sdk-core/realtime/connection-events.ts

@@ -7,7 +7,7 @@
 import { createDecartClient, type DecartSDKError, models } from "@decartai/sdk";
 
 async function main() {
-  const model = models.realtime("mirage_v2");
+  const model = models.realtime("lucy-restyle-2");
 
   const stream = await navigator.mediaDevices.getUserMedia({
     video: {

examples/sdk-core/realtime/custom-base-url.ts

@@ -7,7 +7,7 @@
 import { createDecartClient, models } from "@decartai/sdk";
 
 async function main() {
-  const model = models.realtime("mirage_v2");
+  const model = models.realtime("lucy-restyle-2");
 
   // Get webcam stream with model-specific settings
   const stream = await navigator.mediaDevices.getUserMedia({

examples/sdk-core/realtime/live-avatar.ts

@@ -10,7 +10,7 @@ import { createDecartClient, models } from "@decartai/sdk";
  * Pass null for stream - the SDK creates an internal audio stream
  */
 async function withPlayAudio() {
-  const model = models.realtime("live_avatar");
+  const model = models.realtime("live-avatar");
 
   const client = createDecartClient({
     apiKey: process.env.DECART_API_KEY!,
@@ -43,7 +43,7 @@ async function withPlayAudio() {
  * Pass user's audio stream - avatar speaks what user says
  */
 async function withMicInput() {
-  const model = models.realtime("live_avatar");
+  const model = models.realtime("live-avatar");
 
   // Get user's microphone stream
   const micStream = await navigator.mediaDevices.getUserMedia({

examples/sdk-core/realtime/lucy-2.1-vton.ts

@@ -0,0 +1,48 @@
+/**
+ * Browser-only example - requires WebRTC APIs
+ * Lucy 2.1 VTON (Virtual Try-On) for realtime garment/outfit transfer
+ * See examples/nextjs-realtime or examples/react-vite for runnable demos
+ */
+
+import { createDecartClient, models } from "@decartai/sdk";
+
+async function main() {
+  const model = models.realtime("lucy-2.1-vton");
+
+  const stream = await navigator.mediaDevices.getUserMedia({
+    audio: true,
+    video: {
+      frameRate: model.fps,
+      width: model.width,
+      height: model.height,
+    },
+  });
+
+  const client = createDecartClient({
+    apiKey: process.env.DECART_API_KEY!,
+  });
+
+  const realtimeClient = await client.realtime.connect(stream, {
+    model,
+    onRemoteStream: (editedStream) => {
+      const video = document.getElementById("output") as HTMLVideoElement;
+      video.srcObject = editedStream;
+    },
+    initialState: {
+      prompt: {
+        text: "Wearing a red leather jacket",
+        enhance: true,
+      },
+    },
+  });
+
+  // Use a reference image of a garment to try on
+  await realtimeClient.set({
+    prompt: "Wearing the outfit from the reference image",
+    image: "https://example.com/outfit-reference.png",
+  });
+
+  console.log("Session ID:", realtimeClient.sessionId);
+}
+
+main();

examples/sdk-core/realtime/lucy-2.1.ts

@@ -0,0 +1,55 @@
+/**
+ * Browser-only example - requires WebRTC APIs
+ * Lucy 2.1 for realtime video editing with reference image + prompt support
+ * See examples/nextjs-realtime or examples/react-vite for runnable demos
+ */
+
+import { createDecartClient, models } from "@decartai/sdk";
+
+async function main() {
+  const model = models.realtime("lucy-2.1");
+
+  const stream = await navigator.mediaDevices.getUserMedia({
+    audio: true,
+    video: {
+      frameRate: model.fps,
+      width: model.width,
+      height: model.height,
+    },
+  });
+
+  const client = createDecartClient({
+    apiKey: process.env.DECART_API_KEY!,
+  });
+
+  const realtimeClient = await client.realtime.connect(stream, {
+    model,
+    onRemoteStream: (editedStream) => {
+      const video = document.getElementById("output") as HTMLVideoElement;
+      video.srcObject = editedStream;
+    },
+    initialState: {
+      prompt: {
+        text: "Add a small dog in the background",
+        enhance: true,
+      },
+    },
+  });
+
+  // set() replaces the full state — prompt + image atomically in a single message
+  await realtimeClient.set({
+    prompt: "A person wearing a superhero costume",
+    enhance: true,
+    image: "https://example.com/superhero-reference.png",
+  });
+
+  // Prompt-only set() clears the reference image.
+  await realtimeClient.set({ prompt: "Add sunglasses to the person" });
+
+  // setPrompt() as syntactic sugar for set() with prompt only
+  realtimeClient.setPrompt("Change the person's shirt to red");
+
+  console.log("Session ID:", realtimeClient.sessionId);
+}
+
+main();

examples/sdk-core/realtime/lucy-2.ts

@@ -7,7 +7,7 @@
 import { createDecartClient, models } from "@decartai/sdk";
 
 async function main() {
-  const model = models.realtime("lucy_2_rt");
+  const model = models.realtime("lucy-2");
 
   const stream = await navigator.mediaDevices.getUserMedia({
     audio: true,

examples/sdk-core/realtime/lucy-v2v-720p.ts

@@ -7,7 +7,7 @@
 import { createDecartClient, models } from "@decartai/sdk";
 
 async function main() {
-  const model = models.realtime("lucy_v2v_720p_rt");
+  const model = models.realtime("lucy");
 
   const stream = await navigator.mediaDevices.getUserMedia({
     audio: true,