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

[AdirAmsalem]

Summary

Adds canonical model names across the SDK to match the updated API naming convention, adds new models, and introduces deprecation warnings for old names.

• New canonical names: lucy-2, lucy-clip, lucy-restyle-2, lucy-image-2, live-avatar, etc. replace the old naming convention (lucy_2_rt, mirage_v2, lucy-pro-v2v, etc.)
• New models: lucy-2.1 (realtime + video) and lucy-2.1-vton (realtime)
• Backwards compatible: Deprecated names still work but emit a one-time DeprecationWarning guiding users to migrate
• lucy-clip: Now supports optional reference_image input

Usage

from decart import DecartClient, models

async with DecartClient() as client:
    # Image editing (canonical name)
    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": "Apply watercolor style",
        "data": open("input.png", "rb"),
    })

    # Video editing (canonical name)
    result = await client.queue.submit_and_poll({
        "model": models.video("lucy-clip"),
        "prompt": "Add anime shading",
        "data": open("input.mp4", "rb"),
    })

    # New lucy-2.1 model
    model = models.realtime("lucy-2.1")

    # Old names still work but warn
    model = models.realtime("mirage_v2")
    # DeprecationWarning: Model "mirage_v2" is deprecated. Use "lucy-restyle-2" instead.

---

Note

Medium Risk
Medium risk because it updates the model registry (names, schemas, and url_paths) and adds deprecation warning behavior that could affect runtime requests and user integrations relying on old model identifiers.

Overview
Updates the SDK to prefer new canonical model names (e.g., lucy-image-2, lucy-clip, lucy-restyle-2, live-avatar) and adds new realtime/video models (lucy-2.1, lucy-2.1-vton) plus "latest" aliases (e.g., lucy-latest).

Introduces one-time DeprecationWarnings for legacy model names via a centralized alias map, while keeping deprecated identifiers usable. Video model definitions are refreshed to use /v1/jobs/... endpoints, and VideoToVideoInput gains optional reference_image support.

Docs, examples, playground, token examples, UI, and tests are updated to use the canonical names and to accept both live_avatar and live-avatar where relevant.

^{Reviewed by Cursor Bugbot for commit 5a0c5e5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a651208. Configure here.}

[cursor]

Overlapping model names bypass queue's category validation

Low Severity

Model names lucy-2, lucy-2.1, and lucy-restyle-2 now exist in both _MODELS["realtime"] and _MODELS["video"]. The queue client validates models via model.name not in _MODELS["video"], so a realtime model definition (with input_schema=BaseModel) would pass this check. Pydantic v2's BaseModel silently ignores extra fields by default (extra='ignore'), so the user's prompt, seed, and other non-file inputs would be silently dropped during validation, sending an incomplete request to the server. Previously, model names were unique across categories, making this impossible.

Additional Locations (1)

• decart/queue/client.py#L84-L93

 

^{Reviewed by Cursor Bugbot for commit a651208. Configure here.}