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

Add canonical model names (lucy-2, lucy-clip, lucy-restyle-2, lucy-image-2,
live-avatar, etc.) to match the updated API naming convention. Add new models
lucy-2.1 (realtime + batch) and lucy-2.1-vton (realtime). Deprecated model
names still work but now emit a DeprecationWarning guiding users to migrate.

Author: AdirAmsalem

README.md

@@ -34,7 +34,7 @@ async def main():
     async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
         # Edit an image
         result = await client.process({
-            "model": models.image("lucy-pro-i2i"),
+            "model": models.image("lucy-image-2"),
             "prompt": "Apply a painterly oil-on-canvas look while preserving the composition",
             "data": open("input.png", "rb"),
         })
@@ -53,7 +53,7 @@ For video editing jobs, use the queue API to submit jobs and poll for results:
 async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
     # Submit and poll automatically
     result = await client.queue.submit_and_poll({
-        "model": models.video("lucy-pro-v2v"),
+        "model": models.video("lucy-clip"),
         "prompt": "Restyle this footage with anime shading and vibrant neon highlights",
         "data": open("input.mp4", "rb"),
         "on_status_change": lambda job: print(f"Status: {job.status}"),
@@ -72,7 +72,7 @@ Or manage the polling manually:
 async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
     # Submit the job
     job = await client.queue.submit({
-        "model": models.video("lucy-pro-v2v"),
+        "model": models.video("lucy-clip"),
         "prompt": "Add cinematic teal-and-orange grading and gentle film grain",
         "data": open("input.mp4", "rb"),
     })

decart/client.py

@@ -37,14 +37,14 @@ class DecartClient:
 
         # Image editing (sync) - use process()
         image = await client.process({
-            "model": models.image("lucy-pro-i2i"),
+            "model": models.image("lucy-image-2"),
             "prompt": "Apply a painterly oil-on-canvas look while preserving the composition",
             "data": open("input.png", "rb"),
         })
 
         # Video editing (async) - use queue
         result = await client.queue.submit_and_poll({
-            "model": models.video("lucy-pro-v2v"),
+            "model": models.video("lucy-clip"),
             "prompt": "Restyle this footage with anime shading and vibrant neon highlights",
             "data": open("input.mp4", "rb"),
         })
@@ -84,7 +84,7 @@ def queue(self) -> QueueClient:
             ```python
             # Submit and poll automatically
             result = await client.queue.submit_and_poll({
-                "model": models.video("lucy-pro-v2v"),
+                "model": models.video("lucy-clip"),
                 "prompt": "Restyle this footage with anime shading and vibrant neon highlights",
                 "data": open("input.mp4", "rb"),
             })

decart/models.py

@@ -1,19 +1,75 @@
+import warnings
 from typing import Literal, Optional, List, Generic, TypeVar
 from pydantic import BaseModel, Field, ConfigDict, model_validator
 from .errors import ModelNotFoundError
 from .types import FileInput, MotionTrajectoryInput
 
 
-RealTimeModels = Literal["mirage", "mirage_v2", "lucy_v2v_720p_rt", "lucy_2_rt", "live_avatar"]
+RealTimeModels = Literal[
+    # Canonical names
+    "lucy",
+    "lucy-2",
+    "lucy-2.1",
+    "lucy-2.1-vton",
+    "lucy-restyle",
+    "lucy-restyle-2",
+    "live-avatar",
+    # Deprecated names
+    "mirage",
+    "mirage_v2",
+    "lucy_v2v_720p_rt",
+    "lucy_2_rt",
+    "live_avatar",
+]
 VideoModels = Literal[
-    "lucy-pro-v2v",
+    # Canonical names
+    "lucy-clip",
+    "lucy-2",
+    "lucy-2.1",
+    "lucy-restyle-2",
     "lucy-motion",
+    # Deprecated names
+    "lucy-pro-v2v",
     "lucy-restyle-v2v",
     "lucy-2-v2v",
 ]
-ImageModels = Literal["lucy-pro-i2i"]
+ImageModels = Literal[
+    # Canonical names
+    "lucy-image-2",
+    # Deprecated names
+    "lucy-pro-i2i",
+]
 Model = Literal[RealTimeModels, VideoModels, ImageModels]
 
+MODEL_ALIASES: dict[str, str] = {
+    # Realtime aliases
+    "mirage": "lucy-restyle",
+    "mirage_v2": "lucy-restyle-2",
+    "lucy_v2v_720p_rt": "lucy",
+    "lucy_2_rt": "lucy-2",
+    "live_avatar": "live-avatar",
+    # Video aliases
+    "lucy-pro-v2v": "lucy-clip",
+    "lucy-restyle-v2v": "lucy-restyle-2",
+    "lucy-2-v2v": "lucy-2",
+    # Image aliases
+    "lucy-pro-i2i": "lucy-image-2",
+}
+
+_warned_aliases: set[str] = set()
+
+
+def _warn_deprecated(model: str) -> None:
+    canonical = MODEL_ALIASES.get(model)
+    if canonical and model not in _warned_aliases:
+        _warned_aliases.add(model)
+        warnings.warn(
+            f'Model "{model}" is deprecated. Use "{canonical}" instead. '
+            f"See https://docs.platform.decart.ai/models for details.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+
 # Type variable for model name
 ModelT = TypeVar("ModelT", bound=str)
 
@@ -49,6 +105,7 @@ class VideoToVideoInput(DecartBaseModel):
         max_length=1000,
     )
     data: FileInput
+    reference_image: Optional[FileInput] = None
     seed: Optional[int] = None
     resolution: Optional[str] = None
     enhance_prompt: Optional[bool] = None
@@ -121,6 +178,64 @@ class ImageToImageInput(DecartBaseModel):
 
 _MODELS = {
     "realtime": {
+        # Canonical names
+        "lucy": ModelDefinition(
+            name="lucy",
+            url_path="/v1/stream",
+            fps=25,
+            width=1280,
+            height=704,
+            input_schema=BaseModel,
+        ),
+        "lucy-2": ModelDefinition(
+            name="lucy-2",
+            url_path="/v1/stream",
+            fps=20,
+            width=1280,
+            height=720,
+            input_schema=BaseModel,
+        ),
+        "lucy-2.1": ModelDefinition(
+            name="lucy-2.1",
+            url_path="/v1/stream",
+            fps=20,
+            width=1088,
+            height=624,
+            input_schema=BaseModel,
+        ),
+        "lucy-2.1-vton": ModelDefinition(
+            name="lucy-2.1-vton",
+            url_path="/v1/stream",
+            fps=20,
+            width=1088,
+            height=624,
+            input_schema=BaseModel,
+        ),
+        "lucy-restyle": ModelDefinition(
+            name="lucy-restyle",
+            url_path="/v1/stream",
+            fps=25,
+            width=1280,
+            height=704,
+            input_schema=BaseModel,
+        ),
+        "lucy-restyle-2": ModelDefinition(
+            name="lucy-restyle-2",
+            url_path="/v1/stream",
+            fps=22,
+            width=1280,
+            height=704,
+            input_schema=BaseModel,
+        ),
+        "live-avatar": ModelDefinition(
+            name="live-avatar",
+            url_path="/v1/stream",
+            fps=25,
+            width=1280,
+            height=720,
+            input_schema=BaseModel,
+        ),
+        # Deprecated names
         "mirage": ModelDefinition(
             name="mirage",
             url_path="/v1/stream",
@@ -163,40 +278,84 @@ class ImageToImageInput(DecartBaseModel):
         ),
     },
     "video": {
-        "lucy-pro-v2v": ModelDefinition(
-            name="lucy-pro-v2v",
-            url_path="/v1/generate/lucy-pro-v2v",
+        # Canonical names
+        "lucy-clip": ModelDefinition(
+            name="lucy-clip",
+            url_path="/v1/jobs/lucy-clip",
             fps=25,
             width=1280,
             height=704,
             input_schema=VideoToVideoInput,
         ),
+        "lucy-2": ModelDefinition(
+            name="lucy-2",
+            url_path="/v1/jobs/lucy-2",
+            fps=20,
+            width=1280,
+            height=720,
+            input_schema=VideoEdit2Input,
+        ),
+        "lucy-2.1": ModelDefinition(
+            name="lucy-2.1",
+            url_path="/v1/jobs/lucy-2.1",
+            fps=20,
+            width=1088,
+            height=624,
+            input_schema=VideoEdit2Input,
+        ),
+        "lucy-restyle-2": ModelDefinition(
+            name="lucy-restyle-2",
+            url_path="/v1/jobs/lucy-restyle-2",
+            fps=22,
+            width=1280,
+            height=704,
+            input_schema=VideoRestyleInput,
+        ),
         "lucy-motion": ModelDefinition(
             name="lucy-motion",
-            url_path="/v1/generate/lucy-motion",
+            url_path="/v1/jobs/lucy-motion",
             fps=25,
             width=1280,
             height=704,
             input_schema=ImageToMotionVideoInput,
         ),
+        # Deprecated names
+        "lucy-pro-v2v": ModelDefinition(
+            name="lucy-pro-v2v",
+            url_path="/v1/jobs/lucy-pro-v2v",
+            fps=25,
+            width=1280,
+            height=704,
+            input_schema=VideoToVideoInput,
+        ),
         "lucy-restyle-v2v": ModelDefinition(
             name="lucy-restyle-v2v",
-            url_path="/v1/generate/lucy-restyle-v2v",
-            fps=25,
+            url_path="/v1/jobs/lucy-restyle-v2v",
+            fps=22,
             width=1280,
             height=704,
             input_schema=VideoRestyleInput,
         ),
         "lucy-2-v2v": ModelDefinition(
             name="lucy-2-v2v",
-            url_path="/v1/generate/lucy-2-v2v",
+            url_path="/v1/jobs/lucy-2-v2v",
             fps=20,
             width=1280,
             height=720,
             input_schema=VideoEdit2Input,
         ),
     },
     "image": {
+        # Canonical names
+        "lucy-image-2": ModelDefinition(
+            name="lucy-image-2",
+            url_path="/v1/generate/lucy-image-2",
+            fps=25,
+            width=1280,
+            height=704,
+            input_schema=ImageToImageInput,
+        ),
+        # Deprecated names
         "lucy-pro-i2i": ModelDefinition(
             name="lucy-pro-i2i",
             url_path="/v1/generate/lucy-pro-i2i",
@@ -213,6 +372,7 @@ class Models:
     @staticmethod
     def realtime(model: RealTimeModels) -> RealTimeModelDefinition:
         """Get a realtime model definition for WebRTC streaming."""
+        _warn_deprecated(model)
         try:
             return _MODELS["realtime"][model]  # type: ignore[return-value]
         except KeyError:
@@ -225,11 +385,13 @@ def video(model: VideoModels) -> VideoModelDefinition:
         Video models only support the queue API.
 
         Available models:
-            - "lucy-pro-v2v" - Video-to-video
+            - "lucy-clip" - Video-to-video
+            - "lucy-2" - Video editing with reference image support
+            - "lucy-2.1" - Video editing (newer, higher quality)
+            - "lucy-restyle-2" - Video restyling with prompt or reference image
             - "lucy-motion" - Image-to-motion-video
-            - "lucy-restyle-v2v" - Video-to-video with prompt or reference image
-            - "lucy-2-v2v" - Video-to-video editing (long-form, 720p)
         """
+        _warn_deprecated(model)
         try:
             return _MODELS["video"][model]  # type: ignore[return-value]
         except KeyError:
@@ -242,8 +404,9 @@ def image(model: ImageModels) -> ImageModelDefinition:
         Image models only support the process (sync) API.
 
         Available models:
-            - "lucy-pro-i2i" - Image-to-image
+            - "lucy-image-2" - Image-to-image
         """
+        _warn_deprecated(model)
         try:
             return _MODELS["image"][model]  # type: ignore[return-value]
         except KeyError:

decart/queue/client.py

@@ -37,15 +37,15 @@ class QueueClient:
 
         # Option 1: Submit and poll automatically
         result = await client.queue.submit_and_poll({
-            "model": models.video("lucy-pro-v2v"),
+            "model": models.video("lucy-clip"),
             "prompt": "Restyle this clip with anime shading and saturated colors",
             "data": open("input.mp4", "rb"),
             "on_status_change": lambda job: print(f"Status: {job.status}"),
         })
 
         # Option 2: Submit and poll manually
         job = await client.queue.submit({
-            "model": models.video("lucy-pro-v2v"),
+            "model": models.video("lucy-clip"),
             "prompt": "Add cinematic teal-and-orange grading and subtle film grain",
             "data": open("input.mp4", "rb"),
         })

decart/realtime/client.py

@@ -113,7 +113,7 @@ async def connect(
 
         model_name: RealTimeModels = options.model.name  # type: ignore[assignment]
 
-        is_avatar_live = model_name == "live_avatar"
+        is_avatar_live = model_name in ("live_avatar", "live-avatar")
         audio_stream_manager: Optional[AudioStreamManager] = None
 
         if is_avatar_live and local_track is None:

decart/realtime/webrtc_connection.py

@@ -246,7 +246,7 @@ async def on_ice_connection_state_change():
             self._pc.addTransceiver("audio", direction="recvonly")
             logger.debug("Added video+audio transceivers (recvonly) for subscribe mode")
         else:
-            if model_name == "live_avatar":
+            if model_name in ("live_avatar", "live-avatar"):
                 self._pc.addTransceiver("video", direction="recvonly")
                 logger.debug("Added video transceiver (recvonly) for avatar-live mode")
             self._pc.addTrack(local_track)

decart/tokens/client.py

@@ -28,7 +28,7 @@ class TokensClient:
         # With expiry, model restrictions, and constraints:
         token = await client.tokens.create(
             expires_in=120,
-            allowed_models=["lucy_2_rt"],
+            allowed_models=["lucy-2"],
             constraints={"realtime": {"maxSessionDuration": 300}},
         )
         ```
@@ -70,7 +70,7 @@ async def create(
             token = await client.tokens.create(
                 metadata={"role": "viewer"},
                 expires_in=120,
-                allowed_models=["lucy_2_rt"],
+                allowed_models=["lucy-2"],
                 constraints={"realtime": {"maxSessionDuration": 300}},
             )
             ```

examples/README.md

@@ -20,8 +20,8 @@ export DECART_API_KEY="your-api-key-here"
 
 ### Process API
 
-- **`process_video.py`** - Edit a local video with `lucy-pro-v2v`
-- **`process_image.py`** - Edit the bundled example image with `lucy-pro-i2i`
+- **`process_video.py`** - Edit a local video with `lucy-clip`
+- **`process_image.py`** - Edit the bundled example image with `lucy-image-2`
 - **`process_url.py`** - Transform videos from URLs
 - **`queue_image_example.py`** - Turn the bundled example image into motion with `lucy-motion`