# Vercel AI SDK
Source: https://docs.platform.decart.ai/ai-frameworks/ai-sdk

Generate images and videos with Decart using the Vercel AI SDK.

The Decart provider for the [Vercel AI SDK](https://ai-sdk.dev/docs) adds image and video generation to any AI SDK project.

## Prerequisites

* A [Decart API key](/getting-started/authentication)
* Node.js 18+
* The `ai` package (`npm i ai`)

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @decartai/ai-sdk-provider
  ```

  ```bash pnpm theme={null}
  pnpm add @decartai/ai-sdk-provider
  ```

  ```bash yarn theme={null}
  yarn add @decartai/ai-sdk-provider
  ```
</CodeGroup>

## Setup

Import the default provider instance:

```typescript theme={null}
import { decart } from '@decartai/ai-sdk-provider';
```

The provider reads your API key from the `DECART_API_KEY` environment variable by default.

Set your Decart API key as an environment variable:

```bash theme={null}
export DECART_API_KEY="your-api-key"
```

Get your API key from [platform.decart.ai](https://platform.decart.ai). See [authentication](/getting-started/authentication) for details.

For custom configuration, use `createDecart()`:

```typescript theme={null}
import { createDecart } from '@decartai/ai-sdk-provider';

const decart = createDecart({
  apiKey: 'your-api-key',
  baseURL: 'https://api.decart.ai',
});
```

<ParamField type="string">
  API key for authentication. Defaults to the `DECART_API_KEY` environment variable.
</ParamField>

<ParamField type="string">
  Custom URL prefix for API calls. Defaults to `https://api.decart.ai`.
</ParamField>

<ParamField type="Record<string, string>">
  Custom headers to include in requests.
</ParamField>

<ParamField type="(input: RequestInfo, init?: RequestInit) => Promise<Response>">
  Custom fetch implementation for intercepting requests or testing.
</ParamField>

## Image generation

Generate images with [`generateImage()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image):

```typescript theme={null}
import { decart } from '@decartai/ai-sdk-provider';
import { generateImage } from 'ai';
import fs from 'fs';

const { image } = await generateImage({
  model: decart.image('lucy-pro-t2i'),
  prompt: 'A golden retriever sitting in a field of wildflowers at sunset',
});

const filename = `image-${Date.now()}.png`;
fs.writeFileSync(filename, image.uint8Array);
console.log(`Image saved to ${filename}`);
```

### Image models

| Model | Description |
| - | - |
| `lucy-pro-t2i` | High-quality text-to-image generation |

### Image settings

<ParamField type="string">
  Aspect ratio of the generated image. Supported values: `16:9` (landscape) and `9:16` (portrait).
</ParamField>

<ParamField type="number">
  Seed value for reproducible results.
</ParamField>

<Note>
  Unsupported aspect ratios generate a warning and fall back to the default behavior.
</Note>

```typescript theme={null}
const { image } = await generateImage({
  model: decart.image('lucy-pro-t2i'),
  prompt: 'A minimalist Japanese garden with cherry blossoms',
  aspectRatio: '16:9',
  seed: 42,
});
```

## Video generation

Generate videos with [`experimental_generateVideo()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-video):

<Note>
  `experimental_generateVideo` is an experimental AI SDK API. The function signature may change in future releases.
</Note>

### Text-to-video

```typescript theme={null}
import { decart } from '@decartai/ai-sdk-provider';
import { experimental_generateVideo as generateVideo } from 'ai';
import fs from 'fs';

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-t2v'),
  prompt: 'A horse galloping through a sunlit meadow',
});

fs.writeFileSync('video.mp4', videos[0].uint8Array);
```

### Video models

| Model | Description |
| - | - |
| `lucy-pro-t2v` | Text-to-video generation |

### Video settings

<ParamField type="string">
  Aspect ratio of the generated video. Supported values: `16:9` (landscape) and `9:16` (portrait).
</ParamField>

<ParamField type="number">
  Seed value for reproducible results.
</ParamField>

<ParamField type="string">
  Video resolution. Supported values: `1280x720` (720p) and `854x480` (480p).
</ParamField>

### Provider options

Pass Decart-specific options via `providerOptions.decart`:

<ParamField type={'"landscape" | "portrait"'}>
  Override orientation directly instead of deriving it from `aspectRatio`.
</ParamField>

## Next steps

<CardGroup>
  <Card title="Models overview" icon="layer-group" href="/getting-started/models">
    Explore all available Decart models.
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript">
    Use Decart's native SDK for full API access.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/DecartAI/ai-sdk-provider">
    View source code and contribute.
  </Card>
</CardGroup>


# LangChain.js
Source: https://docs.platform.decart.ai/ai-frameworks/langchain

Give your LLM agents the ability to generate and edit images with Decart.

The `@decartai/langchain` package provides a [LangChain Tool](https://js.langchain.com/docs/concepts/tools) that gives any LLM agent the ability to generate and edit images using Decart.

## Prerequisites

* A [Decart API key](/getting-started/authentication)
* Node.js 18+
* An LLM provider (Anthropic, OpenAI, etc.) for agent usage

## Installation

Install the package along with the required `@langchain/core` peer dependency:

<CodeGroup>
  ```bash npm theme={null}
  npm install @decartai/langchain @langchain/core
  ```

  ```bash pnpm theme={null}
  pnpm add @decartai/langchain @langchain/core
  ```

  ```bash yarn theme={null}
  yarn add @decartai/langchain @langchain/core
  ```
</CodeGroup>

## Setup

Set your Decart API key as an environment variable:

```bash theme={null}
export DECART_API_KEY="your-api-key"
```

Get your API key from [platform.decart.ai](https://platform.decart.ai). See [authentication](/getting-started/authentication) for details.

Or pass your API key directly to the tool:

```typescript theme={null}
import { DecartImageTool } from '@decartai/langchain';

const tool = new DecartImageTool({ apiKey: 'your-api-key' });
```

## Quick start

### Text-to-image

Generate an image from a text prompt:

```typescript theme={null}
import { DecartImageTool } from '@decartai/langchain';

const tool = new DecartImageTool();

const image = await tool.invoke({
  prompt: 'A serene mountain landscape at sunset',
  resolution: '720p',
});
// Returns: data:image/png;base64,...
```

### Image editing

Edit an existing image by providing an `imageUrl`:

```typescript theme={null}
const editedImage = await tool.invoke({
  prompt: 'Change the sky to aurora borealis',
  imageUrl: 'https://example.com/original.jpg',
});
```

<Tip>
  The tool automatically selects the right model: `lucy-pro-t2i` for text-to-image (no `imageUrl`), and `lucy-image-2` for image-to-image editing (with `imageUrl`).
</Tip>

## Using with LLM agents

Bind the tool to an LLM to let it generate images on its own:

```typescript theme={null}
import { ChatAnthropic } from '@langchain/anthropic';
import { HumanMessage } from '@langchain/core/messages';
import { DecartImageTool } from '@decartai/langchain';

const llm = new ChatAnthropic({ model: 'claude-sonnet-4-20250514' });
const tool = new DecartImageTool();

const llmWithTools = llm.bindTools([tool]);

const response = await llmWithTools.invoke([
  new HumanMessage('Generate an image of a futuristic city at night'),
]);

if (response.tool_calls?.length > 0) {
  const result = await tool.invoke(response.tool_calls[0].args);
  console.log('Generated image:', result);
}
```

<Tip>
  This works with any LangChain-compatible LLM that supports tool calling — including OpenAI, Google, and Mistral models.
</Tip>

## Parameters

<ParamField type="string">
  Text description for image generation, or an edit instruction for image-to-image.
</ParamField>

<ParamField type={'"480p" | "720p"'}>
  Output resolution.
</ParamField>

<ParamField type={'"landscape" | "portrait"'}>
  Output orientation. Only applies to text-to-image generation.
</ParamField>

<ParamField type="number">
  Seed value for reproducible results.
</ParamField>

<ParamField type="string">
  Source image URL for image-to-image editing. When provided, the tool uses `lucy-image-2` instead of `lucy-pro-t2i`.
</ParamField>

<ParamField type="boolean">
  Automatically enhance the prompt for better results.
</ParamField>

## Model selection

The tool selects the model automatically based on your input:

| Input | Model | Mode |
| - | - | - |
| `prompt` only | `lucy-pro-t2i` | Text-to-image generation |
| `prompt` + `imageUrl` | `lucy-image-2` | Image-to-image editing |

## Constructor options

<ParamField type="string">
  Decart API key. Defaults to the `DECART_API_KEY` environment variable.
</ParamField>

<ParamField type="string">
  Custom API base URL.
</ParamField>

## Next steps

<CardGroup>
  <Card title="Models overview" icon="layer-group" href="/getting-started/models">
    Explore all available Decart models.
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript">
    Use Decart's native SDK for full API access.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/DecartAI/langchain-js-decart">
    View source code and contribute.
  </Card>
</CardGroup>


# Frameworks
Source: https://docs.platform.decart.ai/ai-frameworks/overview

Use Decart image and video generation through popular AI frameworks like Vercel AI SDK, TanStack AI, and LangChain.

Use Decart's image and video generation models through the AI framework you already use, instead of integrating with the API directly.

## Choosing a framework

* **Already using Vercel AI SDK?** Use the [AI SDK provider](/ai-frameworks/ai-sdk). It has the most models and the richest feature set.
* **Building with TanStack?** Use the [TanStack AI adapter](/ai-frameworks/tanstack-ai).
* **Using LangChain.js?** Use the [LangChain.js tool](/ai-frameworks/langchain). It also supports image editing and automatic tool calling.
* **Want the most control?** Use [Decart's native JavaScript SDK](/sdks/javascript) directly.

## Prerequisites

All three integrations require a Decart API key. Get yours from [platform.decart.ai](https://platform.decart.ai) — see [authentication](/getting-started/authentication) for setup instructions.

<CardGroup>
  <Card title="Vercel AI SDK" icon="bolt" href="/ai-frameworks/ai-sdk">
    Image and video generation with 5 models.
  </Card>

  <Card title="TanStack AI" icon="layer-group" href="/ai-frameworks/tanstack-ai">
    Image and video generation for TanStack and React apps.
  </Card>

  <Card title="LangChain.js" icon="link" href="/ai-frameworks/langchain">
    Image generation and editing as a tool for LLM agents.
  </Card>
</CardGroup>


# TanStack AI
Source: https://docs.platform.decart.ai/ai-frameworks/tanstack-ai

Generate images and videos with Decart using TanStack AI.

The Decart adapter for [TanStack AI](https://tanstack.com/ai) adds image and video generation to any TanStack project.

<Tip>
  Decart is listed as an [official community adapter](https://tanstack.com/ai/latest/docs/community-adapters/decart) on the TanStack AI docs.
</Tip>

## Prerequisites

* A [Decart API key](/getting-started/authentication)
* Node.js 18+

## Installation

Install both the Decart adapter and TanStack AI:

<CodeGroup>
  ```bash npm theme={null}
  npm install @decartai/tanstack-ai-adapter @tanstack/ai
  ```

  ```bash pnpm theme={null}
  pnpm add @decartai/tanstack-ai-adapter @tanstack/ai
  ```

  ```bash yarn theme={null}
  yarn add @decartai/tanstack-ai-adapter @tanstack/ai
  ```
</CodeGroup>

## Setup

Set your Decart API key as an environment variable:

```bash theme={null}
export DECART_API_KEY="your-api-key"
```

Get your API key from [platform.decart.ai](https://platform.decart.ai). See [authentication](/getting-started/authentication) for details.

Or pass your API key directly when creating adapters:

```typescript theme={null}
import { createDecartImage } from '@decartai/tanstack-ai-adapter';

const adapter = createDecartImage('lucy-pro-t2i', 'your-api-key');
```

## Image generation

Generate images with `generateImage()` and the `decartImage()` adapter:

```typescript theme={null}
import { generateImage } from '@tanstack/ai';
import { decartImage } from '@decartai/tanstack-ai-adapter';

const result = await generateImage({
  adapter: decartImage('lucy-pro-t2i'),
  prompt: 'A serene mountain landscape at sunset, cinematic lighting',
});

console.log(result.images[0].b64Json); // Base64-encoded image data
```

### With explicit API key

Use `createDecartImage()` to pass your API key directly:

```typescript theme={null}
import { generateImage } from '@tanstack/ai';
import { createDecartImage } from '@decartai/tanstack-ai-adapter';

const result = await generateImage({
  adapter: createDecartImage('lucy-pro-t2i', 'your-api-key'),
  prompt: 'A serene mountain landscape at sunset, cinematic lighting',
});
```

## Video generation

Video generation uses an async job and polling pattern — you submit a job, then poll for the result.

<Info>
  Unlike `generateImage()`, video generation is asynchronous. You submit a generation job with `generateVideo()`, then poll its status with `getVideoJobStatus()` until it completes.
</Info>

```typescript theme={null}
import { setTimeout } from 'node:timers/promises';
import { generateVideo, getVideoJobStatus } from '@tanstack/ai';
import { decartVideo } from '@decartai/tanstack-ai-adapter';

const { jobId } = await generateVideo({
  adapter: decartVideo('lucy-pro-t2v'),
  prompt: 'A cat walking through a miniature lego city',
});

let videoUrl: string | undefined;
while (true) {
  const status = await getVideoJobStatus({
    adapter: decartVideo('lucy-pro-t2v'),
    jobId,
  });

  if (status.status === 'failed') {
    throw new Error('Video generation failed');
  }

  if (status.status === 'completed') {
    videoUrl = status.url;
    break;
  }

  await setTimeout(2000);
}

console.log('Video ready:', videoUrl);
```

## Models

| Model | Type | Description |
| - | - | - |
| `lucy-pro-t2i` | Text-to-image | High-quality image generation |
| `lucy-pro-t2v` | Text-to-video | Video generation from text prompts |

## Options

<ParamField type="number">
  Seed value for reproducible results.
</ParamField>

<ParamField type={'"720p" | "480p"'}>
  Output resolution. Defaults to `720p`.
</ParamField>

## Next steps

<CardGroup>
  <Card title="Models overview" icon="layer-group" href="/getting-started/models">
    Explore all available Decart models.
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript">
    Use Decart's native SDK for full API access.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/DecartAI/tanstack-ai-adapter">
    View source code and contribute.
  </Card>
</CardGroup>


# Create Client Token
Source: https://docs.platform.decart.ai/api-reference/create-client-token

/openapi.json post /v1/client/tokens
Create an ephemeral API token for client sessions.



# Delete File
Source: https://docs.platform.decart.ai/api-reference/delete-file

/openapi.json delete /v1/files/{file_id}
Delete an uploaded file early, before its TTL expires.



# Get File By MD5
Source: https://docs.platform.decart.ai/api-reference/get-file-by-md5

/openapi.json get /v1/files/by-md5/{md5}
Look up an uploaded file by the MD5 of its bytes, without knowing its `file_*` id. Returns the newest non-expired match when the same file was uploaded more than once. Compute the hash over the exact bytes you uploaded (for example `md5sum image.png`).



# Get File Metadata
Source: https://docs.platform.decart.ai/api-reference/get-file-metadata

/openapi.json get /v1/files/{file_id}
Get metadata for an uploaded file.



# Get Job
Source: https://docs.platform.decart.ai/api-reference/get-job

/openapi.json get /v1/jobs/{job_id}
Get the status and metadata of a job by its ID. Poll this endpoint to check if your job has completed.



# Get Job Content
Source: https://docs.platform.decart.ai/api-reference/get-job-content

/openapi.json get /v1/jobs/{job_id}/content
Download the result of a completed job.

Returns:
    Binary content (image/video) or error if not ready/not found



# Get Realtime Quota
Source: https://docs.platform.decart.ai/api-reference/get-realtime-quota

/openapi.json get /v1/realtime/quota
Current concurrent realtime session quota state for the authenticated account.

For org-scoped keys the count is org-wide (shared across the org's keys/users).

`active` is a live counter, not a periodic aggregate: a session is counted the moment its connection is authenticated and released the moment it closes, so a read reflects a connect or disconnect within about a second. If one of our gateway instances crashes mid-session, its sessions can stay counted for up to 45 seconds before they expire.

Use this endpoint for coarse pre-flight checks and dashboards: poll at most once per second and stay under 10 requests per second per API key. `remaining` is advisory, since other sessions can start between your read and your connect, so always handle the connect-time rejection (WebSocket close code 1013, "Concurrent session limit reached.").



# List Files
Source: https://docs.platform.decart.ai/api-reference/list-files

/openapi.json get /v1/files
List your uploaded files, newest first. Expired files are omitted, as they 404 on `GET /v1/files/{file_id}`.

Pages continue from the last file returned rather than from an offset, so an upload or delete between requests never repeats or skips a file. Pass the previous page's `next_cursor` as `cursor`; the last page has `next_cursor: null`.



# Lucy 2.1
Source: https://docs.platform.decart.ai/api-reference/lucy-21

/openapi.json post /v1/jobs/lucy-2.1
Edit video using Lucy 2.1 model with optional prompt and reference image.



# Lucy 2.5
Source: https://docs.platform.decart.ai/api-reference/lucy-25

/openapi.json post /v1/jobs/lucy-2.5
Edit video using Lucy 2.5 model with optional prompt and reference image. Supports self-anchoring (on by default).



# Lucy Image 2
Source: https://docs.platform.decart.ai/api-reference/lucy-image-2

/openapi.json post /v1/generate/lucy-image-2
Edit image from image using Lucy Image 2 model.



# Lucy Image Latest
Source: https://docs.platform.decart.ai/api-reference/lucy-image-latest

/openapi.json post /v1/generate/lucy-image-latest
Edit image from image using the latest Lucy Image model.



# Lucy Latest
Source: https://docs.platform.decart.ai/api-reference/lucy-latest

/openapi.json post /v1/jobs/lucy-latest
Edit video using the latest Lucy video model with optional prompt and reference image.



# Lucy Restyle 2
Source: https://docs.platform.decart.ai/api-reference/lucy-restyle-2

/openapi.json post /v1/jobs/lucy-restyle-2
Restyle video using Lucy Restyle 2 model.



# Lucy Restyle Latest
Source: https://docs.platform.decart.ai/api-reference/lucy-restyle-latest

/openapi.json post /v1/jobs/lucy-restyle-latest
Restyle video using the latest Lucy Restyle model.



# Lucy VTON 3.5
Source: https://docs.platform.decart.ai/api-reference/lucy-vton-35

/openapi.json post /v1/jobs/lucy-vton-3.5
Edit video with virtual try-on using the Lucy VTON 3.5 model.



# Lucy VTON 3.6
Source: https://docs.platform.decart.ai/api-reference/lucy-vton-36

/openapi.json post /v1/jobs/lucy-vton-3.6
Edit video with virtual try-on using the Lucy VTON 3.6 model.



# Lucy VTON Latest
Source: https://docs.platform.decart.ai/api-reference/lucy-vton-latest

/openapi.json post /v1/jobs/lucy-vton-latest
Edit video with virtual try-on using the latest Lucy VTON model.



# Resolve Model Aliases
Source: https://docs.platform.decart.ai/api-reference/resolve-model-aliases

/openapi.json post /v1/models/resolve
Resolve one or more public model names/aliases to canonical model ids.



# Upload File
Source: https://docs.platform.decart.ai/api-reference/upload-file

/openapi.json post /v1/files
Upload a file once and get back a `file_*` reference id you can reuse across generations.

The same reference can be passed to realtime `set_image` as `image_ref`, avoiding a re-upload of the underlying bytes on every call.



# Changelog
Source: https://docs.platform.decart.ai/changelog

Product updates and announcements for the Decart API Platform

<Update label="October 2026">
  ## Fresh Client Tokens on Every Realtime Dial, Lucy VTON 3.6 (Now Latest, with Fast Mode) & One API Hostname

  * **Fresh client tokens on every realtime dial** - Client tokens expire 60 seconds after minting by default, so a token minted on page load was often refused by the time the user pressed start, and a reconnect with the same token failed with a generic connection error. `createDecartClient` in the [JavaScript](/sdks/javascript-realtime#client-side-authentication) SDK (v0.2.6) now accepts `apiKeyProvider`, a function the SDK calls right before every connect, reconnect and subscribe, so each dial carries a token minted for it. An already-expired token is rejected with `TOKEN_EXPIRED` before any socket is opened. The Studio playgrounds use the same pattern. See [Token lifetime](/getting-started/client-tokens#token-lifetime)
  * **Lucy VTON 3.6** - New virtual try-on model (`lucy-vton-3.6`) available on realtime and batch surfaces, at 720p. It is **opt-in by name**: `lucy-vton-latest` continues to resolve to `lucy-vton-3.5`. Unlike 3.5, `lucy-vton-3.6` does not offer [fast mode](/models/realtime/lucy-2.5#fast-mode) — `speed: "fast"` is ignored and the session is billed at the standard rate. Available across [JavaScript](/sdks/javascript) (v0.2.7), [Python](/sdks/python), [Android](/sdks/android), and [Swift](/sdks/swift) SDKs, and selectable from the Virtual Try-On playground's version dropdown. See the [Prompting Guide](/models/realtime/vton-3.5-prompting) and [Pricing](/getting-started/pricing#realtime-models)
  * **Lucy VTON 3.6 is now the latest, with fast mode** - `lucy-vton-latest` now resolves to `lucy-vton-3.6`, and 3.6 now supports [fast mode](/models/realtime/virtual-try-on#fast-mode) (`speed: "fast"`, billed at 2x the standard realtime rate, \$0.04/sec) on the realtime surface. `lucy-vton-3.5` remains available by name, with fast mode. The Virtual Try-On playground now defaults to 3.6 on both surfaces, and its Fast mode toggle is available on either version. The SDKs list `fast` among `lucy-vton-3.6`'s supported speeds from their next release. See [Pricing](/getting-started/pricing#realtime-models)
  * **One API hostname** - `api.decart.ai` now serves realtime signaling (WebSocket) as well as the REST API, and is the only hostname the docs and SDK defaults use. `api3.decart.ai` keeps working indefinitely for existing integrations; new integrations and firewall allowlists only need `api.decart.ai`. See [Network Requirements](/integrations/network-requirements#domains-to-allow-production)
</Update>

<Update label="September 2026">
  ## Realtime Fast Mode, Lucy VTON 2 and 3 Retirement, Signed Client Tokens & Network Requirements Guide

  * **Realtime fast mode** - Pass `speed: "fast"` when connecting to `lucy-2.5` / `lucy-latest` or `lucy-vton-3.5` / `lucy-vton-latest` for lower latency and higher throughput; output quality is unchanged. Billed at 2x the standard realtime rate (\$0.04/sec). Other models ignore the option; omit it for standard mode. Available across [JavaScript](/sdks/javascript-realtime#fast-mode) (v0.2.2), [Python](/sdks/python-realtime#fast-mode) (v0.2.1), [Android](/sdks/android-realtime#fast-mode) (0.8.1), and [Swift](/sdks/swift-realtime#fast-mode) (v0.7.1) SDKs. The Studio playground gains a matching **Fast mode** switch. See [Fast mode](/models/realtime/lucy-2.5#fast-mode) and [Pricing](/getting-started/pricing#realtime-models)
  * **Lucy VTON 2 and 3 retirement** - `lucy-vton-2` and `lucy-vton-3` (and the `lucy-2.1-vton-2` alias) are retired and no longer served. Use `lucy-vton-3.5`, or `lucy-vton-latest` which resolves to it. The ids are removed from the [JavaScript SDK](/sdks/javascript) as of v0.2.0
  * **Signed client tokens** - Client tokens from `POST /v1/client/tokens` are now signed, and the gateway verifies them offline against the platform's public JWKS. Realtime connections, file uploads, and batch and queue calls no longer wait on a key lookup. Pass the returned `apiKey` to the SDK as before; no client changes needed. See [Client Tokens](/getting-started/client-tokens)
  * **Network requirements guide** - New reference for IT, networking, and security teams deploying the realtime SDK, covering supported OS and hardware, per-session bandwidth, connection-quality thresholds, and the domains and ports that must be allowed through corporate firewalls. See [Network Requirements](/integrations/network-requirements)
</Update>

<Update label="August 2026">
  ## Preset Studio, Automatic Glass-to-Glass & Lucy VTON 3.5

  * **Preset Studio** - New hub at [platform.decart.ai/studio](https://platform.decart.ai/studio) to save, organize, share, and version reusable prompts and reference images. Apply presets across supported model playgrounds, share within an organization, and restore earlier versions from version history. See the [Preset Studio guide](/getting-started/preset-studio)
  * **Automatic glass-to-glass in JavaScript realtime** - The [JavaScript](/sdks/javascript-realtime#glass-to-glass-latency) SDK (v0.1.21) now measures glass-to-glass latency automatically via LiveKit frame metadata — read `glassToGlass.ttffMs` / `.medianMs` off the `stats` event. `debugQuality: true` is a deprecated no-op
  * **Lucy VTON 3.5** - New latest-generation virtual try-on model (`lucy-vton-3.5`) available on realtime and batch surfaces, at 720p. `lucy-vton-latest` now resolves to `lucy-vton-3.5`. Available across [JavaScript](/sdks/javascript) (v0.1.19), [Python](/sdks/python) (v0.1.5), [Android](/sdks/android) (0.7.10), and [Swift](/sdks/swift) (v0.6.10) SDKs. See the [VTON 3.5 Prompting Guide](/models/realtime/vton-3.5-prompting)
</Update>

<Update label="July 2026">
  ## Lucy 2.5

  * **Lucy 2.5** - New latest-generation video editing model (`lucy-2.5`) available on realtime and batch surfaces. `lucy-latest` now resolves to `lucy-2.5`. The previous `lucy-2.1` remains live for pinned integrations. Supports text prompts, reference images, or both. See the [Lucy 2.5 guide](/models/realtime/lucy-2.5)
</Update>

<Update label="June 2026">
  ## Oasis 3 Preview, Realtime Quality & Python LiveKit

  * **Oasis 3 Preview** - New realtime, promptable world model (`oasis-3-preview`): set a scene with a text prompt, stream driving actions (throttle + steering), and receive generated camera frames in realtime — a learned driving simulator you can run reinforcement learning in. Available via the dedicated [`decart-oasis`](https://pypi.org/project/decart-oasis/) Python gRPC SDK. See the [Oasis 3 Preview guide](/models/realtime/oasis-3) and the [RL training notebook](https://colab.research.google.com/github/DecartAI/decart-robotics/blob/main/notebook/train_oasis3_ppo_colab.ipynb), or try it live at [oasis3-preview.decart.ai](https://oasis3-preview.decart.ai)
  * **Lucy VTON 3** - New latest-generation virtual try-on model (`lucy-vton-3`) available on realtime and batch surfaces. `lucy-vton-latest` now resolves to `lucy-vton-3`. The previous `lucy-vton-2` remains live for pinned integrations. Available across [JavaScript](/sdks/javascript) (v0.1.5), [Python](/sdks/python) (v0.0.40), [Android](/sdks/android) (0.7.4), and [Swift](/sdks/swift) (v0.6.3) SDKs
  * **Lucy 2.1 VTON retirement** - `lucy-2.1-vton` and its `lucy-vton` alias are no longer served. Use `lucy-vton-3`, `lucy-vton-latest`, or pin to `lucy-vton-2` if you need the previous generation
  * **Connection quality, preflight & glass-to-glass latency** - Realtime SDKs now report network health on a shared `good | fair | poor | critical` scale. Run a preflight before connecting (`checkConnectivity()`) to gate the integration, react to in-session quality (`onConnectionQuality`) with the limiting factor (bandwidth, latency, loss, stall, cpu), or opt in to glass-to-glass latency (`debugQuality: true`) to measure real camera→display latency end-to-end. Available in [JavaScript](/sdks/javascript-realtime#connection-quality) (v0.1.6), [Android](/sdks/android-realtime#connection-quality) (0.7.5), and [Swift](/sdks/swift-realtime#connection-quality) (v0.6.4)
  * **Python realtime SDK moved to LiveKit** - The [Python](/sdks/python-realtime) realtime SDK (v0.1.0) completes the LiveKit migration after JavaScript, Android, and Swift. Input is now a caller-supplied `livekit.rtc.LocalVideoTrack`, `on_remote_stream` receives a `livekit.rtc.RemoteVideoTrack`, and a new `preferred_video_codec` option picks between `h264` (default) and `vp9`. Install with `pip install decart[realtime]`
</Update>

<Update label="May 2026">
  ## 1080p Realtime & Mobile Mirroring

  * **1080p realtime streams** - New `resolution` option on `realtime.connect()` lets supported models deliver 1080p output. Available across [JavaScript](/sdks/javascript-realtime) (v0.0.68), [Python](/sdks/python-realtime) (v0.0.39), [Android](/sdks/android-realtime) (0.6.1), and [Swift](/sdks/swift-realtime) (v0.6.1) SDKs. Defaults to 720p when omitted
  * **Front-camera mirroring on iOS & Android** - New `mirror` option pre-flips selfie input so server-baked pixels (watermarks, overlays) render correctly without re-flipping on the receiving end. Now available on [Android](/sdks/android-realtime#front-camera-mirroring) (0.6.0) and [Swift](/sdks/swift-realtime#front-camera-mirroring) (v0.6.0), in addition to JavaScript
  * **Lucy VTON 2** - New next-generation virtual try-on model (`lucy-vton-2`) available on realtime and batch surfaces. `lucy-vton-latest` now resolves to `lucy-vton-2`
  * **Origin-scoped client tokens** - New `allowedOrigins` option on `client.tokens.create()` pins a client token to a list of canonical web origins; mismatched browser-issued `Origin` headers are rejected at the realtime gateway. Available in the [JavaScript](/sdks/javascript) SDK (v0.0.63) and the [Python](/sdks/python) SDK (v0.0.37). See [Client Tokens → Origin scoping](/getting-started/client-tokens#origin-scoping)
  * **Model retirements** - LipSync Live, Live Avatar, Lucy Motion, Lucy v1 Realtime, and Lucy Restyle v1 Realtime are no longer served by the API. Their docs pages now redirect to the relevant category overviews and the SDKs no longer surface their model IDs. Migrate to `lucy-2.1` (realtime + batch editing) or `lucy-restyle-2` (realtime + batch restyling)
  * **Custom models in the Python SDK** - The Python SDK now accepts an inline `ModelDefinition` for preview, experimental, or private models that aren't in the built-in registry — matching the JavaScript SDK's `CustomModelDefinition`
  * **Realtime SDKs now LiveKit-backed** - The realtime media transport in the [JavaScript](/sdks/javascript-realtime) (v0.1.0) and [Android](/sdks/android-realtime) (0.7.0) SDKs moved to a LiveKit-managed WebRTC session for better reliability and to power LiveKit-based session subscribe; [Swift](/sdks/swift-realtime) followed in v0.6.2 in early June. The `connect()` interface is unchanged, but Android's `setPrompt` is now a `suspend` function — callers must invoke it from a coroutine and handle thrown ack failures
  * **Files API for realtime reference images** - The [JavaScript SDK](/sdks/javascript-realtime) (v0.1.1) lets you upload a reference image once via `client.files.upload(...)` and pass the resulting `file_…` id by reference to `connect()` / `set()` / `setImage()`, instead of re-encoding the asset on every call
  * **Enterprise SSO for organizations** - Organizations can now sign in via their corporate identity provider (Okta, Entra, Google Workspace, or any OIDC IdP). Org owners and admins self-serve provider registration and DNS TXT domain verification from organization settings; new SSO sign-ins are JIT-provisioned into the organization as members
</Update>

<Update label="April 2026">
  ## Lucy 2.1, Virtual Try-On & Team Accounts

  * **Lucy 2.1** - New flagship realtime and batch video editing model (`lucy-2.1`). Available across [JavaScript](/sdks/javascript), [Python](/sdks/python), [Android](/sdks/android), and [Swift](/sdks/swift) SDKs
  * **Virtual Try-On** - Launched [`lucy-2.1-vton`](/models/realtime/virtual-try-on) for realtime and batch virtual try-on, with a new e-commerce integration guide
  * **Canonical SDK model names** - Unified model naming across all SDKs (e.g. `lucy-2.1`, `lucy-image-2`, `lucy-restyle-2`, `lucy-clip`, `live-avatar`) with deprecation warnings for legacy names
  * **`-latest` aliases** - Use `lucy-latest`, `lucy-vton-latest`, `lucy-restyle-latest`, `lucy-clip-latest`, `lucy-motion-latest`, or `lucy-image-latest` to automatically target the newest model version without code changes
  * **Reference images for image editing** - Added `reference_image` (file or URL) support to `lucy-image-2` for image-to-image editing
  * **Team accounts** - Create organizations with shared credits and billing, invite members by email, manage roles and ownership transfer, and scope API keys to an organization
  * **Auto top-up credits** - Save a Stripe payment method and automatically refill credits when your balance drops below a threshold (now also available for organizations)
  * **Billing portal & receipts** - Manage payment methods and invoices through a hosted Stripe portal, and download receipts directly from a redesigned transaction history
  * **API Terms of Service & DPA** - Published formal [API Terms of Service](/resources/api-terms) and [Data Processing Addendum](/resources/dpa)
  * **Realtime Playground** - Added a mobile version selector and improved auto-sent image handling
</Update>

<Update label="March 2026">
  ## Client Tokens v2, Android SDK & Model Simplification

  * **Client tokens v2** - [Client tokens](/getting-started/client-tokens) now support configurable TTL, model scoping, and per-session constraints for finer-grained client-side access control
  * **Android SDK** - Published the [Decart Android SDK](/sdks/android) with realtime ([`android-realtime`](/sdks/android-realtime)) and batch ([`android-queue`](/sdks/android-queue)) APIs, upload progress callbacks, and Android code snippets across the Lucy 2 docs
  * **LipSync Live pricing and guides** - Added full pricing and a complete guide for realtime lip syncing
  * **Simpler model names** - Renamed models across docs and the platform with consistent naming, and separated flagship from legacy models in the sidebar
  * **Lucy Edit consolidation** - Unified Lucy Edit v1 and v2 into a single docs page with a version selector
  * **Mirage → Lucy Restyle Live** - Renamed Mirage to Lucy Restyle Live across docs, the platform, and all SDKs
</Update>

<Update label="February 2026">
  ## Realtime SDK Overhaul & Lucy 2

  * **Lucy 2 Realtime** - Launched Lucy 2 (`lucy-2`), a new realtime video-to-video model with character reference image support
  * **Session viewing** - Other clients can now watch an active realtime session as read-only viewers using a [subscribe token](/sdks/javascript-realtime#session-viewing-subscribe)
  * **Unified `set()` method** - Atomically replace session state (prompt and reference image) in a single call across [JavaScript](/sdks/javascript-realtime#unified-state-update) and [Python](/sdks/python-realtime#unified-state-update) SDKs
  * **Auto-reconnect** - Realtime SDKs now automatically reconnect with exponential backoff when connections drop
  * **`generationTick` event** - Track session duration and billing with a new periodic event during generation
  * **New connection states** - Added `"generating"` and `"reconnecting"` states for better lifecycle visibility
</Update>

<Update label="January 2026">
  ## Lucy 2 RT Preview, Reference Images & Avatar Live

  * **Lucy 2 RT (Preview)** - Early access to Lucy 2 realtime at 720p\@20FPS
  * **Reference images** - Added reference image support for Lucy Restyle Live, Lucy Restyle, Lucy Pro, and Lucy Edit models in realtime
  * **Avatar Live** - New model for audio-driven avatar animation with MP3 support
  * **Server proxy** - New [server proxy integration](/sdks/javascript) and Next.js proxy adapter for backend-to-backend SDK usage
  * **React Native support** - JavaScript SDK now supports file uploads from React Native
  * **Python 3.10+** - Python SDK now requires Python 3.10 or later
</Update>

<Update label="December 2025">
  ## Lucy Restyle & Client Tokens

  * **Lucy Restyle** - New video restyling model (`lucy-restyle-2`) for transforming video aesthetics with up to 30-minute input
  * **Client tokens** - New [client tokens API](/getting-started/client-tokens) for secure short-lived token creation in client-side apps
    * **Unified generate endpoint** - All model generation consolidated into a single API route
    * **Image cropping** - Crop uploaded images before processing in the Studio
    * **Reduced image pricing** - Lower pricing for image generation models
</Update>

<Update label="November 2025">
  ## Queue API & AWS Marketplace

  ### New Features

  * **Queue-based API** - Introduced queue API pattern for video generation, enabling better handling of long-running jobs
  * **AWS Marketplace** - Decart API Platform is now available on [AWS Marketplace](https://aws.amazon.com/marketplace) with integrated billing
  * **Showcase page** - Added a new showcase page highlighting community creations and use cases
  * **Lucy Fast** - Added Lucy Edit Fast model for quicker video-to-video transformations

  ### API & SDK Updates

  * Updated model routes and code examples for job submission workflow
  * Improved error messages when content violates Terms of Service
  * Updated video pricing for 720p resolution

  ### Platform Improvements

  * Enhanced billing page with AWS Marketplace support
  * Improved credits reserve and deduction logic
  * Better video expand functionality in the video player
</Update>

<Update label="October 2025">
  ## Lip Syncing, Motion & Platform Redesign

  ### New Features

  * **Lip Syncing** - Added realtime lip-syncing capabilities to sync audio with video
  * **Lucy Motion** - Introduced Lucy Motion model for object animation and movement
  * **Lucy Restyle Live v2** - Upgraded to Lucy Restyle Live v2 as the default realtime model with improved quality
  * **Video recording** - Added ability to record sessions directly in the Realtime Playground

  ### Platform Redesign

  * Launched redesigned homepage with improved navigation
  * New model page in Studio with better organization
  * Redesigned sign-in page and authentication flow
  * Mobile-optimized Realtime Playground experience
  * Renamed "Studio" to "Models" for clarity

  ### SDK & Documentation

  * Released [Python SDK](/sdks/python) documentation
  * Added [Swift SDK](/sdks/swift) for iOS development
  * Added comprehensive lip-syncing documentation
  * Upgraded to Next.js 16 for improved performance

  ### Developer Experience

  * Idle detection with warning dialog in Realtime Playground
  * Improved ephemeral API key handling
  * Added preset functionality for quick model configuration
  * GDPR-compliant analytics with consent management
</Update>


# Lucy Edit In ComfyUI
Source: https://docs.platform.decart.ai/examples/comfyui

Lucy Edit ComfyUI Cookbook: Text-Guided Video Editing

## Lucy Edit transforms videos with text prompts while preserving motion

Lucy Edit is a video editing model that performs instruction-guided edits on videos using free-text prompts. The model supports clothing changes, character replacements, object insertions, and scene transformations while preserving the original motion and composition perfectly. This cookbook shows you how to set up and use Lucy Edit in ComfyUI for professional video editing results.

## What Lucy Edit does best

**Motion preservation keeps videos smooth.** Lucy Edit maintains the original motion and composition of your videos perfectly, allowing precise edits without disrupting the flow.

**Edit reliability improves over other methods.** Compared to common inference time methods, Lucy Edit produces more robust and consistent edits.

**Identity conservation maintains character features.** When changing clothing or accessories, the model preserves the subject's identity and facial features.

**No masks or finetuning needed.** Pure text instructions drive all edits—you don't need to create masks or finetune models for common editing tasks.

## Installation takes three steps

### Step 1: Clone the repository into ComfyUI

Navigate to your ComfyUI's custom\_nodes folder and clone the Lucy Edit repository:

```bash theme={null}
cd ComfyUI/custom_nodes
git clone https://github.com/DecartAI/lucy-edit-comfyui.git
```

### Step 2: Install Python dependencies

Install the required Python packages:

```bash theme={null}
cd lucy-edit-comfyui
pip install -r requirements.txt
```

### Step 3: Download model weights

**Choose the right weights for your system.** Download either FP16 (smaller, faster) or FP32 (full precision) weights based on your hardware capabilities:

* **FP16 weights (recommended for most users):**
  [https://huggingface.co/decart-ai/Lucy-Edit-Dev-ComfyUI/resolve/main/lucy-edit-dev-cui-fp16.safetensors](https://huggingface.co/decart-ai/Lucy-Edit-Dev-ComfyUI/resolve/main/lucy-edit-dev-cui-fp16.safetensors)

* **FP32 weights (for maximum precision):**
  [https://huggingface.co/decart-ai/Lucy-Edit-Dev-ComfyUI/resolve/main/lucy-edit-dev-cui.safetensors](https://huggingface.co/decart-ai/Lucy-Edit-Dev-ComfyUI/resolve/main/lucy-edit-dev-cui.safetensors)

Place the downloaded weights in: `ComfyUI/models/diffusion_models/`

## Two ways to run Lucy Edit

### Option 1: Lucy Edit Pro uses the API for faster processing

**API processing offloads computation.** Lucy Edit Pro runs on Decart's servers, requiring no local GPU resources.

1. Load the workflow from `examples/basic-api-lucy-edit.json`
2. Get an API key from [https://platform.decart.ai/](https://platform.decart.ai/)
3. Enter your API key in the workflow node
4. Upload your video and enter your edit prompt
5. Run the workflow to process your edit

### Option 2: Lucy Edit Dev runs entirely on your machine

**Local processing gives you full control.** Lucy Edit Dev runs on your hardware, ideal for sensitive content or offline work.

1. Load the workflow from `examples/basic-lucy-edit-dev.json`
2. Ensure model weights are in the correct folder
3. Upload your video and enter your edit prompt
4. Run the workflow to process locally

**System requirements for local processing:**

* GPU with at least 16GB VRAM (24GB recommended)
* 32GB system RAM minimum
* CUDA-compatible graphics card

## Six types of edits you can make

### 1. Clothing changes work best

**Lucy Edit excels at wardrobe swaps.** The model performs clothing changes with the highest accuracy and consistency.

Write clothing prompts with specific details:

* ✅ "Change the shirt to a silk kimono with wide sleeves and cherry blossom patterns"
* ❌ "Change clothes"

Include material, fit, and style details for best results. Describe textures (silk, leather, denim), patterns (stripes, florals), and fit (loose, tight, flowing).

### 2. Character replacements transform subjects reliably

**Replace humans with creatures or characters.** This edit type works well for transforming people into animals, monsters, or fictional characters.

Effective character replacement prompts:

* ✅ "Replace the person with a Bengal tiger, striped orange fur, muscular build, alert ears"
* ✅ "Replace the woman with an anime character, large expressive eyes, blue hair, school uniform"
* ❌ "Make them a tiger"

Describe physical characteristics, textures, and distinctive features. Avoid pronouns like "him" or "her"—use "person," "man," or "woman" instead.

### 3. Object replacements maintain structure

**Swap objects while preserving size and position.** Object replacement works best when the new object has similar dimensions to the original.

Structure-preserving object swaps:

* ✅ "Replace the apple with a crystal ball, clear glass, internal light refractions, palm-sized"
* ✅ "Replace the coffee cup with a medieval goblet, pewter metal, ornate engravings"
* ❌ "Change the apple"

Keep replacement objects plausible in scale and context. A handheld item should replace another handheld item.

### 4. Color changes need precise descriptions

**Color edits show mixed reliability.** Some color changes are subtle, others dramatic. Detailed descriptions improve consistency.

Color change prompts that work:

* ✅ "Change the jacket color to deep burgundy leather with matte finish"
* ✅ "Change the car paint to metallic silver with mirror-like reflections"
* ❌ "Make it red"

Specify the exact shade, material properties, and finish (matte, glossy, metallic).

### 5. Adding objects works for wearables and props

**Added items often attach to subjects.** This edit type works best for accessories, handheld items, or wearable objects.

Successful object additions:

* ✅ "Add aviator sunglasses on the person's face, gold frames, reflective lenses"
* ✅ "Add a leather backpack on the person's shoulders, brown, worn texture"
* ⚠️ "Add a floating balloon" (may attach to person instead of floating)

Specify exactly where the object should appear and how it connects to the scene.

### 6. Global transformations change entire scenes

**Scene-wide changes may alter subjects.** Transform backgrounds, lighting, or artistic style—but be aware this can affect character identity.

Global transformation examples:

* ✅ "Transform the sunny beach into a snowy winter scene, falling snowflakes, overcast sky"
* ✅ "Transform to 2D cartoon style, bold outlines, flat colors, cel-shaded appearance"
* ⚠️ May change subject appearance along with the scene

Use global transformations when you want comprehensive scene changes. For preserving subjects while changing backgrounds, combine with specific preservation instructions.

## Write prompts that get better results

### Start every prompt with the right trigger word

**Trigger words tell the model your intent.** Beginning with the correct trigger word improves edit accuracy:

* **"Change"** → Clothing or color modifications
* **"Add"** → Adding accessories or objects
* **"Replace"** → Subject or object substitution
* **"Transform"** → Global scene or style changes

### Include 20-30 descriptive words for best results

**Details improve edit precision.** Short prompts like "change shirt to red" produce generic results. Rich descriptions yield professional edits.

Compare these prompts:

* Basic: "Change shirt to kimono"
* Better: "Change the shirt to a silk kimono with deep indigo dye, wide flowing sleeves, subtle crane pattern embroidery, loose fit, soft drape, natural folds"

### Describe materials, textures, and visual properties

**Concrete visual details guide the model.** Include:

* Materials (silk, leather, cotton, metal)
* Textures (fuzzy, smooth, rough, glossy)
* Patterns (stripes, florals, geometric)
* Lighting (soft, harsh, dramatic)
* Scale and positioning
* Colors with modifiers (deep, pale, vibrant)

### Avoid these common prompt mistakes

**Don't mention what to preserve.** The model already preserves motion and pose—mentioning it can confuse the edit.

* ❌ "Change the shirt to red while preserving the pose"
* ✅ "Change the shirt to bright red cotton with ribbed texture"

**Don't use personal pronouns.** Replace "me," "him," "her" with specific descriptors.

* ❌ "Replace me with a robot"
* ✅ "Replace the person with a chrome robot"

**Don't reference specific people.** Avoid mentioning hair color or identifying features.

* ❌ "Change the blonde woman's dress"
* ✅ "Change the dress to emerald green silk"

## Troubleshooting common issues

### Edit not applying strongly enough

**Increase prompt detail.** Add more descriptive words about materials, textures, and visual properties. Consider adjusting the guidance scale in your ComfyUI workflow.

### Motion becoming unstable

**Use 81-frame generations.** Longer clips (81 frames) produce better temporal consistency than shorter ones. Ensure your input video is properly formatted and stable.

### Character identity changing unexpectedly

**Avoid global transformations for identity preservation.** Use targeted edits (clothing, accessories) instead of scene-wide transforms. Add identity-preserving keywords if needed.

### Processing taking too long

**Optimize your settings:**

* Use FP16 weights instead of FP32
* Reduce resolution if quality allows
* Consider using the API version for faster processing
* Process shorter clips when testing prompts

## Examples showcase the possibilities

### Professional outfit changes

**Input:** Woman in casual wear
**Prompt:** "Change the outfit to a tailored business suit, charcoal gray wool, slim fit blazer, matching pencil skirt, white silk blouse underneath, pearl buttons"
**Result:** Professional transformation while maintaining identity and pose

### Creative character replacements

**Input:** Person walking
**Prompt:** "Replace the person with a steampunk robot, brass gears visible, copper plating, steam vents on shoulders, glowing blue eyes, mechanical joints"
**Result:** Robotic character maintaining original walking motion

### Seasonal scene transformations

**Input:** Summer park scene
**Prompt:** "Transform the scene to autumn, golden hour lighting, orange and red maple leaves falling, warm amber tones, soft shadows, crisp atmosphere"
**Result:** Complete seasonal change with consistent motion

## Additional resources and support

**Get help when you need it.** Join the Decart Discord at [https://discord.gg/decart](https://discord.gg/decart) for community support and updates.

**Report issues on GitHub.** Submit bug reports and feature requests at [https://github.com/DecartAI/lucy-edit-comfyui](https://github.com/DecartAI/lucy-edit-comfyui)

**Access the technical report.** Read the full technical details at [https://d2drjpuinn46lb.cloudfront.net/Lucy\_Edit\_\_High\_Fidelity\_Text\_Guided\_Video\_Editing.pdf](https://d2drjpuinn46lb.cloudfront.net/Lucy_Edit__High_Fidelity_Text_Guided_Video_Editing.pdf)

**Try the web playground.** Experiment without installation at [https://platform.decart.ai](https://platform.decart.ai)

## Latest updates

* **September 17, 2025:** Initial Lucy Edit Dev weights and reference code released
* **September 16, 2025:** Diffusers integration merged (PR #12340)

## Coming soon

* Support for Lucy Edit Dev/Image API
* Enhanced prompt optimization tools
* Batch processing capabilities


# E-commerce Virtual Try-On
Source: https://docs.platform.decart.ai/examples/ecommerce-try-on

Add a 'Try it on' button to product pages with realtime virtual try-on

Let shoppers see how clothing looks on them in realtime, using just a webcam. This walkthrough covers the key integration points for adding virtual try-on to an e-commerce product page — from creating secure client tokens to sending garment images with descriptive prompts.

<Info>
  This example uses Next.js, but the same `@decartai/sdk` works with any JavaScript framework.
</Info>

**Source code:** [github.com/DecartAI/tryon-examples](https://github.com/DecartAI/tryon-examples) — includes six production-ready examples (e-commerce, standalone, digital mirror, outfit builder, and more).

## What you'll build

<CardGroup>
  <Card title="Try-on button" icon="shirt">
    A "Try it on" button on product pages that opens a realtime try-on modal with the user's webcam.
  </Card>

  <Card title="Instant garment swap" icon="arrows-rotate">
    Switch between products without reconnecting — each click sends a new garment image and prompt.
  </Card>

  <Card title="Secure tokens" icon="lock">
    Your permanent API key stays on the server. The browser only receives a short-lived ephemeral token.
  </Card>
</CardGroup>

## Prerequisites

* Node.js 18+
* A Decart API key from [platform.decart.ai](https://platform.decart.ai)

## How it works

The entire integration is three steps:

1. **Server** creates a short-lived client token from your permanent API key
2. **Browser** opens the camera and establishes a WebRTC connection to `lucy-vton-latest`
3. **Browser** sends a garment image + descriptive prompt via `set()` — the model dresses the person in realtime

```mermaid theme={null}
sequenceDiagram
    participant S as Your Server
    participant D as Decart
    participant B as Browser<br/>(Decart SDK)

    S->>D: POST /v1/client/tokens (API key)
    D-->>S: { apiKey: "eyJ...", expiresAt }
    S->>B: Pass client token

    B->>D: WebRTC connect (camera stream)
    D->>B: WebRTC (transformed video)

    Note over B,D: set({ image, prompt }) to change outfits
```

## Step 1: Create a client token (server-side)

Your backend creates a short-lived token using your permanent API key. The browser never sees your real key.

```typescript theme={null}
// app/api/tokens/route.ts
import { createDecartClient } from "@decartai/sdk";
import { NextResponse } from "next/server";

export async function POST() {
  const client = createDecartClient({
    apiKey: process.env.DECART_API_KEY,
  });
  const token = await client.tokens.create();
  return NextResponse.json(token);
}
```

<Note>
  Client tokens expire 60 seconds after minting by default. Let the SDK fetch one for every connect and reconnect with `apiKeyProvider`, as in step 2, rather than minting when the page loads. Active WebRTC sessions continue working after the token expires. See [Token lifetime](/getting-started/client-tokens#token-lifetime).
</Note>

## Step 2: Connect camera to the realtime model

The frontend opens the camera and establishes a WebRTC connection to `lucy-vton-latest`. The SDK fetches a client token from your backend right before dialling.

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

// 1. Fetch a client token from your backend right before every connect and reconnect
const client = createDecartClient({
  apiKeyProvider: async () => {
    const res = await fetch("/api/tokens", { method: "POST" });
    const { apiKey } = await res.json();
    return apiKey;
  },
});

// 2. Open the user's camera
const stream = await navigator.mediaDevices.getUserMedia({
  video: { facingMode: "user" },
});

// 3. Connect to the realtime model
const rtClient = await client.realtime.connect(stream, {
  model: models.realtime("lucy-vton-latest"),
  onRemoteStream: (remoteStream) => {
    document.getElementById("output").srcObject = remoteStream;
  },
});
```

## Step 3: Send a garment image + prompt

Call `set()` to send a reference garment image with a descriptive prompt. The model applies the garment to the person in realtime.

```typescript theme={null}
await rtClient.set({
  prompt: "Substitute the current top with a black bomber jacket with a blue logo on the chest and a zip front",
  image: garmentBlob,
  enhance: false,
});
```

Call `set()` again at any time to switch garments — no need to reconnect.

## Product catalog pattern

For e-commerce, pre-write prompts for each product in your catalog. This gives the best results since you can craft specific, detailed descriptions.

```typescript theme={null}
interface Product {
  name: string;
  image: string;
  prompt: string;
  price: number;
}

const products: Product[] = [
  {
    name: "Bomber Jacket",
    image: "/products/bomber.png",
    prompt: "Substitute the current top with a black bomber jacket with a blue logo on the chest and a zip front",
    price: 149,
  },
  {
    name: "Knit Beanie",
    image: "/products/beanie.png",
    prompt: "Add a navy blue knit beanie with a white cross logo on the fold to the person's head",
    price: 35,
  },
  {
    name: "Polo Shirt",
    image: "/products/polo.png",
    prompt: "Substitute the current top with a navy blue polo shirt with a white logo on the chest",
    price: 69,
  },
];

// When user clicks "Try it on"
async function tryOn(product: Product) {
  const garmentBlob = await fetch(product.image).then((r) => r.blob());
  await rtClient.set({
    prompt: product.prompt,
    image: garmentBlob,
    enhance: false, // use your pre-written prompt as-is
  });
}
```

### Prompt patterns

Use the **substitute** pattern when replacing an existing garment, and the **add** pattern when adding something new:

| Pattern | When to use | Example |
| - | - | - |
| **Substitute** | Replacing an existing garment | `"Substitute the current top with a red plaid flannel shirt with a relaxed fit"` |
| **Add** | Adding something the person isn't wearing | `"Add a wide-brimmed straw hat to the person's head"` |

Be specific — include color, material, texture, pattern, and fit. Aim for **20–30 words**.

```
✅ "Substitute the current top with a bright red hoodie with an oversized casual fit"
✅ "Add a navy baseball cap with a blue logo to the person's head"

❌ "Put a jacket on the person"   (too vague)
❌ "Red hoodie"                    (missing action and context)
```

## Generating prompts for user uploads

For user-uploaded garment images where you don't have a pre-written prompt, use any vision LLM to auto-generate one from the garment image:

```typescript theme={null}
// app/api/enhance-prompt/route.ts
import OpenAI from "openai";

const openai = new OpenAI();

export async function POST(req: Request) {
  const formData = await req.formData();
  const image = formData.get("image") as File;
  const personFrame = formData.get("personFrame") as File | null; // optional

  const messages = [
    {
      role: "system" as const,
      content: `You write prompts for a virtual try-on model. Examine the garment image and write a prompt using this pattern:
"Substitute the current top with [detailed garment description]" or "Add [item] to the person's [body part]".
Include color, material, texture, pattern, and fit. 20-30 words. Return only the prompt.`,
    },
    {
      role: "user" as const,
      content: [
        { type: "image_url" as const, image_url: { url: await fileToDataUrl(image) } },
        ...(personFrame
          ? [{ type: "image_url" as const, image_url: { url: await fileToDataUrl(personFrame) } }]
          : []),
      ],
    },
  ];

  const completion = await openai.chat.completions.create({
    model: "gpt-4o-mini",
    messages,
    max_tokens: 100,
  });

  return Response.json({ prompt: completion.choices[0].message.content });
}
```

<Tip>
  Sending a camera frame of the person alongside the garment image gives the LLM context about what they're currently wearing, producing more accurate prompts (e.g. "Substitute the grey sweater" instead of generic "Substitute the current top").
</Tip>

## Reference image tips

* **Clean garment images work best** — just the clothing item, no person wearing it
* **White or plain backgrounds** are ideal
* **At least 512×512 pixels** — the model reproduces what it sees, so a clear image produces better results
* If your product images show a model wearing the garment, consider using an image editing model to extract just the clothing item first

## More examples

The [tryon-examples](https://github.com/DecartAI/tryon-examples) repo includes six production-ready Next.js examples:

| Example | Use case | Highlights |
| - | - | - |
| **E-commerce** | "Try it on" on product pages | Pre-written prompts, modal overlay |
| **Standalone** | Dedicated try-on experience | LLM-generated prompts from garment images |
| **Person Detection** | Kiosks and unattended displays | Auto-connects only when someone is in frame |
| **Full-Featured** | Complete try-on experience | Person detection, clothing extraction, extreme precision |
| **Digital Mirror** | In-store kiosk / smart mirror | Two-device setup (display + phone controller via QR code) |
| **Outfit Builder** | Multi-garment styling | Compose top + bottom garments into full outfits |

## Next steps

<CardGroup>
  <Card icon="bolt" title="Virtual Try-On Guide" href="/models/realtime/virtual-try-on">
    Full guide for realtime and batch virtual try-on, including all parameters and SDK examples.
  </Card>

  <Card icon="code" title="Batch API Reference" href="/api-reference/lucy-vton-latest">
    Process pre-recorded videos asynchronously with the batch virtual try-on endpoint.
  </Card>

  <Card icon="key" title="Client Tokens" href="/getting-started/client-tokens">
    Secure your integration with short-lived ephemeral tokens.
  </Card>

  <Card icon="bolt" title="Streaming Best Practices" href="/models/realtime/streaming-best-practices">
    Optimize your realtime integration for the best experience.
  </Card>
</CardGroup>


# Examples
Source: https://docs.platform.decart.ai/examples/overview

Official examples hub for realtime-first Decart integrations

Use this as the single entry point for Decart examples. Start with Lucy 2.1 and realtime flows, then branch into batch workflows as needed.

<Info>
  If you're building a new product, start with **Realtime Mobile App** or **Use Cases** first.
</Info>

## Recommended example paths

<CardGroup>
  <Card title="Use Cases" href="/examples/use-cases" icon="lightbulb">
    End-to-end patterns for realtime and batch products.
  </Card>

  <Card title="E-commerce Try-On" href="/examples/ecommerce-try-on" icon="shirt">
    Add a "Try it on" button to product pages with realtime virtual try-on.
  </Card>

  <Card title="Realtime Mobile App" href="/examples/real-time-mobile-app" icon="mobile">
    Full Expo/React Native architecture and WebRTC integration.
  </Card>

  <Card title="ComfyUI" href="/examples/comfyui" icon="wand-magic-sparkles">
    Workflow-based editing setup and model usage in ComfyUI.
  </Card>
</CardGroup>

## GitHub example repositories

Decart maintains multiple public examples, including:

* [`tryon-examples`](https://github.com/DecartAI/tryon-examples) - Six production-ready Next.js virtual try-on examples (e-commerce, digital mirror, outfit builder, and more).
* [`decart-example-expo-realtime`](https://github.com/DecartAI/decart-example-expo-realtime) - Expo app demonstrating Decart realtime video models.
* [`decart-example-expo-greeting`](https://github.com/DecartAI/decart-example-expo-greeting) - Expo app for personalized greeting image generation.
* [`decart-example-outfitters`](https://github.com/DecartAI/decart-example-outfitters) - React + Vite demo for weather-based outfit generation from a photo.
* [`decart-example-telegram-bot`](https://github.com/DecartAI/decart-example-telegram-bot) - Telegram bot integration for Decart image and video models.

<Tip>
  Browse these repositories from the DecartAI GitHub organization for production-style implementation references.
</Tip>


# Realtime Mobile App
Source: https://docs.platform.decart.ai/examples/real-time-mobile-app

Build a realtime AI video app with Expo and the Decart SDK

Transform live camera video with AI on mobile devices. This walkthrough covers the architecture and key integration points of an open-source Expo app that connects to Decart's realtime models — including Lucy 2.1 for character transformation.

<Info>
  This example uses Expo with LiveKit's React Native WebRTC stack. React Native realtime requires the LiveKit packages and an early `registerGlobals()` call — plain `react-native-webrtc` is not supported. See [LiveKit setup for React Native](#livekit-setup-for-react-native) below.
</Info>

**Source code:** [github.com/DecartAI/decart-example-expo-realtime](https://github.com/DecartAI/decart-example-expo-realtime)

## What you'll build

<CardGroup>
  <Card title="Model switching" icon="toggle-on">
    Switch between Lucy Restyle Live, Lucy editing, and — after a quick upgrade — Lucy 2.1 for character transformation.
  </Card>

  <Card title="Style presets" icon="palette">
    Swipe through curated looks: anime characters, tuxedos, superhero costumes, and more. Each preset is a text prompt sent to the model.
  </Card>

  <Card title="Camera controls" icon="camera-rotate">
    Toggle front/back camera, switch view modes (fullscreen, picture-in-picture, split), and see your original and transformed feeds side by side.
  </Card>
</CardGroup>

## Prerequisites

* Node.js 18+
* Expo (`npx expo` — no global install needed)
* A Decart API key from [platform.decart.ai](https://platform.decart.ai)
* A physical iOS or Android device (WebRTC requires real camera hardware)

## Project setup

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/DecartAI/decart-example-expo-realtime.git
    cd decart-example-expo-realtime
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Add your API key">
    Create a `.env` file in the project root:

    ```bash theme={null}
    EXPO_PUBLIC_DECART_API_KEY=your-api-key-here
    ```
  </Step>

  <Step title="Run on a device">
    ```bash theme={null}
    npx expo run:ios
    # or
    npx expo run:android
    ```
  </Step>
</Steps>

<Warning>
  WebRTC requires a physical device. The iOS Simulator and Android Emulator do not support camera streaming.
</Warning>

## LiveKit setup for React Native

React Native realtime runs on [LiveKit's React Native packages](https://github.com/livekit/client-sdk-react-native). Plain `react-native-webrtc` is **not** supported. The cloned example already wires this up — here's what makes it work.

**1. Install the LiveKit packages** (already in the example's `package.json`):

```bash theme={null}
npm install @decartai/sdk livekit-client@2.20.1 \
  @livekit/react-native@2.11.1 \
  @livekit/react-native-webrtc@144.1.1
```

**2. Register LiveKit's native globals before the app starts.** The SDK reads the WebRTC globals that LiveKit installs, so `registerGlobals()` must run before your router or root component is imported:

```typescript theme={null}
// livekit-bootstrap.ts
import { registerGlobals } from "@livekit/react-native";

registerGlobals();
```

```typescript theme={null}
// index.ts — import the bootstrap before the app entrypoint
import "./livekit-bootstrap";
import "expo-router/entry"; // or your root App component
```

**3. Add the Expo config plugins.** Install them and register them in `app.json`:

```bash theme={null}
npm install @livekit/react-native-expo-plugin@1.0.2 \
  @config-plugins/react-native-webrtc
```

```json theme={null}
{
  "expo": {
    "plugins": [
      "@livekit/react-native-expo-plugin",
      "@config-plugins/react-native-webrtc"
    ]
  }
}
```

Then run `npx expo prebuild` and rebuild the native app. LiveKit does not run in Expo Go — you need a development build on a physical device.

<Note>
  Using **bare React Native (CLI)** instead of Expo? The realtime code is identical, but you need two Metro/Babel config changes (Expo applies them for you). See [React Native CLI (bare projects)](/sdks/javascript-realtime#react-native-cli-bare-projects).
</Note>

## Architecture overview

The app uses Expo Router with three screens:

| Screen | File | Purpose |
| - | - | - |
| Entry | `app/index.tsx` | Checks camera/microphone permissions, routes accordingly |
| Permissions | `app/permission-screen.tsx` | Requests camera and microphone access |
| Camera | `app/camera.tsx` | Renders the main `<Camera />` component |

Key directories:

```
components/camera/
  hooks/useWebRTC.ts      — Core Decart SDK integration
  ui/ModelSelector.tsx     — Model toggle UI
  ui/VideoRenderer.tsx     — Displays local + remote streams
  ui/style-carousel/       — Swipeable style picker

livekit-bootstrap.ts       — registerGlobals() before the app entrypoint

lib/realtime/
  media-streams.ts         — Camera capture via LiveKit's mediaDevices

lib/skins/
  lucy-skin-list.ts        — 21 text prompts for Lucy editing presets
  lucy-restyle-live-skin-list.ts      — Style presets with optional audio
```

<Note>
  The example reads a permanent API key from `EXPO_PUBLIC_DECART_API_KEY` to keep the walkthrough short. In production, mint [client tokens](/getting-started/client-tokens) on your backend and pass `apiKeyProvider` to `createDecartClient`, so every connect and reconnect dials with a fresh token.
</Note>

## Core integration: the WebRTC hook

The `useWebRTC` hook handles the entire Decart SDK lifecycle — creating a client, capturing the camera, connecting to a realtime model, and managing cleanup.

```typescript theme={null}
import { useCallback, useRef, useState } from "react";
import { createDecartClient, type ModelDefinition, type RealTimeClient, resolveFpsNumber } from "@decartai/sdk";
import type { MediaStream } from "@livekit/react-native-webrtc";
import { getMediaStream } from "@/lib/realtime/media-streams";

export function useWebRTC({ model, facingMode }: { model: ModelDefinition; facingMode: string }) {
  const [localMediaStream, setLocalMediaStream] = useState<MediaStream | null>(null);
  const [remoteMediaStream, setRemoteMediaStream] = useState<MediaStream | null>(null);
  const [connectionState, setConnectionState] = useState<string>("disconnected");
  const realtimeClientRef = useRef<RealTimeClient | null>(null);

  const initializeWebRTC = useCallback(
    async ({ model, facingMode }: { model: ModelDefinition; facingMode: string }) => {
      try {
        // 1. Create the Decart client
        const decartClient = createDecartClient({
          apiKey: process.env.EXPO_PUBLIC_DECART_API_KEY as string,
        });

        // 2. Capture camera with model-specific constraints.
        //    resolveFpsNumber() turns the model's FPS descriptor into a number.
        const stream = await getMediaStream(facingMode, {
          fps: resolveFpsNumber(model.fps),
          width: model.width,
          height: model.height,
        });
        setLocalMediaStream(stream);
        setConnectionState("connecting");

        // 3. Connect to the realtime model. Pass LiveKit's MediaStream type as the
        //    generic — no casts — and select VP8 with preferredVideoCodec.
        realtimeClientRef.current = await decartClient.realtime.connect<MediaStream>(stream, {
          model,
          preferredVideoCodec: "vp8",
          onRemoteStream: (transformedStream) => {
            setRemoteMediaStream(transformedStream);
            setConnectionState("connected");
          },
        });
      } catch (error) {
        console.error("Connection failed:", error);
        setConnectionState("failed");
      }
    },
    [],
  );

  const cleanupWebRTC = useCallback(() => {
    realtimeClientRef.current?.disconnect();
    setRemoteMediaStream(null);
    setConnectionState("disconnected");
  }, []);

  return {
    localMediaStream,
    remoteMediaStream,
    connectionState,
    realtimeClientRef,
    initializeWebRTC,
    cleanupWebRTC,
  };
}
```

Three things to note:

1. **Model constraints drive camera setup.** Each model defines its own `fps`, `width`, and `height`. Resolve the FPS with `resolveFpsNumber(model.fps)` (it can be a descriptor object rather than a plain number), and `getMediaStream` requests exactly those dimensions from LiveKit's `mediaDevices`.

2. **`preferredVideoCodec: "vp8"` selects the codec.** React Native works best with VP8. The SDK negotiates it for you — there's no manual SDP rewriting (the old `customizeOffer` / `forceCodecInSDP` approach is gone).

3. **No `MediaStream` casts.** `connect<MediaStream>(...)` takes LiveKit's React Native `MediaStream` type as a generic, so you pass the captured stream straight through — no `as unknown as` bridging.

## Switching models

Each model offers different creative capabilities:

| Model | ID | What it does |
| - | - | - |
| **Lucy 2.1** | `lucy-2.1` | Character transformation and text-guided editing in one model |
| **Lucy Restyle Live** | `lucy-restyle-2` | Full video restyling — transform scenes into different visual styles |

Switch models by creating a new `ModelDefinition` and reconnecting:

```typescript theme={null}
import { models, type ModelDefinition } from "@decartai/sdk";

// Select a model
const restyleLive = models.realtime("lucy-restyle-2");
const lucy2 = models.realtime("lucy-2.1");

// To switch: disconnect, update state, reconnect
async function switchModel(newModel: ModelDefinition) {
  cleanupWebRTC();
  await new Promise((resolve) => setTimeout(resolve, 100)); // allow cleanup to complete
  await initializeWebRTC({ model: newModel, facingMode });
}
```

<Tip>
  Use Lucy 2.1 as the default for new mobile integrations. It supports both character reference and text-only editing.
</Tip>

## Applying style presets

The app includes curated prompt presets for each model. When a user selects a preset, the prompt is sent to the active model:

```typescript theme={null}
// Apply a style preset to the current model
if (realtimeClientRef.current) {
  realtimeClientRef.current.setPrompt(skin.prompt, {
    enhance: skin.enrich ?? false,
  });
}
```

Example prompts from the preset list:

```typescript theme={null}
const presets = [
  {
    title: "Anime Character",
    prompt:
      "Transform the person into a 2D anime character with smooth cel-shaded lines, " +
      "soft pastel highlights, large expressive eyes, clean contours, even lighting, " +
      "simplified textures, and a bright studio-style background for a polished anime look.",
  },
  {
    title: "Black Tuxedo",
    prompt:
      "Change the outfit to a sharp black tuxedo with satin lapels, crisp white shirt, " +
      "black bow tie, tailored fit, polished shoes, and soft indoor lighting reflecting " +
      "off a marble floor.",
  },
  {
    title: "Sunglasses",
    prompt:
      "Add a pair of dark tinted sunglasses resting naturally on the person's face, " +
      "smooth acetate frames, subtle reflections on the lenses, accurate nose " +
      "placement, and soft shadows across the cheeks.",
  },
];
```

For Lucy 2.1, use `set()` instead of `setPrompt()` to include a reference image:

```typescript theme={null}
// Lucy 2.1: transform into a character using a reference image
await realtimeClientRef.current.set({
  prompt: "Transform into this character",
  image: characterImage, // File, Blob, or URL
  enhance: true,
});
```

## Handling app lifecycle

Mobile apps frequently move between foreground and background. The example handles this by disconnecting when backgrounded and reconnecting when foregrounded:

```typescript theme={null}
import { AppState, type AppStateStatus } from "react-native";

useEffect(() => {
  const handleAppStateChange = (nextAppState: AppStateStatus) => {
    if (appStateRef.current.match(/inactive|background/) && nextAppState === "active") {
      // App returned to foreground — reconnect
      initializeWebRTC({ model, facingMode });
    } else if (appStateRef.current === "active" && nextAppState.match(/inactive|background/)) {
      // App going to background — disconnect to free resources
      cleanupWebRTC();
    }
    appStateRef.current = nextAppState;
  };

  const subscription = AppState.addEventListener("change", handleAppStateChange);
  return () => subscription?.remove();
}, [cleanupWebRTC, initializeWebRTC]);
```

<Tip>
  Always disconnect when backgrounded. WebRTC connections consume battery and network resources even when the app isn't visible.
</Tip>

## Camera controls

**Mirror the front camera.** The SDK's `mirror` option is browser-only and is rejected on React Native with `UNSUPPORTED_PLATFORM_FEATURE`. Mirror the local preview at the view layer instead — pass `mirror` to LiveKit's `<RTCView>`:

```typescript theme={null}
import { RTCView } from "@livekit/react-native-webrtc";

<RTCView
  mirror={facingMode === "user"}
  objectFit="cover"
  streamURL={localMediaStream.toURL()}
/>
```

**Switch facing mode.** The camera stream needs to be recaptured when toggling between front and back cameras, since each has different hardware capabilities.

## Adding Lucy 2.1 support

<Note>
  Adding Lucy 2.1 requires two small changes: updating the model selector and using the `set()` method for character reference images.
</Note>

**1. Add Lucy 2.1 to the model selector:**

```typescript theme={null}
import { models } from "@decartai/sdk";

// Add lucy-2.1 alongside the existing models
const handleTabPress = (modelName: "lucy-restyle-2" | "lucy-2.1") => {
  const newModel = models.realtime(modelName);
  onModelChange(newModel);
};
```

**2. Use `set()` for character reference images:**

Lucy 2.1's key feature is character transformation via reference images. Replace `setPrompt()` with `set()` when a reference image is available:

```typescript theme={null}
// For Lucy 2.1 with a reference image
await realtimeClientRef.current.set({
  prompt: "Transform into this character",
  image: selectedImage,
  enhance: true,
});

// For text-only editing (works with all models)
realtimeClientRef.current.setPrompt("Add sunglasses", { enhance: true });
```

## Next steps

<CardGroup>
  <Card title="Lucy 2.1 guide" icon="sparkles" href="/models/realtime/lucy-2.1">
    Character transformation, reference images, and the `set()` API in detail.
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript-realtime">
    Full SDK reference for connection management, events, and client-side auth.
  </Card>

  <Card title="All realtime models" icon="bolt" href="/models/realtime/overview">
    Compare Lucy 2.1 and Lucy Restyle Live side by side.
  </Card>

  <Card title="Source code" icon="github" href="https://github.com/DecartAI/decart-example-expo-realtime">
    Clone the full example app and start building.
  </Card>
</CardGroup>


# Use Cases
Source: https://docs.platform.decart.ai/examples/use-cases

What you can build with Decart's realtime and batch AI models

Decart's models power a range of creative and production applications — from realtime character transformation on mobile to batch video processing for content pipelines. This page highlights the most common use cases with recommended models and starter code for each.

## Realtime use cases

Realtime models process live video and audio over WebRTC with sub-second latency. They run continuously as long as the connection is open.

<CardGroup>
  <Card title="Character transformation" icon="masks-theater">
    Become any character on camera with Lucy 2.1. Upload a reference image and your movements map onto that identity in realtime.
  </Card>

  <Card title="Live streaming effects" icon="tower-broadcast">
    Apply artistic styles to live video with Lucy Restyle Live. Transform your stream into anime, cyberpunk, oil painting, and more.
  </Card>

  <Card title="Realtime video editing" icon="pen-to-square">
    Add, modify, or remove objects in live video with Lucy 2.1. Change outfits, add accessories, or swap backgrounds with text prompts.
  </Card>

  <Card title="Virtual try-on" icon="shirt">
    Let shoppers see how clothing looks on them in realtime. Send a garment image and prompt to Lucy VTON for instant outfit changes.
  </Card>
</CardGroup>

***

### Character transformation with Lucy 2.1

Turn yourself into any character — live on camera. Lucy 2.1 takes a reference image and maps your facial expressions, head movements, and gestures onto that character.

**Best for:** virtual cosplay, social filters, virtual try-on, character-driven content creation.

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const client = createDecartClient({ apiKey: "your-api-key-here" });
const model = models.realtime("lucy-2.1");

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

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

// Upload a character reference and transform
const characterPhoto = document.querySelector("input[type=file]").files[0]; // from file input
await realtimeClient.set({
  prompt: "Transform into this character",
  image: characterPhoto, // File, Blob, or URL
  enhance: true,
});

// Switch characters without reconnecting
const anotherPhoto = await fetch("/another-character.jpg").then((r) => r.blob());
await realtimeClient.set({ prompt: "Transform into this character", image: anotherPhoto });
```

<Tip>
  Lucy 2.1 also works without a reference image — pass only a `prompt` to `set()` for text-based editing.
</Tip>

### Live streaming effects with Lucy Restyle Live

Transform the entire visual style of a live video feed. Lucy Restyle Live applies artistic styles in realtime — ideal for Twitch, YouTube Live, or TikTok.

**Best for:** social media filters, creative livestreams, virtual events, themed video calls.

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const client = createDecartClient({ apiKey: "your-api-key-here" });
const model = models.realtime("lucy-restyle-2");

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

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

// Apply a style
realtimeClient.setPrompt("Studio Ghibli animation style", { enhance: true });

// Switch styles on the fly
realtimeClient.setPrompt("Cyberpunk city with neon lighting");
realtimeClient.setPrompt("Watercolor painting with soft edges");
```

### Realtime video editing with Lucy 2.1

Make targeted edits to live video using text prompts. Add objects, change clothing, swap backgrounds — all without interrupting the stream.

**Best for:** interactive experiences, photo booths, AR-style effects, live content creation.

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const client = createDecartClient({ apiKey: "your-api-key-here" });
const model = models.realtime("lucy-2.1");

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

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

// Add objects, change outfits, modify the scene
await realtimeClient.set({ prompt: "Add a small dog running around", enhance: true });
await realtimeClient.set({ prompt: "Change the outfit to a sharp black tuxedo with satin lapels" });
await realtimeClient.set({ prompt: "Replace the background with a beach at sunset" });
```

### Virtual try-on with Lucy VTON

Let shoppers see how clothing looks on them in realtime. Lucy VTON takes a garment reference image and a descriptive prompt, then dresses the person on camera — perfect for e-commerce "Try it on" buttons, digital mirrors, and styling apps.

**Best for:** e-commerce product pages, in-store kiosks, digital mirrors, styling and outfit planning.

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const client = createDecartClient({ apiKey: "your-api-key-here" });
const model = models.realtime("lucy-vton-latest");

const stream = await navigator.mediaDevices.getUserMedia({
  video: { facingMode: "user" },
});

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

// Send a garment image with a descriptive prompt
const garmentBlob = await fetch("/products/bomber.png").then((r) => r.blob());
await realtimeClient.set({
  prompt: "Substitute the current top with a black bomber jacket with a blue logo on the chest and a zip front",
  image: garmentBlob,
  enhance: false,
});

// Switch garments without reconnecting
const beanieBlob = await fetch("/products/beanie.png").then((r) => r.blob());
await realtimeClient.set({
  prompt: "Add a navy blue knit beanie with a white logo on the fold to the person's head",
  image: beanieBlob,
  enhance: false,
});
```

<Tip>
  Use the **substitute** pattern when replacing an existing garment (`"Substitute the current top with..."`) and the **add** pattern for new items (`"Add a hat to the person's head"`). See the [full e-commerce try-on example](/examples/ecommerce-try-on) for a complete integration walkthrough.
</Tip>

***

## Batch use cases

Batch models process pre-recorded video and images asynchronously. Submit a job, poll for completion, then download the result.

<CardGroup>
  <Card title="Video editing" icon="wand-magic-sparkles">
    Transform and edit existing videos — change styles, replace objects, or modify scenes.
  </Card>

  <Card title="Image editing" icon="image">
    Edit existing images with precise text-driven control.
  </Card>
</CardGroup>

***

### Video editing

Transform existing videos with text instructions. Change styles, replace objects, or modify entire scenes while preserving the original motion.

**Best for:** post-production, content repurposing, brand transformations, visual effects.

<CodeGroup>
  ```typescript JavaScript theme={null}
  import { createDecartClient, models } from "@decartai/sdk";
  import { readFileSync, writeFileSync } from "fs";

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

  const videoBlob = new Blob([readFileSync("input.mp4")], { type: "video/mp4" });

  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-2.1"),
    data: videoBlob,
    prompt: "Replace the person's outfit with a medieval knight's armor",
    onStatusChange: (job) => console.log(`Status: ${job.status}`),
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("edited.mp4", buffer);
  }
  ```

  ```bash cURL theme={null}
  # Submit a video editing job
  curl -X POST https://api.decart.ai/v1/jobs/lucy-2.1 \
    -H "X-API-KEY: your-api-key-here" \
    -F "data=@input.mp4" \
    -F "prompt=Transform into Studio Ghibli animation style"

  # Poll for result
  curl https://api.decart.ai/v1/jobs/{job_id} \
    -H "X-API-KEY: your-api-key-here"

  # Download when complete
  curl https://api.decart.ai/v1/jobs/{job_id}/content \
    -H "X-API-KEY: your-api-key-here" \
    --output result.mp4
  ```
</CodeGroup>

### Image editing

Apply edits to existing images with text instructions.

**Best for:** product mockups, creative assets, visual prototyping, style transfers.

<CodeGroup>
  ```typescript Image editing theme={null}
  import { createDecartClient, models } from "@decartai/sdk";

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

  const result = await client.process({
    model: models.image("lucy-image-2"),
    data: "https://example.com/room.jpg", // File, Blob, URL, or ReadableStream
    prompt: "Change the wall color to deep burgundy, keep everything else the same",
    enhance_prompt: true,
  });
  ```
</CodeGroup>

***

## Choosing between realtime and batch

| | **Realtime** | **Batch** |
| - | - | - |
| **Latency** | Sub-second (WebRTC) | Seconds to minutes (async jobs) |
| **Input** | Live camera or video stream | Pre-recorded files |
| **Connection** | Persistent — runs as long as connected | One-shot — submit, poll, download |
| **Pricing** | Per second of connection time | Per second of output video |
| **Best for** | Interactive apps, live streaming, mobile | Post-production, content pipelines, automation |

<Info>
  Realtime and batch models use the same `@decartai/sdk` package. The difference is how you connect — `client.realtime.connect()` for realtime, `client.queue.submitAndPoll()` for video, `client.process()` for images.
</Info>

## Next steps

<CardGroup>
  <Card title="Lucy 2.1 guide" icon="sparkles" href="/models/realtime/lucy-2.1">
    Deep dive into character transformation with reference images.
  </Card>

  <Card title="E-commerce try-on" icon="shirt" href="/examples/ecommerce-try-on">
    Add a "Try it on" button to product pages with realtime virtual try-on.
  </Card>

  <Card title="Realtime mobile app" icon="mobile" href="/examples/real-time-mobile-app">
    Build a complete Expo app with model switching and style presets.
  </Card>

  <Card title="All models" icon="layer-group" href="/getting-started/models">
    Compare every Decart model — realtime and batch — side by side.
  </Card>
</CardGroup>


# Coding Agents
Source: https://docs.platform.decart.ai/getting-started/ai-coding-agents

Teach your AI coding agent how to use Decart's APIs

Two ways to give your AI coding agent Decart expertise: **skills** teach it API patterns upfront, and the **MCP server** lets it search Decart's documentation on demand. Use both for best results.

## Agent skill

A skill is a static knowledge file your agent loads at startup. It teaches the agent which API to use, how to authenticate, which models to pick, and what mistakes to avoid.

<Steps>
  <Step title="Install the Decart skill">
    Run this in your project directory:

    ```bash theme={null}
    npx skills add https://docs.platform.decart.ai
    ```

    The CLI auto-discovers the skill and installs it to your detected coding agents.
  </Step>

  <Step title="Start building">
    Your agent now has context about Decart's Realtime, Queue, and Process APIs. Try asking it:

    * "Add live camera effects using Decart's realtime API"
    * "Generate a video from a text prompt using Decart"
    * "Create a talking avatar that lip-syncs to audio"
  </Step>
</Steps>

| Your agent learns | Details |
| - | - |
| API selection | Which API (Realtime, Queue, Process) fits your use case |
| Model selection | Which model for character transform, style transfer, video gen, image gen |
| Authentication | Server-side API keys vs client-side token generation |
| SDK patterns | Correct code patterns for JavaScript and Python |
| Common mistakes | Camera resolution, API key exposure, cleanup, moderation handling |

<AccordionGroup>
  <Accordion title="Install to a specific agent">
    ```bash theme={null}
    npx skills add https://docs.platform.decart.ai -a claude-code
    npx skills add https://docs.platform.decart.ai -a cursor
    ```
  </Accordion>

  <Accordion title="Install globally (all projects)">
    ```bash theme={null}
    npx skills add https://docs.platform.decart.ai -g
    ```
  </Accordion>
</AccordionGroup>

<Note>
  Skills work with 30+ coding agents including Claude Code, Cursor, GitHub Copilot, Windsurf, and OpenCode. See the [full list](https://skills.sh).
</Note>

## MCP server

The MCP (Model Context Protocol) server gives your agent a live search tool that queries Decart documentation on demand. Unlike the skill which is loaded once, MCP lets the agent look up specific details — exact parameters, migration guides, changelog entries — as it works.

Add the Decart MCP server to your agent:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add decart-docs https://docs.platform.decart.ai/mcp --transport http
    ```
  </Tab>

  <Tab title="Codex">
    Add to your `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.decart-docs]
    type = "http"
    url = "https://docs.platform.decart.ai/mcp"
    ```
  </Tab>

  <Tab title="Cursor">
    Add to your `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "decart-docs": {
          "url": "https://docs.platform.decart.ai/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Once connected, your agent can search Decart documentation automatically while generating responses — no need to ask it explicitly.

## Skill vs MCP

| | Skill | MCP |
| - | - | - |
| **How it works** | Pre-loaded context at startup | Live search during conversation |
| **Best for** | API patterns, model selection, gotchas | Exact parameters, examples, latest changes |
| **Setup** | `npx skills add` (one time) | Add MCP config (one time) |
| **Token cost** | Loaded once (\~200 lines) | Per-search, only what's needed |

<Tip>
  Use both together. The skill gives your agent the big picture so it picks the right API and model. The MCP server fills in specifics when the agent needs exact parameter details or code examples.
</Tip>

## Prompting tips

Get better results from your agent by being specific about what you're building:

* **Name the API** — "Use the Realtime API" or "Use the Queue API" instead of just "use Decart"
* **Specify the model** — "Use `lucy-2.1` for character transform" rather than letting the agent guess
* **Mention the SDK** — "Using the JavaScript SDK" or "Using Python" so it generates the right syntax
* **Ask for client tokens** — "Make sure to use client tokens for the browser code" for frontend work
* **Reference the platform** — "Check the Decart docs for the exact parameters" triggers the MCP search


# Authentication
Source: https://docs.platform.decart.ai/getting-started/authentication

Secure your API requests with API keys

## Get your API key

<Steps>
  <Step title="Sign up">
    Create an account at [platform.decart.ai](https://platform.decart.ai)
  </Step>

  <Step title="Create an API Key">
    Navigate to [API Keys](https://platform.decart.ai/api-keys) and create a new API Key
  </Step>

  <Step title="Copy key">
    Copy your API key
  </Step>
</Steps>

## Use your API key

Pass your API key when making requests:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { createDecartClient } from "@decartai/sdk";

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

  ```python Python theme={null}
  from decart import DecartClient
  import os

  client = DecartClient(api_key=os.getenv("DECART_API_KEY"))
  ```

  ```bash cURL theme={null}
  # Submit job
  JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-latest \
    -H "X-API-KEY: $DECART_API_KEY" \
    -F "data=@video.mp4" \
    -F "prompt=Transform to anime style" | jq -r '.job_id')

  # Poll status and download when complete
  while [ "$(curl -s -H "X-API-KEY: $DECART_API_KEY" \
    https://api.decart.ai/v1/jobs/$JOB_ID | jq -r '.status')" != "completed" ]; do sleep 2; done

  curl -H "X-API-KEY: $DECART_API_KEY" \
    https://api.decart.ai/v1/jobs/$JOB_ID/content --output transformed.mp4
  ```
</CodeGroup>

## Best practices

<Warning>
  Never hardcode API keys in your code. Use environment variables.
</Warning>

* Store keys in environment variables
* Rotate keys regularly
* Use different keys for development and production

## Realtime client-side authentication

For browser and mobile apps, use **client tokens** instead of your permanent key (`dct_...`).

<Warning>
  Do not expose permanent API keys in frontend bundles. Always mint short-lived client tokens from your backend.
</Warning>

Create a token from your backend:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { createDecartClient } from "@decartai/sdk";

  const client = createDecartClient({ apiKey: process.env.DECART_API_KEY });
  const token = await client.tokens.create(); // 60s TTL, unrestricted
  // Or scoped:
  // const token = await client.tokens.create({ expiresIn: 300, allowedModels: ["lucy-2.1"] });
  ```

  ```python Python theme={null}
  from decart import DecartClient
  import os

  async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
      token = await client.tokens.create()  # 60s TTL, unrestricted
      # Or scoped:
      # token = await client.tokens.create(expires_in=300, allowed_models=["lucy-2.1"])
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.decart.ai/v1/client/tokens \
    -H "x-api-key: $DECART_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"expiresIn": 300, "allowedModels": ["lucy-2.1"]}'
  ```
</CodeGroup>

The response's `apiKey` is a signed client token the gateway verifies offline, so requests don't wait on a key lookup. Hand it to your frontend.

### Token lifetime

Client tokens expire **60 seconds** after minting by default (`expiresIn`, 1–3600 s). Mint right before connecting, or pass `apiKeyProvider` to `createDecartClient` so the SDK fetches a fresh token for every connect and reconnect. An expired token is rejected with `TOKEN_EXPIRED` before any socket is opened. See [Token lifetime](/getting-started/client-tokens#token-lifetime).

<Tip>
  See [Client Tokens](/getting-started/client-tokens) for the complete backend-to-frontend flow and token rotation strategy.
</Tip>

## Need help?

* [Contact support →](mailto:contact@decart.ai)


# Client Tokens
Source: https://docs.platform.decart.ai/getting-started/client-tokens

Secure realtime authentication for browser and mobile apps

Use client tokens for browser and mobile realtime connections.

Client tokens are short-lived credentials you create on your backend, then pass to your frontend for `client.realtime.connect()` and file uploads.

<Warning>
  Never expose your permanent API key (`dct_...`) in client-side code. Use client tokens for all browser and mobile realtime sessions.
</Warning>

## Why client tokens

* Safe to send to browsers and mobile apps
* Short-lived (configurable TTL, 1–3600 seconds, default 60s; see [Token lifetime](#token-lifetime))
* Optional model scoping (restrict which models the key can access)
* Optional origin scoping (restrict which web origins can use the key — browser-enforced)
* Limited scope (cannot create new tokens)
* Signed, so the gateway verifies them offline and connecting doesn't wait on a key lookup
* Expiration blocks new connections, but does not disconnect active realtime sessions

## End-to-end flow

<Steps>
  <Step title="Create token on your backend">
    Your backend uses your permanent API key to create a client token.
  </Step>

  <Step title="Return token to the frontend">
    Return `apiKey` and `expiresAt` from your backend endpoint.
  </Step>

  <Step title="Connect with the client token">
    Your frontend passes the token to the SDK, minted right before `connect()` or fetched per dial through `apiKeyProvider`. See [Token lifetime](#token-lifetime).
  </Step>
</Steps>

## Options

All options are optional. Without options, tokens use a 60-second TTL and are unrestricted.

| Parameter | Type | Description |
| - | - | - |
| `expiresIn` | `number` | TTL in seconds (1–3600, default 60) |
| `allowedModels` | `string[]` | Restrict which models the key can access (max 20) |
| `allowedOrigins` | `string[]` | Restrict which web origins can use the key (max 20, see [Origin scoping](#origin-scoping)) |
| `constraints` | `object` | Operational limits (see below) |
| `metadata` | `object` | Custom key-value pairs to attach to the token |

**Constraints object:**

```json theme={null}
{
  "realtime": {
    "maxSessionDuration": 120  // max seconds per WebSocket session (min 10)
  }
}
```

<Note>
  **`expiresIn` vs `maxSessionDuration`** — these control different things.
  `expiresIn` sets how long the token can be used to **start** new connections. Once a realtime session is established, the token's expiration does not terminate it.
  `maxSessionDuration` caps how long an individual realtime session can remain active, regardless of token expiration.
  Use both together for full control: e.g. a 5-minute token window with a 2-minute max per session.
</Note>

## Token lifetime

Client tokens expire **60 seconds** after minting by default; `expiresIn` sets the TTL from 1 to 3600 seconds. A token minted on page load is usually dead by the time the user has granted camera access and pressed start, and a reconnect with the same token is refused too.

Keep the token fresh in one of two ways:

<Tabs>
  <Tab title="apiKeyProvider (recommended)">
    Pass a function instead of a key. The SDK calls it right before every `connect()`, connect retry, reconnect and `subscribe()`, so each dial carries a token minted for it:

    ```typescript theme={null}
    const client = createDecartClient({
      apiKeyProvider: async () => {
        const res = await fetch("/api/realtime-token", { method: "POST" }); // your server: client.tokens.create(...)
        const { apiKey } = await res.json();
        return apiKey;
      },
    });
    const realtimeClient = await client.realtime.connect(stream, { model, onRemoteStream });
    ```

    `apiKeyProvider` wins over `apiKey` for realtime; the HTTP APIs (`process`, `queue`, `files`, `tokens`) still use `apiKey` or `proxy`. A provider rejection during `connect()` rejects the call with that error; during a reconnect it is retried like any other dial failure.
  </Tab>

  <Tab title="Mint right before connecting">
    Fetch the token after `getUserMedia` and the user's click, immediately before `connect()`, and size `expiresIn` to your connect window:

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

    // Mint now, not on page load.
    const res = await fetch("/api/realtime-token", { method: "POST" });
    const { apiKey } = await res.json();

    const client = createDecartClient({ apiKey });
    const realtimeClient = await client.realtime.connect(stream, { model, onRemoteStream });
    ```

    The SDK cannot refresh a static token, so a reconnect after it expires is refused. Prefer `apiKeyProvider` for sessions that need to survive network drops.
  </Tab>
</Tabs>

### Expired tokens fail fast

Before every realtime dial the SDK reads the token's `exp` claim (5-second clock-skew tolerance) and rejects an expired one with `TOKEN_EXPIRED` without opening a socket:

* `connect()` and `subscribe()` reject with `{ code: "TOKEN_EXPIRED", message, data: { expiresAt, expiredSecondsAgo } }`.
* On a reconnect, the session emits an `error` event with `TOKEN_EXPIRED` and moves to `disconnected` without retrying.

Permanent keys pass through to the server unchanged.

<Note>
  Expiry only gates **new** dials. A realtime session that is already connected keeps running after its token expires. Use `constraints.realtime.maxSessionDuration` to cap how long a session can run.
</Note>

## Model scoping

Pass `allowedModels` to restrict which models a token can be used with. The bouncer verifies model permissions when the client connects — if the model isn't in the allowed list, the connection is rejected.

Tokens created without `allowedModels` are unrestricted and work with any model.

## Origin scoping

Pass `allowedOrigins` to pin a token to a specific list of web origins. When the token is later used to open a realtime session, the connection is accepted only if the browser-issued WebSocket `Origin` header matches one of the listed origins. Mismatched or missing origins are rejected with close code `1008` and `{"type":"error","error":"Origin not allowed"}`.

Each entry must be a **canonical origin** so it compares byte-for-byte to what browsers send. The mint endpoint enforces this and returns a 400 (with the canonical form in the message) when input doesn't match:

* scheme `http://` or `https://`
* lowercase scheme and host
* no trailing slash, path, query, or fragment
* no userinfo (credentials)
* no default port (`:443` for https, `:80` for http)
* max 253 chars per entry, max 20 entries per token

Examples:

| Input | Outcome |
| - | - |
| `https://app.example.com` | accepted |
| `http://localhost:3000` | accepted (non-default port preserved) |
| `https://app.example.com/` | rejected — trailing slash |
| `https://app.example.com:443` | rejected — default port |
| `https://EXAMPLE.com` | rejected — mixed case |
| `https://user@example.com` | rejected — credentials |
| `example.com` | rejected — missing scheme |

Tokens created without `allowedOrigins` are unrestricted (no origin enforcement).

<Note>
  **Defense-in-depth, not hermetic.** Origin enforcement is browser-driven: it materially raises the cost of stolen-token replay from a different web origin, but does not protect against an attacker who controls a non-browser HTTP client and can spoof the `Origin` header. Treat it as one layer alongside short TTLs and model scoping, not a sole boundary.
</Note>

## Backend examples

<CodeGroup>
  ```typescript Next.js Route Handler theme={null}
  // app/api/realtime-token/route.ts
  import { createDecartClient } from "@decartai/sdk";
  import { NextResponse } from "next/server";

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

  export async function POST() {
    try {
      // Basic — 60s TTL, unrestricted
      const token = await client.tokens.create();
      return NextResponse.json(token);
    } catch {
      return NextResponse.json({ error: "Failed to create token" }, { status: 500 });
    }
  }
  ```

  ```typescript Next.js (scoped) theme={null}
  // app/api/realtime-token/route.ts
  import { createDecartClient } from "@decartai/sdk";
  import { NextResponse } from "next/server";

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

  export async function POST() {
    try {
      // Scoped — 5 min TTL, restricted model + origin, 2 min max session
      const token = await client.tokens.create({
        expiresIn: 300,
        allowedModels: ["lucy-2.1"],
        allowedOrigins: ["https://app.example.com"],
        constraints: { realtime: { maxSessionDuration: 120 } },
      });
      return NextResponse.json(token);
    } catch {
      return NextResponse.json({ error: "Failed to create token" }, { status: 500 });
    }
  }
  ```

  ```python FastAPI theme={null}
  from fastapi import FastAPI, HTTPException
  from decart import DecartClient
  import os

  app = FastAPI()
  client = DecartClient(api_key=os.environ["DECART_API_KEY"])

  @app.post("/api/realtime-token")
  async def create_realtime_token():
      try:
          # Basic — 60s TTL, unrestricted
          token = await client.tokens.create()
          return {"apiKey": token.api_key, "expiresAt": token.expires_at}
      except Exception:
          raise HTTPException(status_code=500, detail="Failed to create token")
  ```

  ```python FastAPI (scoped) theme={null}
  from fastapi import FastAPI, HTTPException
  from decart import DecartClient
  import os

  app = FastAPI()
  client = DecartClient(api_key=os.environ["DECART_API_KEY"])

  @app.post("/api/realtime-token")
  async def create_realtime_token():
      try:
          # Scoped — 5 min TTL, restricted model + origin, 2 min max session
          token = await client.tokens.create(
              expires_in=300,
              allowed_models=["lucy-2.1"],
              allowed_origins=["https://app.example.com"],
              constraints={"realtime": {"maxSessionDuration": 120}},
          )
          return {
              "apiKey": token.api_key,
              "expiresAt": token.expires_at,
              "permissions": token.permissions,
              "constraints": token.constraints,
          }
      except Exception:
          raise HTTPException(status_code=500, detail="Failed to create token")
  ```
</CodeGroup>

## Frontend example

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const model = models.realtime("lucy-2.1");

// The SDK calls the provider right before every connect and reconnect, so each
// dial carries a token minted for it. Client tokens expire 60 s after minting.
const client = createDecartClient({
  apiKeyProvider: async () => {
    const res = await fetch("/api/realtime-token", { method: "POST" });
    const { apiKey } = await res.json(); // the short-lived client token, never your permanent key
    return apiKey;
  },
});

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

  return client.realtime.connect(stream, {
    model,
    onRemoteStream: (remoteStream) => {
      document.getElementById("output").srcObject = remoteStream;
    },
    initialState: {
      prompt: { text: "Anime style", enhance: true },
    },
  });
}
```

## Rotation strategy

* Mint a token right before each connect, or let `apiKeyProvider` do it for every connect and reconnect. Never mint on page load
* Use shorter TTLs (e.g. 60s) for tighter security; use longer TTLs (e.g. 300–600s) when you mint ahead of connecting
* An expired token is refused before dialling (`TOKEN_EXPIRED`). Mint a new one instead of retrying with the old
* Do not persist client tokens in local storage
* A client token cannot be revoked before `expiresAt`; use a short TTL where fast cut-off matters
* Revoke permanent keys in dashboard if you suspect leakage

<Tip>
  For production readiness, also follow the realtime reliability guide in [Streaming Best Practices](/models/realtime/streaming-best-practices).
</Tip>


# Models
Source: https://docs.platform.decart.ai/getting-started/models

Explore Decart's AI models for video and image transformation

Decart offers state-of-the-art AI models for realtime and batch video transformation, lip synchronization, and image editing. Our models are optimized for creative applications, delivering professional-quality results with minimal latency.

<Note>
  **Lucy 2.5 is the latest editing model for realtime and video — text prompts, reference images, or both.** [Get started →](/models/realtime/lucy-2.5)
</Note>

## Realtime models

Realtime models process live video and audio with low latency. They run continuously as long as the connection is open.

| Model | ID | Resolution | Use Case |
| - | - | - | - |
| **Lucy 2.5** | `lucy-2.5` | 720p | Video editing (latest) |
| **Lucy VTON 3.6** | `lucy-vton-3.6` | 720p | Virtual try-on (latest) |
| **Lucy VTON 3.5** | `lucy-vton-3.5` | 720p | Virtual try-on |
| **Lucy Restyle 2** | `lucy-restyle-2` | 720p | Video restyling |
| **Oasis 3 Preview** | `oasis-3-preview` | 768×512 | Realtime world model / driving simulator |

<Note>
  **Fast mode.** `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5` accept `speed: "fast"` at connect time for lower latency and higher throughput, with unchanged output quality. Billed at 2x the standard realtime rate; other models ignore the option. [Learn more →](/models/realtime/lucy-2.5#fast-mode)
</Note>

<Note>
  **Oasis 3 Preview** is a realtime, promptable world model — you set a scene and drive it with actions, and it generates the next camera frames. It uses the dedicated Python gRPC SDK [`decart-oasis`](https://pypi.org/project/decart-oasis/) rather than the `@decartai/sdk` realtime SDKs. [Get started →](/models/realtime/oasis-3)
</Note>

<Accordion title="Previous generation models">
  | Model | ID | Resolution | Use Case |
  | - | - | - | - |
  | **Lucy 2.1** | `lucy-2.1` | 720p | Video editing |
</Accordion>

## Video models

Video models process pre-recorded video asynchronously. Submit a job, poll for completion, then download the result.

| Model | ID | Resolution | Use Case |
| - | - | - | - |
| **Lucy 2.5** | `lucy-2.5` | 720p | Video editing (latest) |
| **Lucy VTON 3.6** | `lucy-vton-3.6` | 720p | Virtual try-on (latest) |
| **Lucy VTON 3.5** | `lucy-vton-3.5` | 720p | Virtual try-on |
| **Lucy Restyle 2** | `lucy-restyle-2` | 720p | Video restyling |

<Accordion title="Previous generation models">
  | Model | ID | Resolution | Use Case |
  | - | - | - | - |
  | **Lucy 2.1** | `lucy-2.1` | 720p | Video editing |
</Accordion>

## Image models

Image models edit and transform images.

| Model | ID | Resolution | Use Case |
| - | - | - | - |
| **Lucy Image 2** | `lucy-image-2` | 480p, 720p | Image editing |

## Latest aliases

Use `-latest` aliases to always target the newest version of a model family. The server resolves these to the current latest version automatically, so your code stays up to date without changes.

| Alias | Type | Currently resolves to |
| - | - | - |
| `lucy-latest` | realtime + video | `lucy-2.5` |
| `lucy-vton-latest` | realtime + video | `lucy-vton-3.6` |
| `lucy-restyle-latest` | realtime + video | `lucy-restyle-2` |
| `lucy-image-latest` | image | `lucy-image-2` |

```typescript theme={null}
// Always use the latest Lucy model — no code changes needed when new versions ship
const model = models.realtime("lucy-latest");
const result = await client.queue.submitAndPoll({
  model: models.video("lucy-latest"),
  prompt: "Anime style",
  data: videoFile,
});
```

## Technical Specifications

### Video Requirements

All video models accept MP4 files with these specifications:

* **Format:** MP4 (H.264 or VP8 codec)
* **Aspect Ratio:** 16:9 or 9:16
* **File Size:** Maximum 200MB

## Choosing the Right Model

### Decision Matrix

| If you need to... | Use this model | Why? |
| - | - | - |
| Transform or edit live video on camera | **Lucy 2.5** (`lucy-2.5`) | Character reference images + text editing in one realtime model (latest) |
| Apply artistic styles to a live stream | **Lucy Restyle 2** (`lucy-restyle-2`) | Full scene restyling in realtime |
| Transform or edit existing video | **Lucy 2.5** (`lucy-2.5`) | Best quality, fastest speed, unlimited duration, supports prompt + reference image (latest) |
| Edit or transform an image | **Lucy Image 2** (`lucy-image-2`) | Precise image editing |
| Simulate a drivable world for RL or robotics | **Oasis 3 Preview** (`oasis-3-preview`) | Realtime world model — actions in, generated camera frames out |

### Quick Start Examples

<CodeGroup>
  ```typescript Lucy 2.5 (realtime) theme={null}
  import { createDecartClient, models } from "@decartai/sdk";

  const client = createDecartClient({ apiKey: "your-api-key-here" });
  const model = models.realtime("lucy-latest");
  const stream = await navigator.mediaDevices.getUserMedia({
    video: { frameRate: model.fps, width: model.width, height: model.height },
  });

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

  // Character transformation
  const photo = document.querySelector("input[type=file]").files[0];
  await realtimeClient.set({ prompt: "Transform into this character", image: photo, enhance: true });
  ```

  ```typescript Lucy Restyle 2 (realtime) theme={null}
  import { createDecartClient, models } from "@decartai/sdk";

  const client = createDecartClient({ apiKey: "your-api-key-here" });
  const realtimeClient = await client.realtime.connect(stream, {
    model: models.realtime("lucy-restyle-2"),
    onRemoteStream: (s) => { document.getElementById("output").srcObject = s; },
    initialState: { prompt: { text: "Cartoon style", enhance: true } },
  });

  // Switch styles on the fly
  realtimeClient.setPrompt("Cyberpunk city");
  ```

  ```typescript Lucy 2.5 (batch) theme={null}
  import { createDecartClient, models } from "@decartai/sdk";

  const client = createDecartClient({ apiKey: "your-api-key-here" });
  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-latest"),
    prompt: "Anime style transformation",
    data: videoFile,
    resolution: "720p",
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("output.mp4", buffer);
  }
  ```
</CodeGroup>

## Pricing

<Note>
  For detailed pricing information, see the [Pricing page](/getting-started/pricing).
</Note>

## Next Steps

<CardGroup>
  <Card title="Lucy 2.5 Guide" icon="sparkles" href="/models/realtime/lucy-2.5">
    Character transformation with reference images in realtime
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/examples/use-cases">
    Explore what you can build with realtime and batch models
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/getting-started/quickstart">
    Transform your first video in minutes
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/lucy-21">
    Detailed API documentation
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript">
    Build with our JavaScript SDK
  </Card>

  <Card title="Streaming Best Practices" icon="bolt" href="/models/realtime/streaming-best-practices">
    Optimize your realtime integration
  </Card>
</CardGroup>


# Overview
Source: https://docs.platform.decart.ai/getting-started/overview

Build with Decart's realtime AI video models. Transform live streams, generate videos, edit images, and animate avatars through a simple API.

Decart provides state-of-the-art AI models for transforming videos and images — both in realtime and as batch jobs — through a simple API.

<Note>
  **New: Lucy 2.5 Realtime** — Edit any live video stream with text prompts, reference images, or both. Add, remove, or replace objects, swap characters, or restyle the whole scene. [Learn more →](/models/realtime/lucy-2.5)
</Note>

## Get started in 3 steps

<Steps>
  <Step title="Get your API key">
    Sign up at [platform.decart.ai](https://platform.decart.ai) — you get free credits to start.
  </Step>

  <Step title="Install the SDK">
    ```bash theme={null}
    npm install @decartai/sdk
    ```

    Also available for [Python](/sdks/python), [Swift](/sdks/swift), and [Android](/sdks/android).
  </Step>

  <Step title="Run the example below">
    Copy the code, plug in your key, and you'll see transformed video in seconds.
  </Step>
</Steps>

## Try it: realtime character transform

This is the fastest way to see Decart in action. Open your camera, upload a face, and watch yourself become that character live:

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const model = models.realtime("lucy-latest");
const stream = await navigator.mediaDevices.getUserMedia({
  video: { frameRate: model.fps, width: model.width, height: model.height },
}).catch((err) => { console.error("Camera access failed:", err.message); throw err; });

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

const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (remoteStream) => {
    document.getElementById("output").srcObject = remoteStream;
  },
  onError: (err) => console.error("Connection error:", err),
  onDisconnect: (reason) => console.log("Disconnected:", reason),
  initialState: {
    prompt: {
      text: "Substitute the character in the video with the person in the reference image.",
      enhance: true,
    },
    image: referencePhoto, // File, Blob, or URL
  },
});
```

<Tip>
  See the [Quickstart](/getting-started/quickstart) for full error handling, camera permission flows, and reconnection patterns.
</Tip>

## What you can build

<CardGroup>
  <Card title="Realtime Character Transform" icon="masks-theater" href="/models/realtime/lucy-2.5">
    Become any character on camera with Lucy 2.5 — upload a face, see yourself transformed live
  </Card>

  <Card title="Realtime Style Transfer" icon="bolt" href="/models/realtime/video-restyling">
    Turn any live video stream into anime, cyberpunk, oil paintings, and more via WebRTC
  </Card>

  <Card title="Video Processing" icon="video" href="/models/video/overview">
    Edit videos with AI
  </Card>

  <Card title="Image Editing" icon="image" href="/models/image/image-editing">
    Transform and edit images with text prompts
  </Card>

  <Card title="Realtime Video Editing" icon="wand-magic-sparkles" href="/models/realtime/lucy-2.5">
    Add, remove, or modify objects in live video with text prompts
  </Card>
</CardGroup>

## More examples

<Tabs>
  <Tab title="Realtime Style Transfer">
    Apply artistic styles to a live camera stream:

    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";

    const model = models.realtime("lucy-restyle-2");
    const stream = await navigator.mediaDevices.getUserMedia({
      video: { frameRate: model.fps, width: model.width, height: model.height },
    }).catch((err) => {
      console.error("Camera access failed:", err.message);
      throw err;
    });

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

    const realtimeClient = await client.realtime.connect(stream, {
      model,
      onRemoteStream: (s) => {
        document.getElementById("output").srcObject = s;
      },
      onError: (err) => console.error("Connection error:", err),
      onDisconnect: (reason) => console.log("Disconnected:", reason),
      initialState: {
        prompt: { text: "Studio Ghibli animation", enhance: true },
      },
    });

    // Switch styles on the fly
    realtimeClient.setPrompt("Cyberpunk city with neon lights");
    ```
  </Tab>

  <Tab title="Video Editing">
    Transform a video file with a single API call:

    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";
    import { readFileSync, writeFileSync } from "fs";

    const client = createDecartClient({ apiKey: process.env.DECART_API_KEY });
    const source = new Blob([readFileSync("input.mp4")], { type: "video/mp4" });

    const result = await client.queue.submitAndPoll({
      model: models.video("lucy-latest"),
      data: source,
      prompt: "Transform into anime style",
      onStatusChange: (job) => console.log(job.status),
    });

    if (result.status === "completed") {
      const buffer = Buffer.from(await result.data.arrayBuffer());
      writeFileSync("output.mp4", buffer);
    }
    ```
  </Tab>

  <Tab title="Image Editing">
    Edit an image synchronously:

    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";
    import { readFileSync } from "fs";

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

    const imageBuffer = readFileSync("input.jpg");
    const imageBlob = new Blob([imageBuffer], { type: "image/jpeg" });

    const result = await client.process({
      model: models.image("lucy-image-2"),
      prompt: "Transform into a watercolor painting style",
      data: imageBlob,
      resolution: "720p",
    });

    document.querySelector("img").src = URL.createObjectURL(result);
    ```
  </Tab>
</Tabs>

[View full quickstart →](/getting-started/quickstart)

## Which API should I use?

Most users start with the **Realtime API** above. If you need batch processing or image editing, here's how the three APIs compare:

| You want to... | API | SDK method |
| - | - | - |
| Transform live camera/video in an interactive app | **Realtime API** | `client.realtime.connect()` |
| Generate or edit videos asynchronously | **Queue API** | `client.queue.submitAndPoll()` |
| Edit images synchronously | **Process API** | `client.process()` |

## Explore

<CardGroup>
  <Card title="Lucy 2.5 Realtime" href="/models/realtime/lucy-2.5" icon="masks-theater">
    Our flagship realtime model — text and reference-image editing at 720p
  </Card>

  <Card title="All Models" href="/getting-started/models" icon="layer-group">
    Compare all Decart models side by side
  </Card>

  <Card title="Quickstart" href="/getting-started/quickstart" icon="rocket">
    Transform your first video in minutes
  </Card>

  <Card title="API Reference" href="/api-reference/lucy-21" icon="code">
    Complete API documentation
  </Card>

  <Card title="SDKs" href="/sdks/javascript" icon="js">
    JavaScript, Python, Swift, and Android libraries
  </Card>

  <Card title="Examples" href="/examples/overview" icon="code">
    Realtime-first starter examples and repo links
  </Card>

  <Card title="Pricing" href="/getting-started/pricing" icon="credit-card">
    Simple pay-as-you-go pricing
  </Card>
</CardGroup>


# Preset Studio
Source: https://docs.platform.decart.ai/getting-started/preset-studio

Save, organize, share, and version reusable prompts and reference images.

Preset Studio saves a prompt, a reference image, or both as a reusable preset. Use presets in compatible model playgrounds, organize them in folders, share them with an organization, and restore earlier versions.

[Open Preset Studio](https://platform.decart.ai/studio)

<Info>
  Sign in to your Decart account to manage presets. You do not need an API key. Generating a preview uses credits from your account.
</Info>

## Get started

### Create your first preset in 3 steps

<Steps>
  <Step title="Open Preset Studio">
    Sign in to [platform.decart.ai](https://platform.decart.ai), then open [Preset Studio](https://platform.decart.ai/studio).
  </Step>

  <Step title="Create your first preset">
    Select **Create Preset**. Add a name and a prompt, a reference image, or both.

    Choose a model family, or choose **Any model** to use the preset across supported model playgrounds.
  </Step>

  <Step title="Apply the preset">
    Open a compatible model playground. In the preset picker, select **Mine**, then choose your preset.

    The model playground loads the preset's current prompt, reference image, and prompt-enhancement setting.
  </Step>
</Steps>

### What is a preset?

A preset is a reusable set of model inputs. It contains a prompt, a reference image, or both.

A preset can also store:

* A model family and prompt-enhancement setting
* A generated preview
* A folder and visibility setting
* Version history and notes

Applying a preset loads its current saved content. Changes you make afterward in the model playground do not update the preset.

## Create and manage presets

### Ways to create a preset

Create a preset from:

* Preset Studio, by selecting **Create Preset**
* A model playground, by selecting **Save as preset** to reuse its current inputs
* A quickstart template, by saving a copy or customizing it

### Create from scratch

<Steps>
  <Step title="Start a new preset">
    Open [Preset Studio](https://platform.decart.ai/studio) and select **Create Preset**.
  </Step>

  <Step title="Add its content">
    Enter a name and add a prompt, a reference image, or both. Reference images can be JPEG, PNG, or WebP files.
  </Step>

  <Step title="Choose a model">
    Select a model family to limit the preset to compatible model playgrounds. Select **Any model** to make it available across supported model families.
  </Step>

  <Step title="Configure prompt enhancement">
    Turn **Enhance prompt** on to expand the saved prompt before generation.

    <Note>
      Lucy 2.5 always enhances prompts applied from presets, regardless of the saved setting.
    </Note>
  </Step>

  <Step title="Choose visibility and a folder">
    If an organization is active, choose whether the preset is private or shared with that organization.

    You can place a model-specific preset in any compatible folder.
  </Step>

  <Step title="Configure the preview">
    Keep **Generate on save** enabled to create a preview when you save, or select **Generate preview** to review one first.

    Preview generation requires a prompt.
  </Step>

  <Step title="Create the preset">
    Optionally add a note for the first version, then select **Create preset**. The preset appears in **Mine**.
  </Step>
</Steps>

<Warning>
  Generating or regenerating a preview uses credits. **Generate on save** is enabled by default, but saving unchanged content with a matching preview does not generate another preview or use more credits.
</Warning>

### Start from a quickstart template

Preset Studio includes read-only quickstart templates.

Open a template and choose:

* **Save to my presets** to create a private copy without opening the editor
* **Customize** to open a new preset with the template's prompt, image, model, enhancement setting, and preview

Either path creates an independent copy when you save. Editing your copy does not affect the published template.

If the template has a generated preview, Preset Studio copies it without using additional credits.

### Edit a preset

In **Mine**, select a preset card to open its editor.

| Field | Save behavior |
| - | - |
| Name | Saves when you press Enter or leave the field |
| Visibility and folder | Save immediately |
| Prompt, reference image, model, **Enhance prompt**, and generated preview | Save together as a new version |

To update versioned content:

<Steps>
  <Step title="Edit the content">
    Change the prompt, reference image, model, or enhancement setting.
  </Step>

  <Step title="Describe the change">
    Optionally add a version note.
  </Step>

  <Step title="Save the version">
    Select **Save new version**. It becomes the current version immediately.
  </Step>
</Steps>

<Warning>
  Changes to an organization-shared preset affect every member who uses it.
</Warning>

### Use version history

Every preset begins with a first version. Later content changes create new versions instead of overwriting earlier ones.

The version marked **Current** is applied in model playgrounds.

To reuse an earlier version:

* Select its history row to load it, make any changes, and select **Save new version**.
* Select **Use this version** to make it current without editing it.

Neither action deletes the version it replaces.

You can delete a non-current version when at least one other version remains. Deleting the preset permanently removes the preset and its complete history.

### Preview presets

A generated preview applies the preset to a fixed sample image. If the preset contains a reference image, the reference appears as an inset.

You can:

* Select **Generate preview** to create one before saving.
* Keep **Generate on save** enabled to create one while saving.
* Disable **Generate on save** to preserve the existing preview.
* Regenerate after changing the prompt or reference image.

If preview generation fails while saving, Preset Studio still saves the preset or version and keeps the previous preview when one exists.

## Organize and share presets

### Personal accounts and organizations

The workspace active when you create a preset determines where it belongs.

| Context | Visibility | Who can access the preset |
| - | - | - |
| Personal | Private | Only you |
| Organization, private | Private | Only you, within that organization |
| Organization, shared | Organization | Every member of that organization |

Your personal presets remain in **Mine** while an organization is active. Switching organizations changes which organization presets and folders are available.

#### Share a personal preset with an organization

<Steps>
  <Step title="Select the organization">
    Make the target organization active.
  </Step>

  <Step title="Open the preset">
    In **Mine**, select the personal preset.
  </Step>

  <Step title="Change its visibility">
    Change **Visibility** from **Private** to the organization. This moves the preset into that organization and shares it with every member.
  </Step>
</Steps>

If its current folder is not compatible with the new organization or visibility, the preset moves to **General**.

#### Organization permissions

Every member of an organization can view, apply, rename, edit, version, roll back, and delete its shared presets. Only the preset creator can change visibility.

<Warning>
  Deleting an organization-shared preset permanently deletes it and its history for every member.
</Warning>

#### Share a link

Select **Copy link** on an organization-shared preset to share it with another member.

Any member of that organization can open the link, even when a different organization is active. People outside the organization cannot open it.

If the creator account is deleted, the shared preset remains available. Its creator appears as **Deleted user**, and its visibility can no longer be changed.

### Folders

Folders group the presets in **Mine** by model family.

<Steps>
  <Step title="Open your folders">
    Select **Mine** in Preset Studio.
  </Step>

  <Step title="Create a folder">
    Select the new-folder button beside **Folders**.
  </Step>

  <Step title="Configure the folder">
    Enter a name, choose a model family, and, when an organization is active, choose private or organization visibility.
  </Step>

  <Step title="Add a preset">
    Open or create a preset with the same model family, then select the folder from its **Folder** field.
  </Step>
</Steps>

Folder rules:

* Folders support one level and cannot be nested.
* Every folder belongs to one model family. Any-model presets cannot be placed in a folder.
* **General** is the default folder and a reserved name. It cannot be renamed or deleted.
* Folder names must be unique within the same model and workspace.
* An organization-shared preset can only use a shared folder from the same organization.
* You can rename or delete a folder, but cannot change its model or visibility after creation.
* Deleting a folder moves its presets to **General**; it does not delete them.

## Find and use presets

### Browse Preset Studio

| Tab | Contents |
| - | - |
| **All presets** | Your available presets and quickstart templates in one flat view |
| **Mine** | Your personal presets and presets available from the active organization |

The folder tree appears when you browse quickstart templates or **Mine**. On smaller screens, it becomes a dropdown.

Search spans the selected tab, not only the selected folder. It matches preset names and prompts, plus template descriptions.

When an organization is active, filter **Mine** by **Private** or **Organization** visibility.

### Apply a preset in a model playground

Compatible model playgrounds let you browse all presets, quickstart templates, or your saved presets.

Selecting a saved preset loads:

* Its current prompt
* Its current reference image
* Its prompt-enhancement setting
* Any-model presets alongside presets for the current model family

Select **Manage in Studio** from **Mine** to edit, organize, or delete presets.

Selecting an image-only preset does not replace text already entered in the model playground.

## Troubleshooting

<AccordionGroup>
  <Accordion title="My preset does not appear in a model playground">
    Check that you are signed in, the correct organization is active, the preset's model matches the model playground, and **Mine** or **All presets** is selected.

    Choose **Any model** if the preset should appear across model families.

    Preset Studio lists the 500 most recently created presets available in your current context. If you exceed that limit, the library reports that older presets are not listed.
  </Accordion>

  <Accordion title="I cannot select a folder">
    Choose a model family first; any-model presets cannot be placed in folders.

    The folder must use the same organization context and model family. Organization-shared presets require a shared folder.
  </Accordion>

  <Accordion title="The organization visibility option is missing">
    Select or join an organization first. Without an active organization, new presets are private.
  </Accordion>

  <Accordion title="Another member cannot see my preset">
    Confirm that the preset is shared with the intended organization and that the person is a member.

    A private preset is visible only to its creator, even when it belongs to an organization.
  </Accordion>

  <Accordion title="A shared preset appears in General instead of its folder">
    The original folder is unavailable or incompatible. It may be private, belong to another organization, or use a different model family.

    Move the preset to a compatible shared folder.
  </Accordion>

  <Accordion title="The preview button is disabled">
    Add a prompt. Generated previews require one.
  </Accordion>

  <Accordion title="I cannot rename or delete a folder">
    Open **Mine** in a desktop-sized window. Hover over or focus the custom folder in the left sidebar, then select the **•••** menu.

    Folder actions are unavailable in **All presets**, the quickstart templates, and the narrow-screen folder dropdown. You also cannot rename or delete **General**, the permanent default folder.

    A new name cannot be blank, longer than 100 characters, **General**, or the same as another folder for that model and workspace.

    Deleting a custom folder moves its presets to **General**; it does not delete them.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Open Preset Studio" icon="sliders" href="https://platform.decart.ai/studio">
    Create and manage presets.
  </Card>

  <Card title="Lucy 2.5" icon="sparkles" href="/models/realtime/lucy-2.5">
    Use prompts and reference images for realtime editing.
  </Card>

  <Card title="Virtual try-on" icon="shirt" href="/models/realtime/virtual-try-on">
    Apply saved clothing and styling presets with Lucy VTON.
  </Card>

  <Card title="Models" icon="layer-group" href="/getting-started/models">
    Compare model families.
  </Card>
</CardGroup>


# Pricing
Source: https://docs.platform.decart.ai/getting-started/pricing

Clear, usage-based pricing for Decart models

Decart uses pay-as-you-go pricing.

<Info>
  No subscriptions and no minimum spend. You pay only for usage.
</Info>

## How pricing works

* Realtime models: billed per second of active generation
* Video models: billed per generated second
* Image models: billed per generation

## Realtime models

| Model | ID | 720p | Fast mode | Best for |
| - | - | - | - | - |
| **Lucy 2.5** | `lucy-2.5` | \$0.02/sec | \$0.04/sec | Realtime video editing (latest) |
| **Lucy VTON 3.6** | `lucy-vton-3.6` | \$0.02/sec | \$0.04/sec | Virtual try-on (latest) |
| **Lucy VTON 3.5** | `lucy-vton-3.5` | \$0.02/sec | \$0.04/sec | Virtual try-on |
| **Lucy Restyle 2** | `lucy-restyle-2` | \$0.01/sec | - | Realtime style transfer |
| **Oasis 3 Preview** | `oasis-3-preview` | \$0.02/sec | - | Realtime world model / driving simulator |

<Note>
  **Fast mode** (`speed: "fast"`) gives the session lower latency and higher throughput; output quality is unchanged. It is available for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5`, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode. See [Fast mode](/models/realtime/lucy-2.5#fast-mode).
</Note>

<Note>
  Oasis 3 Preview is billed at **\$0.02 per second**, with enterprise pricing available depending on the use case — contact `contact@decart.ai`.
</Note>

<Accordion title="Previous generation models">
  | Model | ID | 720p | Best for |
  | - | - | - | - |
  | **Lucy 2.1** | `lucy-2.1` | \$0.02/sec | Realtime video editing |
</Accordion>

## Video models

| Model | ID | 480p | 720p | Best for |
| - | - | - | - | - |
| **Lucy 2.5** | `lucy-2.5` | - | \$0.04/sec | Video editing (latest) |
| **Lucy VTON 3.6** | `lucy-vton-3.6` | - | \$0.04/sec | Virtual try-on (latest) |
| **Lucy VTON 3.5** | `lucy-vton-3.5` | - | \$0.04/sec | Virtual try-on |
| **Lucy Restyle 2** | `lucy-restyle-2` | - | \$0.01/sec | Video restyling |

<Accordion title="Previous generation models">
  | Model | ID | 480p | 720p | Best for |
  | - | - | - | - | - |
  | **Lucy 2.1** | `lucy-2.1` | - | \$0.04/sec | Video editing |
</Accordion>

## Image models

| Model | ID | 480p | 720p | Best for |
| - | - | - | - | - |
| **Lucy Image 2** | `lucy-image-2` | \$0.01 | \$0.02 | Image editing |

## Cost examples

* 5-second video edit with `lucy-2.5` (720p): `5 x $0.04 = $0.20`
* 30-second realtime Lucy 2.5 session: `30 x $0.02 = $0.60`
* 30-second realtime Lucy 2.5 session in fast mode (`speed: "fast"`): `30 x $0.04 = $1.20`
* One 720p image edit with `lucy-image-2`: `$0.02`
* 60-second Oasis 3 Preview session: `60 x $0.02 = $1.20`

## FAQ

<AccordionGroup>
  <Accordion title="Do you have a free tier?">
    New accounts receive free credits so you can test the API before paying.
  </Accordion>

  <Accordion title="How is video billing calculated?">
    Video jobs are billed per generated second. Realtime is billed per active generation time.
  </Accordion>

  <Accordion title="Do you offer enterprise pricing?">
    Yes. Contact `contact@decart.ai` for custom volume pricing.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Model comparison" href="/getting-started/models" icon="layer-group">
    Pick the best quality/speed/cost tradeoff for your product.
  </Card>

  <Card title="Get started" href="https://platform.decart.ai" icon="arrow-right">
    Create an account and run your first request.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.platform.decart.ai/getting-started/quickstart

Go from API key to first Decart output in minutes

Get your first successful Decart result in under 5 minutes.

## Prerequisites

* A Decart account at [platform.decart.ai](https://platform.decart.ai)
* An [API key](/getting-started/authentication)

```bash theme={null}
export DECART_API_KEY="your-api-key-here"
```

<Tip>
  Using an AI coding agent? Run `npx skills add https://docs.platform.decart.ai` to teach it Decart's APIs, or [connect the MCP server](/getting-started/ai-coding-agents) for live docs search.
</Tip>

## Pick your first integration path

<Tabs>
  <Tab title="Realtime">
    ### 1) Install SDK

    ```bash theme={null}
    npm install @decartai/sdk
    ```

    ### 2) Connect camera + model

    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";

    const model = models.realtime("lucy-latest");

    // Request camera access — will throw if the user denies permission
    let stream: MediaStream;
    try {
      stream = await navigator.mediaDevices.getUserMedia({
        video: { frameRate: model.fps, width: model.width, height: model.height },
        audio: true,
      });
    } catch (err) {
      if (err instanceof DOMException && err.name === "NotAllowedError") {
        console.error("Camera permission denied. Please allow camera access and reload.");
      } else {
        console.error("Could not access camera:", err);
      }
      throw err;
    }

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

    const realtimeClient = await client.realtime.connect(stream, {
      model,
      mirror: "auto",
      onRemoteStream: (remoteStream) => {
        document.getElementById("output").srcObject = remoteStream;
      },
      onError: (err) => {
        console.error("Realtime connection error:", err);
      },
      onDisconnect: (reason) => {
        console.log("Disconnected:", reason);
      },
      initialState: {
        prompt: { text: "Substitute the character in the video with an anime-style hero with spiky silver hair and glowing blue eyes.", enhance: true },
      },
    });

    // Switch to a different transformation on the fly
    await realtimeClient.setPrompt("Substitute the character in the video with a Renaissance oil painting portrait.");
    ```

    ### Expected result

    You should see the transformed stream rendered in your output video element.

    <Warning>
      **Common issues:**

      * **Camera permission denied** — the browser will prompt the user. If denied, `getUserMedia` throws a `NotAllowedError`.
      * **No camera found** — throws a `NotFoundError`. Check that a video device is connected.
      * **Connection drops** — the `onDisconnect` callback fires. In production, implement reconnection logic.
    </Warning>

    <Tip>
      For browser/mobile production setups, use [Client Tokens](/getting-started/client-tokens) instead of exposing a permanent API key. They expire after 60 seconds by default, so fetch them per dial with `apiKeyProvider` rather than on page load.
    </Tip>
  </Tab>

  <Tab title="Video Editing">
    ### 1) Submit + poll with the SDK

    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";
    import { writeFileSync } from "fs";

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

    const result = await client.queue.submitAndPoll({
      model: models.video("lucy-latest"),
      data: "https://example.com/input_video.mp4",
      prompt: "Transform into Studio Ghibli animation style",
      onStatusChange: (job) => console.log(`Status: ${job.status}`),
    });

    if (result.status === "completed") {
      const buffer = Buffer.from(await result.data.arrayBuffer());
      writeFileSync("transformed_video.mp4", buffer);
    }
    ```

    ### 2) Same flow in multiple languages

    <CodeGroup>
      ```typescript JavaScript SDK theme={null}
      import { createDecartClient, models } from "@decartai/sdk";

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

      const result = await client.queue.submitAndPoll({
        model: models.video("lucy-latest"),
        data: "https://example.com/input_video.mp4",
        prompt: "Transform into Studio Ghibli animation style",
        onStatusChange: (job) => console.log(job.status),
      });
      ```

      ```python Python SDK theme={null}
      import asyncio
      import os
      from decart import DecartClient, models

      async def main():
          async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
              result = await client.queue.submit_and_poll({
                  "model": models.video("lucy-latest"),
                  "data": "https://example.com/input_video.mp4",
                  "prompt": "Transform into Studio Ghibli animation style",
                  "on_status_change": lambda job: print(job.status),
              })

      asyncio.run(main())
      ```

      ```bash cURL theme={null}
      JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-latest \
        -H "X-API-KEY: $DECART_API_KEY" \
        -F "data=@input_video.mp4" \
        -F "prompt=Transform into Studio Ghibli animation style" | jq -r '.job_id')

      while true; do
        STATUS=$(curl -s -H "X-API-KEY: $DECART_API_KEY" \
          https://api.decart.ai/v1/jobs/$JOB_ID | jq -r '.status')
        [ "$STATUS" = "completed" ] && break
        [ "$STATUS" = "failed" ] && exit 1
        sleep 2
      done

      curl -H "X-API-KEY: $DECART_API_KEY" \
        https://api.decart.ai/v1/jobs/$JOB_ID/content --output transformed_video.mp4
      ```
    </CodeGroup>

    ### Expected result

    You should have `transformed_video.mp4` in your current directory.
  </Tab>

  <Tab title="Image Editing">
    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";
    import { readFileSync } from "fs";

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

    const imageBuffer = readFileSync("input.jpg");
    const imageBlob = new Blob([imageBuffer], { type: "image/jpeg" });

    const result = await client.process({
      model: models.image("lucy-image-2"),
      prompt: "Transform into a watercolor painting style",
      data: imageBlob,
      resolution: "720p",
    });

    document.querySelector("img").src = URL.createObjectURL(result);
    ```
  </Tab>
</Tabs>

## Next steps

<CardGroup>
  <Card title="Lucy 2.1 Realtime" icon="sparkles" href="/models/realtime/lucy-2.1">
    Start with the flagship realtime model for character transformation.
  </Card>

  <Card title="JavaScript Realtime SDK" icon="js" href="/sdks/javascript-realtime">
    Full WebRTC integration guide.
  </Card>

  <Card title="Client Tokens" icon="shield" href="/getting-started/client-tokens">
    Secure browser/mobile realtime authentication.
  </Card>

  <Card title="Models" icon="layer-group" href="/getting-started/models">
    Pick the best model for your use case.
  </Card>

  <Card title="Examples Hub" icon="code" href="/examples/overview">
    Browse official examples and realtime-first starter projects.
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/examples/use-cases">
    See complete realtime and batch product patterns.
  </Card>
</CardGroup>


# Network Requirements
Source: https://docs.platform.decart.ai/integrations/network-requirements

Network, device, and firewall configuration for running the realtime SDK — for IT, networking, and security teams

This page specifies the network, device, and security configuration required to operate the Decart realtime streaming SDK. It is intended for the IT, networking, and security teams responsible for the deployment environment, and can be shared with an internet service provider where connectivity changes are required.

<Note>
  Updated for SDK v0.1.22 and production infrastructure as of August 2026.
</Note>

## Supported operating systems

The SDK does not hard-enforce a minimum OS or browser version. Device support is inherited from the underlying WebRTC stack, which transpiles broadly and checks capability at runtime rather than gating on a version number. The values below are recommended minimums for a reliable realtime experience — not hard cutoffs.

| Platform | Recommended | Technical floor |
| - | - | - |
| iOS / iPadOS | iOS / iPadOS 15 or later | iOS 14.3 |
| Android | Android 10 or later with the latest Chrome (or another up-to-date Chromium browser) | Android 8 with Chrome 110 |
| Desktop | Latest stable Chrome, Edge (Chromium), Firefox, or Safari | Chrome 110, Edge (Chromium) 110, Firefox 110, Safari 16 |

<Tip>
  On Android, Chrome updates independently of the OS, so a recent Chrome version matters more than the Android version number itself.
</Tip>

## Hardware requirements

The SDK processes bidirectional realtime video at \~30 fps. Sustained performance under continuous load matters more than peak spec — a device can pass these numbers and still throttle after a few minutes of thermal load.

| Component | Minimum | Recommended |
| - | - | - |
| Processor | Dual-core 2.0 GHz | Quad-core 2.5 GHz |
| GPU / video acceleration | Integrated GPU; hardware video acceleration strongly recommended | Hardware H.264/VP9/AV1 encode + decode |
| RAM (free at session start) | 2 GB | 4 GB+ |
| Architecture | 64-bit x86 or ARM | 64-bit x86 or ARM (Apple Silicon supported) |

## Network requirements

### Bandwidth per active session

Each live session is bidirectional and roughly symmetric — you send your camera upstream and receive the transformed video downstream at the same time, at 30 fps. A session typically consumes **1.3–2.4 Mbps in each direction simultaneously** in production measurements.

* **Minimum:** 3.5 Mbps per direction (the bitrate cap per stream).
* **Provision for:** 4 Mbps per direction — both upload and download — per concurrent session, which covers the cap plus protocol overhead.

### Fixed locations

For deployments where the experience must stay up consistently (for example, an in-store installation), we recommend:

* **Wired Ethernet over Wi-Fi** for the device running the session. Wi-Fi introduces packet loss and jitter that cause video freezes.
* **\~2× bandwidth headroom** over the per-session requirement (about 8 Mbps per direction, per session).
* **A business or dedicated line** if the existing connection cannot guarantee stability.

### Mobile users

Mobile reception is variable and cannot be guaranteed. The recommended pattern is to gate the feature on measured connectivity — call `checkConnectivity()` before offering the experience and only show it when the connection is good enough. See [Testing connectivity](#testing-connectivity-with-the-js-sdk).

## Connection quality thresholds

These are the exact thresholds the SDK uses to compute its live connection-quality verdict. The overall verdict is the worst dimension, smoothed over a rolling window with a short warm-up and hysteresis so it does not flicker.

| Metric | Good | Fair | Poor | Critical |
| - | - | - | - | - |
| RTT latency | ≤ 150 ms | ≤ 300 ms | ≤ 500 ms | > 500 ms |
| Packet loss | ≤ 0.1% | ≤ 1% | ≤ 5% | > 5% |
| Inbound frame rate | ≥ 20 fps | ≥ 12 fps | ≥ 5 fps | \< 5 fps |

## Quick readiness check

Run this once per fixed location, on the actual device and network:

<Steps>
  <Step title="Run a real session">
    Start a real session and let it run 2–3 minutes.
  </Step>

  <Step title="Confirm the quality verdict">
    Confirm the connection-quality verdict holds at `"good"` (or at worst `"fair"`) for the whole run — monitor it with the `onConnectionQuality` callback shown in [In-session monitoring](#in-session-warn-or-degrade-if-reception-drops).
  </Step>

  <Step title="Watch for stalls and bandwidth limits">
    Watch for any `videoStall` events or `limitingFactor === "bandwidth"` — either one means the network is not ready.

    ```typescript theme={null}
    rt.on("diagnostic", (event) => {
      if (event.name === "videoStall") {
        console.log(event.data.stalled ? "stalled" : "recovered", event.data.durationMs);
      }
    });
    ```
  </Step>

  <Step title="Prefer wired">
    If both Wi-Fi and wired are available, test both and prefer wired.
  </Step>
</Steps>

## Firewall and network configuration

### Domains to allow (production)

| Domain | Purpose | Protocol |
| - | - | - |
| `api.decart.ai` | REST API, authentication, session setup, realtime signaling (WebSocket) | HTTPS and WSS / TCP 443 |
| `platform.decart.ai` | SDK telemetry, authentication, billing | HTTPS / TCP 443 |
| `lk.decart.ai` | Realtime media signaling (US-West) | WSS / TCP 443 |
| `*.lkc.decart.ai` | Realtime media signaling, regional edge servers | WSS / TCP 443 |
| `stun.l.google.com` | STUN, used by the pre-connect connectivity check | UDP 19302 |

<Warning>
  `*.lkc.decart.ai` is required, not optional. Sessions are routed to the nearest regional media server based on client geography, worldwide. A wildcard entry is necessary because the specific hostname a session receives is assigned at connect time. Allowlisting only `lk.decart.ai` will work in US-West and fail everywhere else.
</Warning>

Regional media servers worldwide are served as `<region>.lkc.decart.ai` (for example `eu-west-1.lkc.decart.ai`), and new regions are added regularly — allow the wildcard rather than individual hostnames.

<Note>
  Staging environments use `api.stage-decart.com` and `livekit.stage-decart.com`.
</Note>

### Ports and protocols

| Port / protocol | Direction | Purpose |
| - | - | - |
| TCP 443 | Outbound | HTTPS and secure WebSocket (WSS) signaling. Always required. |
| UDP 7882 | Outbound | WebRTC media. Required. |
| UDP 3478 | Outbound | TURN relay, used when a direct path is unavailable. |
| UDP 19302 | Outbound | STUN, for the pre-connect connectivity check. |

* **Media-server IPs are dynamic.** Allow by protocol and port, not by fixed destination IP. This applies to UDP 3478 as well: the TURN relay is advertised to the client as a per-session server IP, so there is no single TURN hostname or address to allowlist.
* **DTLS/SRTP:** media is encrypted. Do not attempt to inspect it.

### UDP traffic and proxy configuration

This is the most common cause of "it connects but the video freezes" problems:

* WebRTC prefers UDP (port 7882). Allow outbound UDP where possible.
* Do not force media through an HTTP/HTTPS proxy that cannot pass UDP if you want the low-latency path.
* For SNI / transparent proxies: allow the domains above, and do not TLS-intercept (decrypt) `turn.decart.ai`; doing so breaks the connection.

## Testing connectivity with the JS SDK

The JS SDK exposes two connectivity signals — a quality verdict (`good | fair | poor | critical`) and a limiting factor (`bandwidth | latency | loss | stall | cpu | none`).

### Pre-connect: decide whether to show the feature

Checks whether WebRTC can leave the network over UDP, and measures path latency:

```typescript theme={null}
const { quality, metrics, reasons } = await client.realtime.checkConnectivity();
// quality: "good" | "fair" | "poor" | "critical"
// metrics.transport: "udp" | "relay" | "failed"

if (quality === "critical") showFallback(reasons);
```

### In-session: warn or degrade if reception drops

A smoothed live verdict based on the SDK's WebRTC stats, using the [thresholds above](#connection-quality-thresholds):

```typescript theme={null}
const rt = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (remoteStream) => {
    videoElement.srcObject = remoteStream;
  },
  onConnectionQuality: ({ quality, limitingFactor }) => {
    updateSignalBars(quality);
    if (quality === "poor") warnUser(limitingFactor);
  },
});
```

## Next steps

<CardGroup>
  <Card title="Streaming Best Practices" icon="video" href="/models/realtime/streaming-best-practices">
    Camera setup, connection management, and error handling
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript-realtime">
    Full reference for the connectivity and diagnostics APIs
  </Card>
</CardGroup>


# Realtime Integration Paths
Source: https://docs.platform.decart.ai/integrations/overview

Choose how to connect your platform to Decart's realtime AI models

Integrate Decart's realtime video AI models — Lucy Restyle Live and Lucy — into your platform and offer them to your users. Choose from multiple integration paths based on how much control you need over the end-user experience.

## Integration paths

Decart realtime models use **WebRTC** for media (video and audio) and a **control plane** for signaling, prompts, and session events. Each integration path differs in how you connect to the control plane — media quality is identical across all paths.

| Path | How it works | White-label | Provider visibility | Client requirements | Your infrastructure |
| - | - | - | - | - | - |
| [SDK Direct](/integrations/sdk-direct) | Your app embeds the Decart SDK | No | Session events only | WebRTC + Decart SDK | Token minting only |
| [WS Signaling Proxy](/integrations/signaling-proxy-ws) | You proxy WebSocket signaling, WebRTC stays direct | Yes | Full | WebRTC (no SDK) | WS proxy server |
| [HTTP Signaling](/integrations/signaling-proxy-http) | You proxy stateless HTTP calls, WebRTC stays direct | Yes | Full | WebRTC (no SDK) | Stateless HTTP proxy |

## Choosing a path

**Do you need white-label?** If it's OK for your users to connect to Decart endpoints directly (visible in network traffic) and depend on the Decart SDK, use [SDK Direct](/integrations/sdk-direct) — it's the simplest path with zero infrastructure overhead.

**If you do need white-label**, choose based on your infrastructure: if your gateway is HTTP-native (most API platforms), use [HTTP Signaling](/integrations/signaling-proxy-http). If you already run WebSocket infrastructure, use [WS Signaling Proxy](/integrations/signaling-proxy-ws). Both deliver identical media quality.

## Authentication

All integration paths use the same authentication system. You receive a Decart API key for your platform and use it to authenticate requests on behalf of your users.

* **Permanent keys** are used server-side to authenticate with Decart
* **Client tokens** are short-lived keys for browser/mobile use — see [Client Tokens](/getting-started/client-tokens)
* Usage is tracked per API key, so you get full visibility into your users' consumption

<Info>
  Your API key is scoped to your platform. Decart tracks usage per key, so you can query consumption and build your own billing on top.
</Info>

## Next steps

<CardGroup>
  <Card title="SDK Direct" icon="plug" href="/integrations/sdk-direct">
    Simplest path — embed the Decart SDK in your app
  </Card>

  <Card title="WS Signaling Proxy" icon="arrows-left-right" href="/integrations/signaling-proxy-ws">
    White-label with WebSocket proxy
  </Card>

  <Card title="HTTP Signaling" icon="globe" href="/integrations/signaling-proxy-http">
    White-label with stateless HTTP proxy
  </Card>
</CardGroup>


# SDK Direct
Source: https://docs.platform.decart.ai/integrations/sdk-direct

Embed the Decart SDK in your app for the simplest integration path

Your application embeds the Decart SDK directly. End users connect to Decart for both signaling (WebSocket) and media (WebRTC). You handle authentication and billing on your side.

This is the simplest integration path — no proxy infrastructure, no protocol translation, full media quality.

## When to use this path

* You want the fastest integration with zero infrastructure overhead
  It's OK for end users to connect to Decart endpoints directly (visible in network traffic)
* You're building a wrapper app, marketplace listing, or plugin that surfaces Decart models

<Tip>
  If you already use Decart's batch models (video editing, image editing), SDK Direct for realtime works the same way — same API key, same SDK, same billing.
</Tip>

## Characteristics

| Property | Value |
| - | - |
| White-label | No — end users see Decart endpoints and SDK |
| Frame access | No |
| Provider visibility | Session events only (`generationTick`, `connectionChange`) |
| Client requirements | Browser or native app with WebRTC + Decart SDK |
| Your infrastructure | Backend for token minting only |

<Check>
  Media quality is identical to using Decart directly. There is no degradation — the SDK connects straight to Decart.
</Check>

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant B as Your Backend
    participant D as Decart
    participant F as Your Frontend<br/>(Decart SDK)

    B->>D: POST /v1/client/tokens (your API key)
    D-->>B: { apiKey: "eyJ...", expiresAt }
    B->>F: Pass client token

    F->>D: WS connect (signaling)
    F->>D: WebRTC media (P2P)
    D->>F: WebRTC media (P2P)

    Note over F,D: Media flows p2p over WebRTC
```

## How it works

<Steps>
  <Step title="Create a client token on your backend">
    Use your platform API key to mint a short-lived client token. This keeps your permanent key server-side.

    ```typescript theme={null}
    // Your backend
    const client = createDecartClient({ apiKey: process.env.DECART_API_KEY });
    const clientToken = await client.tokens.create(); // expires in 60 s by default
    // Return clientToken.apiKey to your frontend
    ```
  </Step>

  <Step title="Connect from the frontend">
    Your frontend hands the SDK a function that fetches the client token; it runs before every connect and reconnect, so no dial uses a stale token. The SDK handles WebSocket signaling, WebRTC negotiation, ICE candidates, and auto-reconnection.

    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";

    const model = models.realtime("lucy-2.1");
    const stream = await navigator.mediaDevices.getUserMedia({
      video: { frameRate: model.fps, width: model.width, height: model.height },
    });

    // Fetched right before every connect and reconnect; client tokens expire after 60 s.
    const client = createDecartClient({
      apiKeyProvider: async () => {
        const res = await fetch("/api/realtime-token", { method: "POST" }); // your backend route from step 1
        const { apiKey } = await res.json();
        return apiKey;
      },
    });

    const rt = await client.realtime.connect(stream, {
      model,
      onRemoteStream: (remoteStream) => {
        videoElement.srcObject = remoteStream;
      },
    });

    await rt.set({ prompt: "Anime style", enhance: true });
    ```
  </Step>

  <Step title="Control the generation">
    Use `set()` to replace the session state at any time. Include all fields you want to keep — omitted fields are cleared:

    ```typescript theme={null}
    // Set a new prompt (clears any previous image)
    await rt.set({ prompt: "Cyberpunk neon city" });

    // Set a reference image with a prompt
    await rt.set({
      prompt: "Transform into this character",
      image: selectedFile,  // File, Blob, base64 string, or null to clear
    });

    // Disable prompt enhancement for exact control
    await rt.set({ prompt: "Exact prompt text", enhance: false });
    ```
  </Step>

  <Step title="Listen to events">
    Track session state and usage with event listeners:

    ```typescript theme={null}
    rt.on("connectionChange", (state) => {
      // "connecting" | "connected" | "generating" | "disconnected" | "reconnecting"
      updateStatusIndicator(state);
    });

    rt.on("generationTick", ({ seconds }) => {
      // Total elapsed generation time (cumulative, not a delta)
      updateUsageDisplay(seconds);
    });

    rt.on("error", (error) => {
      // DecartSDKError with message and context
      console.error("Decart error:", error.message);
    });
    ```
  </Step>

  <Step title="Disconnect when done">
    Clean up the session when the user leaves. This closes the WebSocket and WebRTC connections.

    ```typescript theme={null}
    rt.disconnect();
    ```
  </Step>
</Steps>

## API reference

### `connect(stream, options)`

Creates a new realtime session and establishes the WebRTC connection.

```typescript theme={null}
const rt = await client.realtime.connect(stream, {
  model: models.realtime("lucy-2.1"),
  onRemoteStream: (stream) => { videoElement.srcObject = stream; },
  initialState: {
    prompt: { text: "Anime style", enhance: true },
    image: selectedFile,
  },
});
```

<ParamField type="ModelDefinition">
  The realtime model — use `models.realtime("model_id")`.
</ParamField>

<ParamField type="(stream: MediaStream) => void">
  Called when the remote video/audio stream is ready.
</ParamField>

<ParamField type="object">
  Pre-configure a prompt and/or image before the first frame.
</ParamField>

<ParamField type="&#x22;h264&#x22; | &#x22;vp8&#x22; | &#x22;vp9&#x22;">
  Preferred local publish codec. Desktop Safari is always pinned to `vp8`. On React Native, use `"vp8"`.
</ParamField>

The `initialState` option lets you set a prompt and image in the same round-trip as session creation — the model starts generating with your configuration from the first frame.

### `set(input)`

Replace the session state with a new prompt, reference image, or both. Fields not included are cleared. At least one of `prompt` or `image` is required. Awaits server acknowledgment — throws if rejected by moderation or on timeout.

```typescript theme={null}
await rt.set({ prompt: "Anime style", enhance: true, image: file });
```

<ParamField type="string">
  The text prompt to apply.
</ParamField>

<ParamField type="boolean">
  Enhance the prompt automatically. Set to `false` for exact prompt text.
</ParamField>

<ParamField type="Blob | File | string | null">
  Reference image. Pass `null` to clear the current image. Strings are treated as base64.
</ParamField>

### `setPrompt(prompt, options?)`

Set the prompt and wait for server acknowledgment. Throws if the prompt is rejected by moderation or the request times out (15 seconds).

```typescript theme={null}
try {
  await rt.setPrompt("Anime style", { enhance: true });
} catch (error) {
  // Prompt was rejected by moderation or timed out
  console.error(error.message);
}
```

<ParamField type="boolean">
  Enhance the prompt automatically.
</ParamField>

### `setImage(image, options?)`

Set a reference image and wait for server acknowledgment. Throws if the image is rejected by moderation or the request times out.

```typescript theme={null}
try {
  await rt.setImage(selectedFile, {
    prompt: "Transform into this character",
    enhance: true,
  });
} catch (error) {
  // Image was rejected by moderation or timed out
  console.error(error.message);
}
```

<ParamField type="string">
  Set a prompt alongside the image.
</ParamField>

<ParamField type="boolean">
  Enhance the prompt automatically.
</ParamField>

<ParamField type="number">
  Timeout in milliseconds.
</ParamField>

<Warning>
  Reference images must be under 10 MB. The SDK rejects oversized images before sending them.
</Warning>

### `disconnect()`

End the session and clean up all WebRTC and WebSocket connections.

```typescript theme={null}
rt.disconnect();
```

### `isConnected()`

Returns `true` if the SDK has an active connection.

```typescript theme={null}
if (rt.isConnected()) {
  await rt.set({ prompt: "New prompt" });
}
```

### `getConnectionState()`

Returns the current connection state.

```typescript theme={null}
const state = rt.getConnectionState();
// "connecting" | "connected" | "generating" | "disconnected" | "reconnecting"
```

### `sessionId`

The current session identifier, or `null` if not connected.

```typescript theme={null}
console.log("Session:", rt.sessionId);
```

### Events

Listen to events with `rt.on(event, listener)` and remove listeners with `rt.off(event, listener)`.

| Event | Payload | Description |
| - | - | - |
| `connectionChange` | `ConnectionState` | Connection state changed — `"connecting"`, `"connected"`, `"generating"`, `"disconnected"`, `"reconnecting"` |
| `generationTick` | `{ seconds: number }` | Total elapsed generation time (cumulative). Use for billing. |
| `error` | `DecartSDKError` | An error occurred. The error has a `message` property with details. |

<Note>
  The SDK automatically handles ICE restarts and WebRTC reconnection. You don't need to manage the WebRTC lifecycle — just listen to `connectionChange` to update your UI.
</Note>

## Error handling

The SDK surfaces errors through the `error` event and by throwing from async methods like `set()`, `setPrompt()`, and `setImage()`.

```typescript theme={null}
// Global error listener
rt.on("error", (error) => {
  console.error("Decart error:", error.message);

  if (!rt.isConnected()) {
    // Connection lost — show reconnecting UI or clean up
    showReconnectingState();
  }
});

// Per-call error handling
try {
  await rt.setPrompt("Transform into anime character");
} catch (error) {
  // Moderation rejection or timeout
  showNotification("Prompt not accepted. Try a different description.");
}
```

Common error scenarios:

* **Moderation rejection** — prompt or image violates content policy. Caught by `set()`, `setPrompt()`, and `setImage()` (all throw on rejection).
* **Connection lost** — network issue or server disconnect. The SDK attempts to reconnect automatically. Listen to `connectionChange` for state transitions.
* **Invalid API key** — the session fails to connect. Caught during `connect()`.
* **Insufficient credits** — the session ends with a `connectionChange` to `"disconnected"`.

## Next steps

<CardGroup>
  <Card title="Client Tokens" icon="key" href="/getting-started/client-tokens">
    Set up secure token rotation for frontend auth
  </Card>

  <Card title="Streaming Best Practices" icon="gauge-high" href="/models/realtime/streaming-best-practices">
    Optimize camera setup, prompts, and error handling
  </Card>
</CardGroup>


# HTTP Signaling
Source: https://docs.platform.decart.ai/integrations/signaling-proxy-http

Use stateless HTTP endpoints for signaling with direct WebRTC media

<Warning>
  HTTP signaling is in private preview. [Contact us](mailto:contact@decart.ai) to request access.
</Warning>

Your platform proxies stateless HTTP control endpoints for WebRTC signaling and session control. Media (video and audio) flows directly between the end user and Decart over WebRTC. A long-lived Server-Sent Events (SSE) stream carries server-to-client events.

A single `POST` creates the session, exchanges the SDP offer/answer, and optionally sets the initial prompt and reference image — all in one round-trip.

## When to use this path

* Your platform is HTTP-native (REST API gateway, serverless functions, containers)
* You want white-label endpoints without managing stateful WebSocket connections
* You want to use standard API gateway tooling (rate limiting, auth, logging)
* You prefer stateless infrastructure that scales horizontally

<Tip>
  This is the recommended path for most API platforms. If you can proxy HTTP, you can integrate Decart realtime.
</Tip>

## Characteristics

| Property | Value |
| - | - |
| White-label | Yes — end users only see your HTTP URLs |
| Frame access | No — media bypasses your proxy |
| Provider visibility | Full — you see every HTTP request (prompts, images, session events) |
| Client requirements | Browser or native app with WebRTC (no Decart SDK needed) |
| Your infrastructure | Stateless HTTP proxy + one SSE stream per active session |

<Check>
  Media quality is identical to using Decart directly. HTTP signaling adds marginal latency to infrequent control operations — not to the video stream.
</Check>

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant U as End User
    participant P as Your HTTP Proxy
    participant D as Decart

    rect rgb(240, 245, 255)
    Note over U,D: Session + SDP Exchange (single round-trip)
    U->>P: POST /sessions {model, sdp_offer, prompt?, image?}
    P->>D: POST /v1/realtime/sessions
    D-->>P: 201 Created {sdp_answer, ice_servers, event_token}
    P-->>U: 201 Created {sdp_answer, ice_servers, event_token}
    end
    rect rgb(245, 240, 255)
    Note over U,D: SSE + ICE Trickle
    U->>P: GET /sessions/{id}/events?event_token=...
    P->>D: GET /v1/realtime/sessions/{id}/events?event_token=...
    D-->>P: SSE stream
    P-->>U: SSE stream
    U->>P: PATCH /sessions/{id} {candidates}
    P->>D: PATCH /v1/realtime/sessions/{id}
    D-->>P: 204 No Content
    P-->>U: 204 No Content
    end

    rect rgb(240, 255, 240)
    Note over U,D: Session Control (stateless HTTP calls)
    U->>P: POST /sessions/{id}/prompt
    P->>D: POST /v1/realtime/sessions/{id}/prompt
    D-->>P: 200 OK
    P-->>U: 200 OK
    end

    Note over U,D: WebRTC media flows directly to Decart<br/>Video & audio bypass your proxy entirely
    U->>D: WebRTC media (direct)
    D->>U: WebRTC media (direct)
```

## How it works

<Steps>
  <Step title="Create session and exchange SDP">
    A single `POST` creates the realtime session, exchanges the SDP offer/answer, and returns ICE server configuration. You can optionally include an initial prompt and reference image to pre-configure the generation before the first frame.

    Your backend sends the model selection and the client's SDP offer. Decart returns a `201 Created` with the SDP answer, a `Location` header pointing to the session resource, and an `ETag` for ICE session tracking.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.decart.ai/v1/realtime/sessions \
        -H "x-api-key: $DECART_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "lucy-2.1",
          "sdp": {
            "type": "offer",
            "sdp": "v=0\r\no=- 123 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0 1\r\n..."
          },
          "prompt": "Anime style portrait",
          "enhance_prompt": true
        }'
      ```

      ```http Response theme={null}
      HTTP/1.1 201 Created
      Location: https://api.decart.ai/v1/realtime/sessions/rs_abc123
      ETag: "ice-1a2b3c"
      Content-Type: application/json

      {
        "session_id": "rs_abc123",
        "sdp": {
          "type": "answer",
          "sdp": "v=0\r\no=- 456 2 IN IP4 34.102.85.17\r\ns=-\r\nt=0 0\r\n..."
        },
        "ice_servers": [
          { "urls": "stun:stun.l.google.com:19302" },
          {
            "urls": "turn:turn.decart.ai:3478",
            "username": "...",
            "credential": "..."
          }
        ],
        "events": {
          "url": "https://api.decart.ai/v1/realtime/sessions/rs_abc123/events",
          "event_token": "evt_eyJhbGciOi...",
          "expires_at": "2025-01-15T12:30:00Z"
        },
        "expires_at": "2025-01-15T12:30:00Z"
      }
      ```
    </CodeGroup>

    <Tip>
      The `sdp` object matches the browser's `RTCSessionDescription` format. You can pass `pc.localDescription` directly and apply the response with `pc.setRemoteDescription(response.sdp)`.
    </Tip>

    The optional fields let you front-load session configuration in the same round-trip:

    <ParamField type="string">
      Model identifier (e.g., `lucy-2.1`).
    </ParamField>

    <ParamField type="object">
      Client's SDP offer — `{ "type": "offer", "sdp": "..." }`.
    </ParamField>

    <ParamField type="string">
      Set the initial prompt before generation starts.
    </ParamField>

    <ParamField type="boolean">
      Enhance the prompt automatically (default: `true`).
    </ParamField>

    <ParamField type="string">
      Base64-encoded reference image (max 10 MB).
    </ParamField>

    <Note>
      When you include `prompt` or `image_data`, the server validates and moderates the content before creating the session. If moderation rejects it, the request fails with `422` — no session is created and no resources are allocated.
    </Note>

    The response includes everything needed to complete the WebRTC connection:

    <ResponseField name="session_id" type="string">
      Unique session identifier.
    </ResponseField>

    <ResponseField name="sdp" type="object">
      SDP answer — pass directly to `pc.setRemoteDescription(response.sdp)`.

      <Expandable title="Properties">
        <ResponseField name="type" type="string">
          Always `"answer"`.
        </ResponseField>

        <ResponseField name="sdp" type="string">
          Full SDP string (same format as `RTCSessionDescription.sdp`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ice_servers" type="array">
      ICE server configuration — pass to `new RTCPeerConnection({ iceServers: response.ice_servers })`.
    </ResponseField>

    <ResponseField name="events" type="object">
      SSE connection details for the server event stream.

      <Expandable title="Properties">
        <ResponseField name="url" type="string">
          SSE endpoint URL.
        </ResponseField>

        <ResponseField name="event_token" type="string">
          Ephemeral token for SSE auth — safe to pass to the client.
        </ResponseField>

        <ResponseField name="expires_at" type="string">
          ISO 8601 expiration timestamp.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      ISO 8601 session expiration timestamp.
    </ResponseField>
  </Step>

  <Step title="Trickle ICE candidates and open SSE">
    Right after session creation, forward ICE candidates from the client using `PATCH` with the `If-Match` header. The client opens the SSE stream using the `event_token` from the session response.

    The candidate format matches `RTCIceCandidate.toJSON()` — forward them directly from the browser. Signal end-of-candidates by sending a `null` candidate.

    <CodeGroup>
      ```bash ICE Candidate theme={null}
      curl -X PATCH https://api.decart.ai/v1/realtime/sessions/rs_abc123 \
        -H "x-api-key: $DECART_API_KEY" \
        -H "Content-Type: application/json" \
        -H 'If-Match: "ice-1a2b3c"' \
        -d '{
          "candidates": [
            {
              "candidate": "candidate:1 1 UDP 2130706431 192.168.1.5 54321 typ host",
              "sdpMLineIndex": 0,
              "sdpMid": "0"
            }
          ]
        }'
      ```

      ```bash End of Candidates theme={null}
      curl -X PATCH https://api.decart.ai/v1/realtime/sessions/rs_abc123 \
        -H "x-api-key: $DECART_API_KEY" \
        -H "Content-Type: application/json" \
        -H 'If-Match: "ice-2b3c4d"' \
        -d '{
          "candidates": [null]
        }'
      ```

      ```http Response theme={null}
      HTTP/1.1 204 No Content
      ETag: "ice-2b3c4d"
      ```
    </CodeGroup>

    Server-side ICE candidates are delivered via the [SSE event stream](#handle-server-events-sse). The server sends `null` as the last candidate to signal end-of-candidates from its side.

    <Note>
      **ETag is required on every `PATCH`.** If you omit `If-Match`, the server responds with `428 Precondition Required`. If the ETag doesn't match (another ICE operation completed first), you get `412 Precondition Failed` — call `GET /v1/realtime/sessions/{id}` to fetch the current ETag and retry. The server queues concurrent ICE candidates correctly, so rapid-fire PATCHes work as long as each carries a valid ETag.
    </Note>
  </Step>

  <Step title="Handle server events (SSE)">
    The client opens an SSE connection using the `event_token` from the session creation response. Handle generation lifecycle, server-side ICE candidates, moderation alerts, and errors.

    ```typescript theme={null}
    const events = new EventSource(
      `https://api.yourplatform.com/v1/realtime/sessions/${sessionId}/events?event_token=${encodeURIComponent(eventToken)}`
    );

    events.addEventListener("generation_started", () => {
      showLiveIndicator();
    });

    events.addEventListener("generation_tick", (e) => {
      const { seconds } = JSON.parse(e.data);
      updateUsageDisplay(seconds);
    });

    events.addEventListener("ice-candidate", (e) => {
      const data = JSON.parse(e.data);
      if (data.candidate === null) {
        // Server signals end-of-candidates
        peerConnection.addIceCandidate(null);
      } else {
        const { candidate, sdpMLineIndex, sdpMid } = data;
        peerConnection.addIceCandidate({ candidate, sdpMLineIndex, sdpMid });
      }
    });

    events.addEventListener("ice-restart", async (e) => {
      const { ice_servers } = JSON.parse(e.data);
      // Server requests ICE restart — reconfigure with new TURN credentials
      peerConnection.setConfiguration({ iceServers: ice_servers });
      const offer = await peerConnection.createOffer({ iceRestart: true });
      await peerConnection.setLocalDescription(offer);
      // Send PATCH with If-Match: "*" and the new SDP offer
    });


    events.addEventListener("generation_ended", (e) => {
      const { seconds, reason } = JSON.parse(e.data);
      finalizeSession(seconds, reason);
      // SSE stream closes after this event
    });

    events.addEventListener("error", (e) => {
      const error = JSON.parse(e.data);
      handleError(error.title, error.detail);
    });
    ```

    <Tip>
      The SSE stream is your only channel for server-initiated messages. Keep it open for the entire session. When the session ends, the server sends `generation_ended` followed by a final empty `data: ` field, then closes the stream. If the connection drops mid-session, reconnect — `EventSource` handles this automatically with the `Last-Event-ID` header. If you reconnect after the session has already ended, the server responds with `410 Gone`.
    </Tip>
  </Step>

  <Step title="Send prompts and images">
    Control the generation with stateless HTTP calls — no persistent connection needed.

    <CodeGroup>
      ```bash Prompt theme={null}
      curl -X POST https://api.decart.ai/v1/realtime/sessions/rs_abc123/prompt \
        -H "x-api-key: $DECART_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"prompt": "Anime style", "enhance_prompt": true}'
      ```

      ```json Response theme={null}
      {
        "prompt": "Anime style"
      }
      ```
    </CodeGroup>

    <CodeGroup>
      ```bash Reference Image theme={null}
      curl -X POST https://api.decart.ai/v1/realtime/sessions/rs_abc123/image \
        -H "x-api-key: $DECART_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "image_data": "<base64-encoded image>",
          "prompt": "Transform into this character",
          "enhance_prompt": true
        }'
      ```

      ```http Response theme={null}
      HTTP/1.1 200 OK
      Content-Type: application/json

      {}
      ```
    </CodeGroup>

    The prompt response echoes back the original prompt text. A `200` status code confirms the content was accepted — no additional `success` field is needed. Both endpoints moderate input content synchronously — if the content is rejected, the API returns `422 Unprocessable Entity`:

    ```json theme={null}
    {
      "type": "https://api.decart.ai/errors/moderation-rejected",
      "title": "Input rejected by moderation",
      "detail": "Content violates our Terms of Service",
      "status": 422
    }
    ```

    <Warning>
      Reference images must be under 10 MB (base64-encoded). Requests with oversized images are rejected with `413 Content Too Large`.
    </Warning>
  </Step>

  <Step title="Handle ICE restart (if needed)">
    If the network path degrades, the server sends an `ice-restart` SSE event with updated TURN credentials. Respond by creating a new SDP offer (with the provided ICE servers) and sending it as a `PATCH` with `If-Match: "*"` (wildcard).

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X PATCH https://api.decart.ai/v1/realtime/sessions/rs_abc123 \
        -H "x-api-key: $DECART_API_KEY" \
        -H "Content-Type: application/json" \
        -H 'If-Match: "*"' \
        -d '{
          "sdp": {
            "type": "offer",
            "sdp": "v=0\r\no=- 123 3 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\n..."
          }
        }'
      ```

      ```http Response theme={null}
      HTTP/1.1 200 OK
      ETag: "ice-4d5e6f"
      Content-Type: application/json

      {
        "sdp": {
          "type": "answer",
          "sdp": "v=0\r\no=- 456 3 IN IP4 34.102.85.17\r\ns=-\r\nt=0 0\r\n..."
        }
      }
      ```
    </CodeGroup>

    The response includes a new `ETag` — use it for any subsequent ICE operations.

    <Note>
      ICE restarts are server-initiated. The server makes one restart attempt with TURN credentials — if it fails, the session ends with a `generation_ended` event (reason: `"ice_failure"`).
    </Note>
  </Step>

  <Step title="End the session">
    Explicitly close the session when the user disconnects. The response includes a session summary with billing information.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X DELETE https://api.decart.ai/v1/realtime/sessions/rs_abc123 \
        -H "x-api-key: $DECART_API_KEY"
      ```

      ```json Response theme={null}
      {
        "session_id": "rs_abc123",
        "duration_seconds": 120,
        "billed_seconds": 120,
        "reason": "disconnect"
      }
      ```
    </CodeGroup>

    Sessions also end automatically when:

    * The WebRTC connection fails and ICE restart does not recover it
    * A moderation violation terminates the stream
    * The session reaches the maximum duration
    * No media activity is detected (inactivity timeout)

    In all cases, a `generation_ended` SSE event is sent before the stream closes.
  </Step>
</Steps>

## API reference

### Endpoints

| Method | Path | Description |
| - | - | - |
| `POST` | `/v1/realtime/sessions` | Create session + exchange SDP offer/answer |
| `PATCH` | `/v1/realtime/sessions/{id}` | Trickle ICE candidates or trigger ICE restart |
| `GET` | `/v1/realtime/sessions/{id}` | Read session state, current ETag, and refresh `event_token` |
| `GET` | `/v1/realtime/sessions/{id}/events` | SSE stream for server events |
| `POST` | `/v1/realtime/sessions/{id}/prompt` | Set or update the model prompt |
| `POST` | `/v1/realtime/sessions/{id}/image` | Set reference image (with optional prompt) |
| `DELETE` | `/v1/realtime/sessions/{id}` | End the session and return billing summary |

### Session state

Use `GET /v1/realtime/sessions/{id}` to recover state after reconnects, to fetch the current ETag before retrying a `412` ICE operation, or to obtain a fresh `event_token` if the SSE connection dropped.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.decart.ai/v1/realtime/sessions/rs_abc123 \
    -H "x-api-key: $DECART_API_KEY"
  ```

  ```json Response theme={null}
  {
    "session_id": "rs_abc123",
    "state": "active",
    "etag": "ice-2b3c4d",
    "events": {
      "url": "https://api.decart.ai/v1/realtime/sessions/rs_abc123/events",
      "event_token": "evt_freshTokenHere...",
      "expires_at": "2025-01-15T12:30:00Z"
    },
    "expires_at": "2025-01-15T12:30:00Z",
    "started_at": "2025-01-15T12:00:00Z",
    "generation_seconds": 36,
    "billed_seconds": 36
  }
  ```
</CodeGroup>

Each `GET` returns a fresh `event_token` that expires at the same time as the session. This avoids the need for a separate token refresh endpoint.

### Authentication

All control endpoints require an `x-api-key` header with a valid Decart API key. The SSE endpoint uses a short-lived `event_token` returned by `POST /v1/realtime/sessions` (and refreshable via `GET /v1/realtime/sessions/{id}`):

```
GET /v1/realtime/sessions/{id}/events?event_token=EVT_TOKEN
```

<Note>
  The `event_token` is scoped to one session and expires when the session does. This avoids placing your long-lived API key in browser-visible URLs while keeping `x-api-key` as the upstream authentication method for all other endpoints. The token is ephemeral, read-only (SSE is server-to-client), and safe to pass to the client.
</Note>

### SSE event types

| Event | Data | Description |
| - | - | - |
| `ice-candidate` | `{"candidate": "...", "sdpMLineIndex": 0, "sdpMid": "0"}` | Server-side ICE candidate — forward to `RTCPeerConnection`. A `null` candidate signals end-of-candidates. |
| `ice-restart` | `{"ice_servers": [{"urls": "turn:...", "username": "...", "credential": "..."}]}` | Server requests ICE restart — reconfigure and send new offer via `PATCH` |
| `generation_started` | `{}` | Model is producing frames — media will start flowing |
| `generation_tick` | `{"seconds": 30}` | Total elapsed generation time in seconds (cumulative, not a delta). Use for usage tracking. |
| `generation_ended` | `{"seconds": 120, "reason": "disconnect"}` | Session complete. SSE stream closes after this event. |
| `error` | `{"type": "...", "title": "...", "detail": "...", "status": 500}` | Server error |

The `generation_ended` reason field indicates why the session ended:

| Reason | Description |
| - | - |
| `disconnect` | Client disconnected |
| `timeout` | Session reached the maximum duration |
| `moderation_violation` | Content policy violation terminated the stream |
| `error` | Server error |
| `insufficient_credits` | Account has insufficient credits |

### Error responses

All errors return a structured JSON body:

```json theme={null}
{
  "type": "https://api.decart.ai/errors/invalid-sdp",
  "title": "Invalid SDP offer",
  "detail": "Missing ice-ufrag attribute in the SDP offer",
  "status": 400
}
```

| Status | When |
| - | - |
| `400` | Malformed request body or invalid SDP |
| `401` | Missing or invalid API key |
| `404` | Session not found or expired |
| `410` | Session ended — SSE reconnect after termination |
| `412` | `If-Match` ETag doesn't match current ICE session state |
| `413` | Image exceeds the 10 MB size limit |
| `422` | Valid JSON but semantically invalid (unsupported model, content rejected by moderation) |
| `428` | `PATCH` sent without required `If-Match` header |
| `503` | Service temporarily unavailable — check the `Retry-After` header |

## Provider proxy example

Your control endpoints stay stateless — every request is an independent pass-through, including SSE. The client provides the `event_token` (received during session creation) to connect to the SSE stream through your proxy.

```typescript theme={null}
// Next.js / Express — all routes are stateless pass-through
app.all("/v1/realtime/*", async (req, res) => {
  const decartUrl = `https://api.decart.ai${req.path}${req.url.includes("?") ? req.url.substring(req.url.indexOf("?")) : ""}`;

  // Build headers — inject API key, forward If-Match for ICE operations
  const headers: Record<string, string> = {
    "x-api-key": process.env.DECART_API_KEY!,
  };
  if (req.headers["content-type"]) {
    headers["Content-Type"] = req.headers["content-type"] as string;
  }
  if (req.headers["if-match"]) {
    headers["If-Match"] = req.headers["if-match"] as string;
  }
  const response = await fetch(decartUrl, {
    method: req.method,
    headers,
    body: ["GET", "DELETE"].includes(req.method)
      ? undefined
      : JSON.stringify(req.body),
  });
  // Forward response headers
  for (const header of ["location", "etag"]) {
    const value = response.headers.get(header);
    if (value) res.setHeader(header, value);
  }

  // SSE — pipe the stream directly to the client
  if (req.path.endsWith("/events")) {
    res.status(response.status);
    res.setHeader("Content-Type", "text/event-stream");
    res.setHeader("Cache-Control", "no-cache");
    res.setHeader("Connection", "keep-alive");
    response.body?.pipeTo(
      new WritableStream({
        write(chunk) { res.write(chunk); },
        close() { res.end(); },
      })
    );
    return;
  }
  if (response.status === 204) {
    return res.status(204).end();
  }
  const data = await response.json();
  res.status(response.status).json(data);
});
```

<Info>
  Your proxy must forward the `ETag` and `Location` headers from Decart's response, and pass through `If-Match` from client requests. The `event_token` is ephemeral, session-scoped, and read-only — safe to pass to the client. You can still add your own authentication, rate limiting, and logging on top.
</Info>

## Client implementation

Your client talks to your HTTP proxy for signaling and handles WebRTC with standard browser APIs.

```javascript theme={null}
const pc = new RTCPeerConnection({
  iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
});

pc.ontrack = (event) => {
  document.getElementById("remote-video").srcObject = event.streams[0];
};

const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: 1280, height: 720, frameRate: 20 },
  audio: true,
});
stream.getTracks().forEach((track) => pc.addTrack(track, stream));

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

// Create session — SDP exchange + ICE servers in one round-trip
const BASE = "https://api.yourplatform.com/v1/realtime";
const createRes = await fetch(`${BASE}/sessions`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "lucy-2.1",
    sdp: { type: "offer", sdp: offer.sdp },
    prompt: "Anime style",
    enhance_prompt: true,
  }),
});

const session = await createRes.json();
const sessionId = session.session_id;
let etag = createRes.headers.get("ETag");

await pc.setRemoteDescription(session.sdp);
pc.setConfiguration({ iceServers: session.ice_servers });

// Queue candidates and flush serially to maintain ETag ordering
const candidateQueue = [];
let flushing = false;

async function flushCandidates() {
  if (flushing || candidateQueue.length === 0) return;
  flushing = true;
  const batch = candidateQueue.splice(0);
  const res = await fetch(`${BASE}/sessions/${sessionId}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json", "If-Match": etag },
    body: JSON.stringify({ candidates: batch }),
  });
  etag = res.headers.get("ETag") || etag;
  flushing = false;
  if (candidateQueue.length > 0) flushCandidates();
}

pc.onicecandidate = ({ candidate }) => {
  candidateQueue.push(candidate ? candidate.toJSON() : null);
  flushCandidates();
};

// SSE for server-initiated events
const sse = new EventSource(
  `${BASE}/sessions/${sessionId}/events?event_token=${encodeURIComponent(session.events.event_token)}`
);

sse.addEventListener("ice-candidate", async (e) => {
  const data = JSON.parse(e.data);
  await pc.addIceCandidate(data.candidate === null ? null : data);
});

sse.addEventListener("ice-restart", async (e) => {
  const { ice_servers } = JSON.parse(e.data);
  pc.setConfiguration({ iceServers: ice_servers });
  const restartOffer = await pc.createOffer({ iceRestart: true });
  await pc.setLocalDescription(restartOffer);
  // If-Match: "*" bypasses ETag sequencing during restarts
  const res = await fetch(`${BASE}/sessions/${sessionId}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json", "If-Match": "*" },
    body: JSON.stringify({ sdp: { type: "offer", sdp: restartOffer.sdp } }),
  });
  etag = res.headers.get("ETag") || etag;
  await pc.setRemoteDescription((await res.json()).sdp);
});

sse.addEventListener("generation_started", () => {
  document.getElementById("status").textContent = "● Live";
});

sse.addEventListener("generation_tick", (e) => {
  document.getElementById("usage").textContent = `${JSON.parse(e.data).seconds}s`;
});

sse.addEventListener("generation_ended", () => {
  document.getElementById("status").textContent = "Ended";
  sse.close();
});

// Session controls
window.setPrompt = (text) =>
  fetch(`${BASE}/sessions/${sessionId}/prompt`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt: text }),
  });

window.disconnect = async () => {
  await fetch(`${BASE}/sessions/${sessionId}`, { method: "DELETE" });
  stream.getTracks().forEach((t) => t.stop());
  sse.close();
  pc.close();
};
```

<Note>
  The queue-and-flush pattern batches ICE candidates into fewer `PATCH` requests while maintaining ETag ordering. In production, retry `412` responses by fetching the current ETag with `GET /sessions/{id}`.
</Note>

## Next steps

<CardGroup>
  <Card title="WebSocket Signaling Proxy" icon="arrows-left-right" href="/integrations/signaling-proxy-ws">
    Alternative: proxy via WebSocket instead of HTTP
  </Card>

  <Card title="Authentication" icon="key" href="/getting-started/authentication">
    API key management and client tokens
  </Card>
</CardGroup>


# WS Signaling Proxy
Source: https://docs.platform.decart.ai/integrations/signaling-proxy-ws

Proxy WebSocket signaling for a white-labeled integration while keeping WebRTC direct

Your platform runs a WebSocket proxy that sits between the end user and Decart for the control plane (signaling, prompts, session events). Media (video and audio) flows directly between the end user and Decart over WebRTC — your proxy never touches it.

This gives you a white-labeled experience with full media quality and visibility into all control messages.

## When to use this path

* Your platform already runs WebSocket infrastructure
* You want full visibility into the control plane (prompts, images, session events)
* You want white-labeled endpoints — end users never see Decart

<Tip>
  If your platform is HTTP-native and you'd prefer not to run stateful WebSocket connections, see [HTTP Signaling](/integrations/signaling-proxy-http) — same quality, same white-label, but with stateless HTTP proxy instead.
</Tip>

## Characteristics

| Property | Value |
| - | - |
| White-label | Yes — end users only see your WS URL |
| Frame access | No — media bypasses your proxy |
| Provider visibility | Full — you see every signaling message, prompt, and image |
| Client requirements | Browser or native app with WebRTC (no Decart SDK needed) |
| Your infrastructure | WebSocket proxy server |

<Check>
  Media quality is identical to using Decart directly. Your WS proxy only handles signaling — video and audio flow peer-to-peer.
</Check>

## Reference implementation

<Card title="ws-signaling-proxy" icon="github" href="https://github.com/DecartAI/sdk/tree/main/examples/ws-signaling-proxy">
  A complete working proxy in \~200 lines of TypeScript — message buffering, close-code sanitization, structured logging, and an e2e test.
</Card>

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant U as End User
    participant P as Your WS Proxy
    participant D as Decart

    U->>P: WS connect
    P->>P: Authenticate user
    P->>D: WS connect (your API key)

    rect rgb(240, 245, 255)
    Note over U,D: WebRTC Signaling (proxied)
    U->>P: offer SDP
    P->>D: forward
    D-->>P: answer SDP
    P-->>U: answer SDP
    U->>P: ICE candidates
    P->>D: forward
    D-->>P: ICE candidates
    P-->>U: ICE candidates
    end

    rect rgb(240, 255, 240)
    Note over U,D: Control Messages (proxied)
    U->>P: prompt
    P->>P: Log / modify
    P->>D: forward
    D-->>P: prompt_ack
    P-->>U: prompt_ack
    D-->>P: generation_tick
    P-->>U: generation_tick
    D-->>P: generation_ended
    P-->>U: generation_ended
    end

    Note over U,D: WebRTC media flows directly (P2P)<br/>Video & audio bypass your proxy entirely
    U->>D: WebRTC media (direct via IP:port)
    D->>U: WebRTC media (direct via IP:port)
```

## How it works

<Steps>
  <Step title="End user connects to your WebSocket endpoint">
    The end user connects to your platform's WS URL — they never see a Decart endpoint.

    ```
    wss://api.yourplatform.com/v1/realtime?model=lucy-2.1&token=user_token
    ```
  </Step>

  <Step title="Your proxy opens a connection to Decart">
    Authenticate with Decart using your platform API key and forward the model selection.

    ```python theme={null}
    import websockets

    upstream = await websockets.connect(
        f"wss://api.decart.ai/v1/stream?api_key={DECART_API_KEY}&model={model}"
    )
    ```

    <Info>
      Your proxy connects to Decart with **your** API key.
    </Info>

    <Note>
      Forward connect-time query parameters your end users rely on — in particular `speed`. [Fast mode](/models/realtime/lucy-2.5#fast-mode) (`speed=fast`, billed at 2x) is selected on this URL; a proxy that rebuilds it with only `model` silently lands every session on the standard tier. Omit the parameter entirely for standard mode.
    </Note>
  </Step>

  <Step title="Forward messages bidirectionally">
    Pump JSON messages between the client and Decart. Every message has a `type` field. You can log, validate, or modify messages as they pass through — see the [message reference](#message-reference) for the full protocol.

    ```python theme={null}
    import asyncio
    import json

    async def client_to_upstream(client_ws, upstream_ws):
        async for raw_msg in client_ws:
            msg = json.loads(raw_msg)

            if msg["type"] == "prompt":
                log_prompt(msg["prompt"])
                # Optional: validate or modify before forwarding

            elif msg["type"] == "set_image":
                log_image_upload()
                # Optional: validate image size / content

            await upstream_ws.send(raw_msg)

    async def upstream_to_client(upstream_ws, client_ws):
        async for raw_msg in upstream_ws:
            msg = json.loads(raw_msg)

            if msg["type"] == "session_id":
                log_session(msg["session_id"])

            elif msg["type"] == "prompt_ack" and not msg["success"]:
                log_moderation_rejection(msg["error"])

            elif msg["type"] == "generation_ended":
                log_session_end(msg["seconds"], msg["reason"])

            await client_ws.send(raw_msg)

    await asyncio.gather(
        client_to_upstream(client_ws, upstream),
        upstream_to_client(upstream, client_ws),
    )
    ```
  </Step>

  <Step title="WebRTC connects directly">
    When the end user's browser receives the SDP answer and ICE candidates through your proxy, it establishes a direct WebRTC connection to Decart via the IP:port in the ICE candidates. Your proxy is not involved in media.
  </Step>

  <Step title="Handle disconnects gracefully">
    When either side disconnects, close the other connection. Your proxy should handle both directions:

    ```python theme={null}
    async def proxy_session(client_ws, model):
        upstream = await websockets.connect(
            f"wss://api.decart.ai/v1/stream?api_key={DECART_API_KEY}&model={model}"
        )
        try:
            await asyncio.gather(
                client_to_upstream(client_ws, upstream),
                upstream_to_client(upstream, client_ws),
            )
        except websockets.ConnectionClosed:
            pass
        finally:
            await upstream.close()
    ```
  </Step>
</Steps>

## Message reference

Your proxy forwards JSON messages between the client and Decart. Every message has a `type` field that identifies it.

<Tabs>
  <Tab title="Client → Decart">
    Messages your proxy receives from the client and forwards to Decart.

    <AccordionGroup>
      <Accordion title="offer — SDP offer to establish WebRTC">
        ```json theme={null}
        { "type": "offer", "sdp": "v=0\r\no=- 123 2 IN IP4 127.0.0.1\r\n..." }
        ```

        The `sdp` field is a string containing the full SDP (same format as `RTCSessionDescription.sdp`). Forward as-is.
      </Accordion>

      <Accordion title="ice-candidate — ICE candidate for connectivity">
        ```json theme={null}
        {
          "type": "ice-candidate",
          "candidate": {
            "candidate": "candidate:1 1 UDP 2130706431 192.168.1.5 54321 typ host",
            "sdpMLineIndex": 0,
            "sdpMid": "0",
            "usernameFragment": "ab12"
          }
        }
        ```

        Forward as-is. The candidate format matches `RTCIceCandidate.toJSON()` — `usernameFragment` is optional and may be present depending on the browser. Signal end-of-candidates by sending `null`:

        ```json theme={null}
        { "type": "ice-candidate", "candidate": null }
        ```
      </Accordion>

      <Accordion title="prompt — Text prompt for the model">
        ```json theme={null}
        { "type": "prompt", "prompt": "Anime style portrait", "enhance_prompt": true }
        ```

        | Field | Type | Description |
        | - | - | - |
        | `prompt` | `string` | The text prompt to apply |
        | `enhance_prompt` | `boolean` | When `true` (default), the server enhances the prompt automatically before applying it. Set to `false` to use the exact prompt text. |

        You **can** validate, filter, or replace this message before forwarding.
      </Accordion>

      <Accordion title="set_image — Reference image with optional prompt">
        ```json theme={null}
        {
          "type": "set_image",
          "image_data": "<base64-encoded image>",
          "prompt": "Transform into this character",
          "enhance_prompt": true
        }
        ```

        | Field | Type | Description |
        | - | - | - |
        | `image_data` | `string \| null` | Base64-encoded image (max 10 MB decoded). Send `null` to clear the current reference image. |
        | `prompt` | `string` | Optional. Set a prompt alongside the image. |
        | `enhance_prompt` | `boolean` | Optional. Enhance the prompt automatically (default: `true`). |

        You **can** validate or reject this message before forwarding.

        <Warning>
          Reference images must be under 10 MB (decoded). Oversized images are rejected by the server.
        </Warning>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Decart → Client">
    Messages your proxy receives from Decart and forwards to the client.

    <AccordionGroup>
      <Accordion title="answer — SDP answer for WebRTC">
        ```json theme={null}
        { "type": "answer", "sdp": "v=0\r\no=- 456 2 IN IP4 34.102.85.17\r\n..." }
        ```

        Forward as-is. The client applies this with `pc.setRemoteDescription({ type: "answer", sdp: msg.sdp })`.
      </Accordion>

      <Accordion title="ice-candidate — ICE candidate from server">
        ```json theme={null}
        {
          "type": "ice-candidate",
          "candidate": {
            "candidate": "candidate:1 1 UDP 2130706431 34.102.85.17 12345 typ host",
            "sdpMLineIndex": 0,
            "sdpMid": "0",
            "usernameFragment": "ab12"
          }
        }
        ```

        Forward as-is. A `null` candidate signals end-of-candidates from the server side.

        <Info>
          ICE candidates are high-frequency during connection setup. Avoid logging individual candidates — log connection state changes instead.
        </Info>
      </Accordion>

      <Accordion title="session_id — Session identifier for tracking">
        ```json theme={null}
        {
          "type": "session_id",
          "session_id": "abc123",
          "server_ip": "34.102.85.17",
          "server_port": 12345
        }
        ```

        Log the `session_id` for tracking and support. The `server_ip` and `server_port` indicate which Decart server is handling this session.
      </Accordion>

      <Accordion title="prompt_ack — Prompt accepted or rejected">
        ```json theme={null}
        { "type": "prompt_ack", "prompt": "Anime style portrait", "success": true, "error": null }
        ```

        When moderation rejects a prompt:

        ```json theme={null}
        { "type": "prompt_ack", "prompt": "...", "success": false, "error": "Content violates our Terms of Service" }
        ```

        Forward to the client so they know whether their prompt was applied. The `prompt` field echoes back the original text.
      </Accordion>

      <Accordion title="set_image_ack — Image accepted or rejected">
        ```json theme={null}
        { "type": "set_image_ack", "success": true, "error": null }
        ```

        When moderation rejects an image:

        ```json theme={null}
        { "type": "set_image_ack", "success": false, "error": "Content violates our Terms of Service" }
        ```

        Forward to the client so they know whether their image was applied.
      </Accordion>

      <Accordion title="generation_started — Model is producing frames">
        ```json theme={null}
        { "type": "generation_started" }
        ```

        Media will start flowing over the WebRTC connection after this message.
      </Accordion>

      <Accordion title="generation_tick — Periodic billing update">
        ```json theme={null}
        { "type": "generation_tick", "seconds": 30 }
        ```

        The `seconds` field is the total elapsed generation time (cumulative, not a delta). Use this for usage tracking and billing.
      </Accordion>

      <Accordion title="generation_ended — Session complete">
        ```json theme={null}
        { "type": "generation_ended", "seconds": 120, "reason": "disconnect" }
        ```

        The WebSocket connection closes shortly after this message. The `reason` field indicates why the session ended:

        | Reason | Description |
        | - | - |
        | `disconnect` | Client disconnected |
        | `timeout` | Session reached the maximum duration |
        | `moderation_violation` | Content policy violation terminated the stream |
        | `error` | Server error |
        | `insufficient_credits` | Account has insufficient credits |
      </Accordion>

      <Accordion title="error — Error occurred">
        ```json theme={null}
        { "type": "error", "error": "Connection failed" }
        ```

        The `error` field is a human-readable error string. Forward to the client or handle in your proxy.
      </Accordion>

      <Accordion title="ice-restart — ICE restart with new TURN credentials">
        ```json theme={null}
        {
          "type": "ice-restart",
          "turn_config": {
            "username": "...",
            "credential": "...",
            "server_url": "turn:turn.decart.ai:3478"
          }
        }
        ```

        When present, `turn_config` provides fresh TURN credentials. Forward to the client — they should reconfigure their peer connection with the new TURN server and create a new SDP offer.

        <Note>
          ICE restarts are server-initiated. If the restart fails, the session ends with a `generation_ended` message (reason: `"error"`).
        </Note>
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Moderation

Prompts and images are moderated server-side before being applied to the model. Your proxy sees the result as acknowledgment messages:

* **Prompt accepted** → `prompt_ack` with `success: true`
* **Prompt rejected** → `prompt_ack` with `success: false` and an `error` string
* **Image accepted** → `set_image_ack` with `success: true`
* **Image rejected** → `set_image_ack` with `success: false` and an `error` string

Rejected content is not applied — the model continues with the previous prompt or image. Your proxy can add its own moderation layer before forwarding messages to Decart.

## Usage tracking

Track usage by watching the generation lifecycle messages:

```python theme={null}
async def upstream_to_client(upstream_ws, client_ws, session):
    async for raw_msg in upstream_ws:
        msg = json.loads(raw_msg)

        if msg["type"] == "generation_started":
            session.mark_started()

        elif msg["type"] == "generation_tick":
            session.record_usage(seconds=msg["seconds"])

        elif msg["type"] == "generation_ended":
            session.finalize(
                total_seconds=msg["seconds"],
                reason=msg["reason"],
            )

        await client_ws.send(raw_msg)
```

## Proxy example

A complete WebSocket proxy using Python and `websockets`. This example authenticates the client, connects upstream, pumps messages with logging, and handles disconnects:

```python theme={null}
import asyncio
import json
import websockets

DECART_API_KEY = "your-api-key"  # Load from environment in production

async def handle_client(client_ws):
    # 1. Authenticate the client and extract model (and optional speed) from query params
    model = parse_model_from_query(client_ws.request)
    speed = parse_speed_from_query(client_ws.request)  # "fast" for fast mode, else None
    user = authenticate_user(client_ws.request)
    if not user:
        await client_ws.close(4001, "Unauthorized")
        return

    # 2. Open upstream connection to Decart — forward `speed` only when set
    upstream_url = f"wss://api.decart.ai/v1/stream?api_key={DECART_API_KEY}&model={model}"
    if speed:
        upstream_url += f"&speed={speed}"
    async with websockets.connect(upstream_url) as upstream_ws:
        session_id = None

        async def client_to_upstream():
            async for raw_msg in client_ws:
                msg = json.loads(raw_msg)

                if msg["type"] == "prompt":
                    print(f"[{session_id}] prompt: {msg['prompt'][:80]}")

                elif msg["type"] == "set_image":
                    print(f"[{session_id}] set_image (has_prompt={bool(msg.get('prompt'))})")

                await upstream_ws.send(raw_msg)

        async def upstream_to_client():
            nonlocal session_id
            async for raw_msg in upstream_ws:
                msg = json.loads(raw_msg)

                if msg["type"] == "session_id":
                    session_id = msg["session_id"]
                    print(f"Session started: {session_id}")

                elif msg["type"] == "prompt_ack":
                    if not msg["success"]:
                        print(f"[{session_id}] prompt rejected: {msg['error']}")

                elif msg["type"] == "set_image_ack":
                    if not msg["success"]:
                        print(f"[{session_id}] image rejected: {msg['error']}")

                elif msg["type"] == "generation_started":
                    print(f"[{session_id}] generation started")

                elif msg["type"] == "generation_ended":
                    print(f"[{session_id}] ended: {msg['reason']} ({msg['seconds']}s)")
                    record_billing(user, session_id, msg["seconds"])

                elif msg["type"] == "error":
                    print(f"[{session_id}] error: {msg['error']}")

                await client_ws.send(raw_msg)

        # 3. Pump messages in both directions
        try:
            await asyncio.gather(
                client_to_upstream(),
                upstream_to_client(),
            )
        except websockets.ConnectionClosed:
            pass

    print(f"[{session_id}] connection closed")

async def main():
    async with websockets.serve(handle_client, "0.0.0.0", 8080):
        await asyncio.Future()  # Run forever

asyncio.run(main())
```

<Info>
  This proxy is stateless — it holds no session state between connections. Each WebSocket connection is an independent pass-through. You can scale horizontally by running multiple proxy instances behind a load balancer.
</Info>

## Client implementation

Your client connects to the proxy over WebSocket and handles WebRTC with standard browser APIs.

```javascript theme={null}
const ws = new WebSocket(
  "wss://api.yourplatform.com/v1/realtime?model=lucy-2.1&token=user_token"
);

const pc = new RTCPeerConnection({
  iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
});

const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: 1280, height: 720, frameRate: 20 },
  audio: true,
});
stream.getTracks().forEach((track) => pc.addTrack(track, stream));

pc.ontrack = (event) => {
  document.getElementById("remote-video").srcObject = event.streams[0];
};

pc.onicecandidate = ({ candidate }) => {
  ws.send(JSON.stringify({ type: "ice-candidate", candidate }));
};

ws.addEventListener("open", async () => {
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);
  ws.send(JSON.stringify({ type: "offer", sdp: offer.sdp }));
});

ws.addEventListener("message", async (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "answer":
      await pc.setRemoteDescription({ type: "answer", sdp: msg.sdp });
      break;

    case "ice-candidate":
      if (msg.candidate) await pc.addIceCandidate(msg.candidate);
      break;

    case "ice-restart":
      // Server rotated TURN credentials — reconfigure and restart ICE
      pc.setConfiguration({
        iceServers: [
          { urls: "stun:stun.l.google.com:19302" },
          {
            urls: msg.turn_config.server_url,
            username: msg.turn_config.username,
            credential: msg.turn_config.credential,
          },
        ],
      });
      const restartOffer = await pc.createOffer({ iceRestart: true });
      await pc.setLocalDescription(restartOffer);
      ws.send(JSON.stringify({ type: "offer", sdp: restartOffer.sdp }));
      break;

    case "generation_started":
      showLiveIndicator();
      break;

    case "generation_tick":
      updateUsageDisplay(msg.seconds);
      break;

    case "generation_ended":
      finalizeSession(msg.seconds, msg.reason);
      break;

    case "prompt_ack":
      if (!msg.success) console.warn("Prompt rejected:", msg.error);
      break;

    case "set_image_ack":
      if (!msg.success) console.warn("Image rejected:", msg.error);
      break;

    case "error":
      console.error("Server error:", msg.error);
      break;
  }
});
```

Once the session is running, send control messages at any time:

```javascript theme={null}
ws.send(JSON.stringify({
  type: "prompt",
  prompt: "Cyberpunk neon city",
  enhance_prompt: true,
}));

stream.getTracks().forEach((t) => t.stop());
ws.close();
pc.close();
```

<Note>
  Message types and fields match the [message reference](#message-reference) above. In production, add reconnection logic for WebSocket drops and monitor `pc.connectionState` for WebRTC failures.
</Note>

## Next steps

<CardGroup>
  <Card title="HTTP Signaling" icon="globe" href="/integrations/signaling-proxy-http">
    Same architecture with stateless HTTP instead of WS proxy
  </Card>

  <Card title="Authentication" icon="key" href="/getting-started/authentication">
    API key management and client tokens
  </Card>
</CardGroup>


# Image Editing
Source: https://docs.platform.decart.ai/models/image/image-editing

Learn how to edit and transform existing images with AI.

With the Decart API, you can transform and edit existing images using text prompts. Simply upload an image and describe the changes you want to make, and Lucy Image will intelligently modify your image while preserving important details.
Lucy Image excels at style transfers, object modifications, background replacements, and artistic transformations.
Our models maintain the core structure of your original image while applying your desired edits with high precision.

## Quick start

Here's a simple example using **Lucy Image**, our advanced image editing model.

<CodeGroup>
  ```bash Curl theme={null}
  curl -X POST https://api.decart.ai/v1/generate/lucy-image-2 \
    -H "X-API-KEY: $DECART_API_KEY" \
    -F "data=@input-image.jpg" \
    -F "prompt=Change the sky to sunset colors" \
    -F "resolution=720p" \
    --output edited-image.jpg
  ```

  ```python Python SDK theme={null}
  from decart_sdk import create_decart_client, models

  client = create_decart_client(api_key="your-api-key-here")

  with open("input-image.jpg", "rb") as image_file:
      result = await client.process({
          "model": models.image("lucy-image-2"),
          "prompt": "Change the sky to sunset colors",
          "resolution": "720p",
          "data": image_file
      })

  with open("edited-image.jpg", "wb") as f:
      f.write(result)
  ```

  ```javascript JavaScript SDK theme={null}
  import { createDecartClient, models } from "@decartai/sdk";

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

  const result = await client.process({
    model: models.image("lucy-image-2"),
    prompt: "Change the sky to sunset colors",
    resolution: "720p",
    data: imageFile
  });

  const img = document.querySelector("img");
  img.src = URL.createObjectURL(result);
  ```

  ```python Python (REST) theme={null}
  import requests
  import os

  with open("input-image.jpg", "rb") as image:
      response = requests.post(
          "https://api.decart.ai/v1/generate/lucy-image-2",
          headers={"X-API-KEY": os.getenv("DECART_API_KEY")},
          files={"data": image},
          data={
              "prompt": "Change the sky to sunset colors",
              "resolution": "720p"
          }
      )

  with open("edited-image.jpg", "wb") as f:
      f.write(response.content)
  ```

  ```javascript JavaScript (REST) theme={null}
  const formData = new FormData();
  formData.append("data", imageFile);
  formData.append("prompt", "Change the sky to sunset colors");
  formData.append("resolution", "720p");

  const response = await fetch("https://api.decart.ai/v1/generate/lucy-image-2", {
    method: "POST",
    headers: {
      "X-API-KEY": process.env.DECART_API_KEY,
    },
    body: formData,
  });

  const editedImage = await response.blob();
  ```
</CodeGroup>

### Parameters

* `data` (**required**) — Input image file to edit.
* `prompt` (**required**) — Text description of the changes to apply.
* `reference_image` (**optional**) — A reference image to guide the edit. Use this to show the model exactly what you want to add or change (e.g., a specific pair of sunglasses, a logo, or a style reference).
* `resolution` (**optional**) — Output size: `480p` or `720p` (default: `720p`).

<Note>
  For complete API documentation including response formats and error codes, see the [API Reference](/api-reference/lucy-image-2).
</Note>

## Available Models and Options

Decart provides different editing models to balance **precision, creativity, and cost** depending on your use case.

We currently offer:

* **Lucy Image** — our flagship editing model for precise, high-quality image transformations.

Supported resolutions:

* **720p** (720×1280) — detailed, higher quality, ideal for professional edits.
* **480p** (480×832) — faster, cheaper, well-suited for previews or smaller outputs.

## Using Reference Images

For more precise edits, **Lucy Image** supports an optional `reference_image` parameter. This allows you to provide a visual reference that guides the edit—perfect for when you want to add a specific item (like a particular style of sunglasses) or match a specific look.

<CodeGroup>
  ```bash Curl theme={null}
  curl -X POST https://api.decart.ai/v1/generate/lucy-image-2 \
    -H "X-API-KEY: $DECART_API_KEY" \
    -F "data=@input-image.jpg" \
    -F "prompt=Add these sunglasses to the person's face" \
    -F "reference_image=@sunglasses.jpg" \
    -F "resolution=720p" \
    --output edited-image.jpg
  ```

  ```python Python SDK theme={null}
  from decart_sdk import create_decart_client, models

  client = create_decart_client(api_key="your-api-key-here")

  with open("input-image.jpg", "rb") as image_file:
      with open("sunglasses.jpg", "rb") as reference_image:
          result = await client.process({
              "model": models.image("lucy-image-2"),
              "prompt": "Add these sunglasses to the person's face",
              "data": image_file,
              "reference_image": reference_image,
              "resolution": "720p"
          })

  with open("edited-image.jpg", "wb") as f:
      f.write(result)
  ```

  ```javascript JavaScript SDK theme={null}
  import { createDecartClient, models } from "@decartai/sdk";
  import { readFileSync, writeFileSync } from "fs";

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

  const imageBuffer = readFileSync("input-image.jpg");
  const imageBlob = new Blob([imageBuffer], { type: "image/jpeg" });

  const referenceBuffer = readFileSync("sunglasses.jpg");
  const referenceBlob = new Blob([referenceBuffer], { type: "image/jpeg" });

  const result = await client.process({
    model: models.image("lucy-image-2"),
    prompt: "Add these sunglasses to the person's face",
    data: imageBlob,
    reference_image: referenceBlob,
    resolution: "720p",
  });

  const buffer = Buffer.from(await result.arrayBuffer());
  writeFileSync("edited-image.jpg", buffer);
  ```
</CodeGroup>

## Prompt Engineering for Edits

Image editing requires different prompt strategies than generation. Your prompts should clearly describe what to change while implicitly indicating what to preserve. Lucy Image interprets your instructions in the context of the existing image.

Effective editing prompts are **specific about changes** (what to modify), **clear about scope** (local vs global edits), and **descriptive about the target result**. Unlike generation, you don't need to describe the entire scene—focus only on what needs to change. Lucy Image excels at identity conservation, edit precision, realism, and prompt adherence.

**Pro tip:** Longer, detailed prompts (20–30 words) describing style, appearance, and context produce significantly better results than short instructions.

## Supported Edit Types

### ✅ Best Performance

#### 1. Clothing Changes

Lucy Image excels at swapping outfits while preserving motion, pose, and identity. This is where the model truly shines.

* Example: "Change the shirt to a kimono with wide sleeves and patterned fabric"
* Example: "Replace the dress with a business suit, navy blue with pinstripes and a silk tie"

#### 2. Human/Character Replacement

Strong results when transforming people into new characters or creatures. Detailed prompts are key for maintaining pose and composition.

* Example: "Replace the person with a tiger, striped orange fur, muscular build, and glowing green eyes"
* Example: "Replace the person with a 2D anime character, big eyes, blue gown and battle scars"

#### 3. Object Replacement

Reliable for structure-preserving swaps. Ideal when replacing one object with another of similar scale.

* Example: "Replace the apple with a glowing crystal ball emitting blue light"
* Example: "Replace the car with a vintage motorcycle, chrome details and leather seat"

### ⚠️ Mixed Reliability

#### 4. Color Changes

Sometimes subtle, sometimes exaggerated. Works best with precise descriptions of material and finish.

* Example: "Change the jacket color to deep red leather with a glossy finish"
* Tip: Specify the exact shade and material properties for better control

#### 5. Adding Objects

Often attaches to the subject rather than appearing independently. Works best for wearable or handheld props.

* Example: "Add a golden crown on the person's head, decorated with ornate jewels"
* Example: "Add sunglasses, aviator style with reflective lenses"

#### 6. Global Transformations

Effective for backgrounds or scene-wide changes, but might alter the subject's identity. Use carefully when subject preservation is important.

* Example: "Transform the sunny beach into a snowy tundra with falling snowflakes"
* Warning: May change the identity or appearance of people in the image

### Additional Optimization Tips

* **Frame count matters**: For video editing, 81-frame generations produce better temporal consistency than shorter clips
* **Detail improves results**: Include style, materials, colors, and textures in your prompts
* **Be explicit about preservation**: If certain elements must remain unchanged, consider mentioning what to keep

**Bottom line:** Lucy Image performs best with detailed prompts that clearly describe the desired changes. Focus on clothing swaps, character replacements, and object substitutions for the most reliable results. Be cautious with global transformations if preserving subject identity is crucial.

## Endpoint and Full API Reference

* **Lucy Image**: [`/v1/generate/lucy-image-2`](/api-reference/lucy-image-2)

## Next steps

Now that you know the basics of image editing, you might want to check out one of these resources next.

<CardGroup>
  <Card icon="code" title="Full API reference" href="/api-reference/lucy-image-2">
    Check out all the options for image editing in the API reference.
  </Card>

  <Card icon="images" title="Non-realtime Overview" href="/models/video/overview">
    Explore all non-realtime models.
  </Card>
</CardGroup>


# Lucy 2.1 Realtime
Source: https://docs.platform.decart.ai/models/realtime/lucy-2.1

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.

<Info>
  Use Lucy 2.1 as your default realtime editing model. It supports character reference and text-only editing in the same integration.
</Info>

## Quick start

### Installation

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm install @decartai/sdk
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install decart
    ```
  </Tab>

  <Tab title="Android">
    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")
    }
    ```
  </Tab>
</Tabs>

### Transform into a character

<Tabs>
  <Tab title="JavaScript">
    ```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,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```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())
    ```
  </Tab>

  <Tab title="Android">
    ```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
    )
    ```
  </Tab>
</Tabs>

<Tip>
  Pass the prompt and/or reference image in `initialState` so the first frame is already transformed — otherwise viewers briefly see the raw camera feed.
</Tip>

## 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;
  },
});
```

<Tip>
  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.
</Tip>

## Use cases

<CardGroup>
  <Card title="Character cosplay" icon="masks-theater">
    Become any character live on camera — no costume needed. Stream as your favorite game, anime, or movie character.
  </Card>

  <Card title="Virtual try-on" icon="shirt">
    Let customers see products on themselves in realtime. Upload a model photo and map it onto the customer's live feed.
  </Card>

  <Card title="Live streaming" icon="tower-broadcast">
    Transform your appearance for Twitch, YouTube, or TikTok Live. Switch characters on the fly without interrupting your stream.
  </Card>

  <Card title="Content creation" icon="video">
    Produce character-driven video content without actors or costumes. Change your look between shots with a single API call.
  </Card>

  <Card title="Video conferencing" icon="users">
    Appear as a custom avatar in meetings. Your facial expressions and head movements transfer naturally to the reference character.
  </Card>

  <Card title="Interactive experiences" icon="gamepad">
    Build apps where users transform into characters in realtime — photo booths, AR filters, virtual events.
  </Card>
</CardGroup>

## 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.

<Steps>
  <Step title="Connect with your camera">
    Establish a WebRTC connection with your camera stream, just like any other realtime model.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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:

<CodeGroup>
  ```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)
  ```
</CodeGroup>

<Tip>
  `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.
</Tip>

## 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:

<CodeGroup>
  ```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.")
  ```
</CodeGroup>

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 \<description>." |
| **Add** | "Add \<description of object in reference image> to \<where to add it>." |
| **Replace** | "Change \<object to change> with \<description of the object in the reference image>." |
| **Change attribute** | "Change \<object to change attribute of> to \<description of new attribute>." |

<Tip>
  These templates produce the best results. The `enhance` option can improve short prompts, but starting with a well-structured prompt gives you more control over the output.
</Tip>

### Character transformation

When using a reference image, describe the character's appearance in the prompt. The more detail you provide, the closer the output matches the reference.

**"Substitute the character in the video with <span>\<description of the character in reference image></span>."**

Examples:

* *Substitute the character with <span>an older man, which has pale, wrinkled skin, light blue eyes, a powdered white wig with side curls, and wears a dark formal coat with a white ruffled neckpiece.</span>*
* *Substitute the character with <span>a young person wearing a short-sleeved pink top with white ribbon ties on the back, loose pink pants, and short brown hair tied in a side ponytail.</span>*
* *Substitute the character with <span>a furry creature, which has soft brown and orange fur, a light face with dark eye markings, a dark nose, and long claws.</span>*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Substitute the character with an older man, which has pale, wrinkled skin, light blue eyes, a powdered white wig with side curls, and wears a dark formal coat with a white ruffled neckpiece.",
  image: referenceImage,
  enhance: true,
});
```

<Note>
  Describe what you see in the reference image — skin tone, hair, clothing, distinctive features. Generic prompts like "Transform into this character" still work but produce less precise results.
</Note>

### Adding objects

Add new elements to the scene by specifying what to add and where to place it.

**"Add <span>\<description of object in reference image></span> to <span>\<where to add it></span>."**

Examples:

* *Add <span>a red conical hat, covered in sequins, with a white fluffy trim and a matching pompom</span> to <span>the person's head</span>.*
* *Add <span>a purple knit headband which features a black embroidered athletic jumping figure</span> <span>the person's head</span>.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Add a red conical hat, covered in sequins, with a white fluffy trim and a matching pompom to the person's head.",
  image: hatReference,
  enhance: true,
});
```

<Tip>
  Always specify placement ("to the person's head", "in the background", "on the table"). Without a location, the model places the object unpredictably.
</Tip>

### Replacing objects

Swap an existing element in the scene with something different.

**"Change <span>\<object to change></span> with <span>\<description of the object in the reference image></span>."**

Examples:

* *Change <span>the person's sweater</span> to <span>a red knit sweater, which has a white-outlined, gold and white striped rectangular emblem on the chest</span>.*
* *Change <span>the shirt</span> to <span>a black t-shirt, which features a large, stylized white text graphic across the chest and has a round neck</span>.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Change the person's sweater to a red knit sweater, which has a white-outlined, gold and white striped rectangular emblem on the chest.",
  image: sweaterReference,
  enhance: true,
});
```

### Changing attributes

Modify a property of an existing object — color, texture, material — without replacing the object itself.

**"Change <span>\<object to change attribute of></span> to <span>\<description of new attribute></span>."**

Examples:

* *Change <span>the wall's color</span> to <span>light blue, natural consistent paint finish</span>.*
* *Change <span>the shirt's texture</span> to <span>knitted, woven fabric</span>.*

```typescript theme={null}
// No reference image needed for attribute changes
await realtimeClient.set({
  prompt: "Change the wall's color to light blue, natural consistent paint finish.",
});
```

<Note>
  Attribute changes work without a reference image. When you do provide one, the model pulls the attribute (color, texture) from the reference.
</Note>

### Prompt tips

* **Be specific** — "a red knit sweater with a white emblem on the chest" outperforms "a red sweater"
* **Describe the reference image** — when using character transformation, describe what you see in the reference photo (skin, hair, clothing, features)
* **One edit per prompt** — combining multiple edits in a single prompt can produce unpredictable results
* **Use `enhance: true`** — prompt enhancement auto-expands short prompts, but explicit detail always wins

## Reference image best practices

For the best character transformation results. See also the [character transformation](#character-transformation) prompting pattern for how to describe your reference image in the prompt.

* **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.1 shares the same connection lifecycle as all realtime models. See the [JavaScript SDK](/sdks/javascript-realtime#connection-state), [Python SDK](/sdks/python-realtime), or [Android SDK](/sdks/android-realtime#connection-state) 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:

<CodeGroup>
  ```typescript JavaScript theme={null}
  import { createDecartClient, models, type DecartSDKError } from "@decartai/sdk";

  async function setupLucy2() {
    const model = models.realtime("lucy-2.1");

    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.1 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: "Substitute the character in the video with the person in the reference image.",
          image: file,
          enhance: true,
        });
      }
    });

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

    return realtimeClient;
  }

  setupLucy2();
  ```

  ```python Python theme={null}
  import asyncio
  from decart import DecartClient, models

  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),
          )

          # Track connection state
          @realtime.on("connection_change")
          def on_state(state):
              print(f"Connection: {state}")

          # Track billing
          @realtime.on("generation_tick")
          def on_tick(seconds):
              print(f"Usage: {seconds}s")

          # Handle errors
          @realtime.on("error")
          def on_error(error):
              print(f"Lucy 2.1 error: {error.code} {error.message}")

          # 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 Android theme={null}
  import ai.decart.sdk.*
  import ai.decart.sdk.realtime.*
  import org.webrtc.*

  val model = RealtimeModels.LUCY_2_1
  val client = DecartClient(context, DecartClientConfig(apiKey = "your-api-key"))
  client.realtime.initialize(eglBase)

  // Create camera track
  val videoSource = client.realtime.createVideoSource(false)!!
  val videoTrack = client.realtime.createVideoTrack("camera", videoSource)!!
  val enumerator = Camera2Enumerator(context)
  val capturer = enumerator.createCapturer(
      enumerator.deviceNames.first { enumerator.isFrontFacing(it) }, 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) }
      )
  )

  // Track connection state
  lifecycleScope.launch {
      client.realtime.connectionState.collect { state ->
          statusText.text = state.name
      }
  }

  // Track billing
  lifecycleScope.launch {
      client.realtime.generationTicks.collect { tick ->
          usageText.text = "${tick.seconds}s"
      }
  }

  // Handle errors
  lifecycleScope.launch {
      client.realtime.errors.collect { error ->
          Log.e("Lucy2", "Error: ${error.code} ${error.message}")
      }
  }

  // Character selection — encode the picked image and send it
  fun onCharacterSelected(imageBytes: ByteArray) {
      val base64 = Base64.encodeToString(imageBytes, Base64.NO_WRAP)
      client.realtime.setImage(
          imageBase64 = base64,
          prompt = "Substitute the character in the video with the person in the reference image.",
          enhance = true
      )
  }

  // Cleanup
  capturer.stopCapture()
  client.realtime.disconnect()
  client.release()
  eglBase.release()
  ```
</CodeGroup>

## Client-side authentication

For browser and mobile apps, use client tokens instead of your permanent API key.

<CodeGroup>
  ```typescript JavaScript theme={null}
  // Backend: generate a short-lived token (expires in 60 s by default)
  const token = await client.tokens.create();

  // Frontend: let the SDK fetch a fresh token right before every connect and reconnect
  const frontendClient = createDecartClient({
    apiKeyProvider: async () => {
      const res = await fetch("/api/realtime-token", { method: "POST" });
      const { apiKey } = await res.json();
      return apiKey;
    },
  });
  ```

  ```python Python theme={null}
  # Backend: generate a short-lived token
  token = await client.tokens.create()

  # Frontend: connect with the token
  frontend_client = DecartClient(api_key=token.api_key)
  ```

  ```kotlin Android theme={null}
  // Fetch a short-lived token from your backend
  val ephemeralKey = fetchTokenFromBackend()

  // Connect with the token
  val client = DecartClient(context, DecartClientConfig(apiKey = ephemeralKey))
  ```
</CodeGroup>

See the full pattern for [JavaScript](/sdks/javascript-realtime#client-side-authentication) or [Android](/sdks/android-realtime#client-side-authentication).

Client tokens expire 60 seconds after minting by default, so fetch them per dial with `apiKeyProvider` rather than on page load. See [Token lifetime](/getting-started/client-tokens#token-lifetime).

## Technical specifications

| Property | Value |
| - | - |
| **Model ID** | `lucy-2.1` |
| **Resolution** | 1280×720 |
| **Orientation** | Landscape (16:9) and Portrait (9:16) |
| **Transport** | WebRTC |
| **Character reference** | Yes (JPEG, PNG, WebP) |
| **Prompt enhancement** | Yes (default: enabled) |
| **Auto-reconnect** | Yes (exponential backoff, up to 5 retries) |

## Next steps

<CardGroup>
  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript-realtime">
    Full JavaScript SDK reference for realtime features
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python-realtime">
    Full Python SDK reference for realtime features
  </Card>

  <Card title="Android SDK" icon="android" href="/sdks/android-realtime">
    Full Android SDK reference for realtime features
  </Card>

  <Card title="All Models" icon="layer-group" href="/getting-started/models">
    Compare all Decart models side by side
  </Card>
</CardGroup>


# Lucy 2.5 Realtime
Source: https://docs.platform.decart.ai/models/realtime/lucy-2.5

Edit any element in a live video stream - add, replace, or remove objects, swap characters, change backgrounds, and apply effects in realtime.

> Transform any video in realtime with AI-powered editing at 720p. Lucy 2.5 is a general editing model - capable across edit type, object, and scene.

<Info>
  Use Lucy 2.5 as your default realtime editing model. It supports text prompts, reference images, or both in the same integration.
</Info>

## Quick start

### Installation

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm install @decartai/sdk
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install decart
    ```
  </Tab>

  <Tab title="Android">
    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")
    }
    ```
  </Tab>
</Tabs>

### Connect and start editing

<Tabs>
  <Tab title="JavaScript">
    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";

    const model = models.realtime("lucy-2.5");

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

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

    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,
        },
      },
    });

    await realtimeClient.set({
      prompt: "Substitute the character in the video with the person in the reference image.",
      image: characterImage,
      enhance: true,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```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.5")

            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,
                    ),
                ),
            )

            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())
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin theme={null}
    val model = RealtimeModels.LUCY_2_5

    val client = DecartClient(context, DecartClientConfig(apiKey = "your-api-key"))
    client.realtime.initialize(eglBase)

    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)

    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,
            ),
        )
    )

    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
    )
    ```
  </Tab>
</Tabs>

<Tip>
  Pass the prompt and/or reference image in `initialState` so the first frame is already transformed - otherwise viewers briefly see the raw camera feed.
</Tip>

## Model capabilities

Lucy 2.5 is designed as a general editing model - reliable across a wide range of tasks, object types, and input conditions.

| Quality dimension | Description |
| - | - |
| **Reference adherence** | Follows the provided reference image precisely |
| **Task adherence** | Executes the prompt exactly as written |
| **Aesthetic and realism** | Natural results across face, body, clothing, and environment |
| **Motion accuracy** | Tracks facial expressions, lip sync, and body movement |
| **Consistency** | Stays stable across long sessions |

### Edit types

| Edit type | Description |
| - | - |
| **Character swap** | Replace a person or character with a new identity from a reference image |
| **Virtual try-on** | Swap clothing or accessories onto a person |
| **Add** | Insert a new object into the scene |
| **Replace** | Swap an existing object with something different |
| **Remove** | Clean removal of objects with background reconstruction |
| **Background** | Swap the scene environment |
| **Style transformation** | Apply a global visual aesthetic to the entire video |
| **Visual effects** | Add dynamic effects - fire, explosions, smoke, particles |

<Info>
  Virtual try-on has a dedicated optimized model. See the [Lucy - Virtual try-on model](/models/realtime/virtual-try-on) for details.
</Info>

## Use cases

<CardGroup>
  <Card title="Virtual try-on" icon="shirt">
    Let customers see clothing and accessories on themselves in realtime. Supports a wide range of garment types, materials, and body conditions.
  </Card>

  <Card title="Ad variation" icon="megaphone">
    Generate personalized ad creatives at scale. Swap products, backgrounds, or characters across live or pre-recorded content without reshoots.
  </Card>

  <Card title="Social engagement" icon="heart">
    Give audiences interactive effects, filters, and transformations that drive participation and sharing.
  </Card>

  <Card title="Content monetization" icon="circle-dollar-sign">
    Embed branded products and sponsored placements directly into live video.
  </Card>

  <Card title="Live shopping" icon="bag-shopping">
    Sell any product, in any video. Give sellers the ability to place any item into live content instantly.
  </Card>

  <Card title="Furniture replacement" icon="couch">
    Swap furniture and home decor in live video, letting customers visualize products in their own space before buying.
  </Card>
</CardGroup>

## Updating the reference image

You can change the reference image at any time without reconnecting. Use the `set()` method to atomically replace the session state - include all fields you want to keep:

<CodeGroup>
  ```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)
  ```
</CodeGroup>

<Tip>
  `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.
</Tip>

### Reference image best practices

<CardGroup>
  <Card title="Use a clear, well-lit portrait" icon="sun">
    Consistent, even lighting works best regardless of edit type. For characters, use a front-facing photo. For garments and objects, avoid harsh shadows or reflections that obscure important details.
  </Card>

  <Card title="Match the framing" icon="crop">
    Match the reference framing to the source video. If the source shows a full-body standing person and you want to swap the character or change clothes, use a full-body reference shot rather than a head-and-shoulders crop.
  </Card>

  <Card title="Avoid occlusion" icon="eye">
    Make sure the key features of the reference are fully visible. Partially hidden characters, garments, or objects reduce what the model can extract and may affect output quality.
  </Card>

  <Card title="Resolution and format" icon="image">
    At least 512×512 pixels recommended. Supported formats: JPEG, PNG, and WebP.
  </Card>

  <Card title="For object replacement" icon="box">
    Use a clean product or object shot against a neutral background. The cleaner the separation between subject and background, the more precisely the model can apply it.
  </Card>

  <Card title="For virtual try-on" icon="shirt">
    A front-facing, evenly lit garment shot on a plain background gives the model the clearest signal. Include the full item from collar to hem where possible.
  </Card>
</CardGroup>

## Text-only editing

Lucy 2.5 works without a reference image too. Use text prompts to add, modify, or remove elements in your live video:

<CodeGroup>
  ```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.")
  ```
</CodeGroup>

See the [prompting guide](#prompting-guide) below for the best prompt structures for each edit type.

## Prompting guide

Strong prompts answer five questions: what should change, what should it become, where should it apply, how should it interact with the subject or environment, and what should stay the same.
Think of the prompt as short creative direction. You do not need technical language. You do need clear visual details.

<Info>
  For deeper guidance - layered edits, physical effects, restyle prompts, troubleshooting, and dos/don'ts - see the full [Prompting guide for Lucy 2.5](/models/realtime/lucy-2.5-prompting).
</Info>

Lucy 2.5 responds best when prompts follow the specific pattern for each edit type. The table below shows all eight supported operations with their recommended templates.

| Edit type | Prompt template |
| - | - |
| **Character swap** | `"Substitute the character in the video with <description>."` |
| **Add** | `"Add <description of object> to <where to add it>."` |
| **Replace** | `"Change <object to change> with <description of replacement>."` |
| **Remove** | `"Remove <object to remove> from the scene."` |
| **Change attribute** | `"Change <object> to <description of new attribute>."` |
| **Background** | `"Change the background to <description of new background>."` |
| **Style** | `"Change the style of the video to <style description>."` |
| **VFX** | `"Add <effect description> to <location in scene>."` |

<Note>
  Avoid negative instructions such as "don't add a hat" or "the person never changes clothes." Describe what you want to see instead.
</Note>

### Character swap

When using a reference image, describe the character's appearance in the prompt. The more detail you provide, the closer the output matches the reference.

**"Substitute the character in the video with <span>\<description of the character in the reference image></span>."**

Examples:

* *Substitute the character with <span>an older man, which has pale, wrinkled skin, light blue eyes, a powdered white wig with side curls, and wears a dark formal coat with a white ruffled neckpiece.</span>*
* *Substitute the character with <span>a young person wearing a short-sleeved pink top with white ribbon ties on the back, loose pink pants, and short brown hair tied in a side ponytail.</span>*
* *Substitute the character with <span>a furry creature, which has soft brown and orange fur, a light face with dark eye markings, a dark nose, and long claws.</span>*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Substitute the character with a furry creature, which has soft brown and orange fur, a light face with dark eye markings, a dark nose, and long claws.",
  image: referenceImage,
  enhance: true,
});
```

<Note>
  Describe what you see in the reference image - skin tone, hair, clothing, distinctive features. Generic prompts like "Transform into this character" still work but produce less precise results.
</Note>

### Adding objects

Add new elements to the scene by specifying what to add and where to place it.

**"Add <span>\<description of object></span> to <span>\<where to add it></span>."**

Examples:

* *Add <span>a red conical hat, covered in sequins, with a white fluffy trim and a matching pompom</span> to <span>the person's head</span>.*
* *Add <span>a coffee mug with a green logo</span> to <span>the person's right hand</span>.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Add a red conical hat, covered in sequins, with a white fluffy trim and a matching pompom to the person's head.",
  image: hatReference,
  enhance: true,
});
```

<Tip>
  Always specify placement ("to the person's head", "in the background", "on the table"). Without a location, the model places the object unpredictably.
</Tip>

### Replacing objects

Swap an existing element in the scene with something different.

**"Change <span>\<object to change></span> with <span>\<description of the replacement></span>."**

Examples:

* *Change <span>the person's sweater</span> with <span>a red knit sweater, which has a white-outlined, gold and white striped rectangular emblem on the chest</span>.*
* *Change <span>the phone in the person's hand</span> with <span>a sleek black smartphone with a triple-lens camera on the back</span>.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Change the person's sweater with a red knit sweater, which has a white-outlined, gold and white striped rectangular emblem on the chest.",
  image: sweaterReference,
  enhance: true,
});
```

### Removing objects

Remove an element from the scene. The model reconstructs the background behind it.

**"Remove <span>\<object to remove></span> from the scene."**

Examples:

* *Remove <span>the microphone stand</span> from the scene.*
* *Remove <span>the logo on the person's shirt</span> from the scene.*
* *Remove <span>the bottle on the table</span> from the scene.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Remove the microphone stand from the scene.",
});
```

### Changing attributes

Modify a property of an existing object - color, texture, material - without replacing the object itself.

**"Change <span>\<object></span> to <span>\<description of new attribute></span>."**

Examples:

* *Change <span>the wall's color</span> to <span>light blue, natural consistent paint finish</span>.*
* *Change <span>the shirt's texture</span> to <span>knitted, woven fabric</span>.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Change the wall's color to light blue, natural consistent paint finish.",
});
```

### Background replacement

Replace the background of the scene with a new environment. Works with or without a reference image.

**"Change the background to <span>\<description of the new background></span>."**

Examples:

* *Change the background to <span>a sandy beach with clear blue water and a bright sunny sky</span>.*
* *Change the background to <span>a cozy living room with warm lighting, bookshelves, and a fireplace</span>.*
* *Change the background to <span>a neon-lit city street at night with reflections on wet pavement</span>.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Change the background to a sandy beach with clear blue water and a bright sunny sky.",
  enhance: true,
});
```

### Style transformation

Apply a global visual style change to the entire scene - mood, aesthetic, or look and feel.

**"Change the style of the video to <span>\<style description></span>."**

Examples:

* *Change the style of the video to <span>a vintage 1970s film aesthetic with warm tones and slight grain</span>.*
* *Change the style of the video to <span>an anime illustration style with cel shading and bold outlines</span>.*
* *Change the style of the video to <span>a dark cyberpunk aesthetic with teal and magenta color grading</span>.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Change the style of the video to a vintage 1970s film aesthetic with warm tones and slight grain.",
  enhance: true,
});
```

### Visual effects

Add dynamic effects to characters or environments. VFX use the same "Add" structure but describe effects rather than physical objects.

**"Add <span>\<effect description></span> to <span>\<location in scene></span>."**

Examples:

* *Add <span>shooting fireballs</span> to <span>the person's hands</span>.*
* *Add <span>a large explosion with rising smoke</span> to <span>the background</span>.*
* *Add <span>a swirling vortex of electricity</span> <span>around the person</span>.*

```typescript theme={null}
await realtimeClient.set({
  prompt: "Add shooting fireballs to the person's hands.",
  enhance: true,
});
```

### Dos and don'ts

| Do | Don't |
| - | - |
| `"Add a silver crown floating above the person's head."` | `"Make it royal."` |
| `"Remove the coffee mug from the desk, leaving the wooden tabletop visible."` | `"Remove the mug."` |
| `"Change the background to a beach with waves crashing, sunlight on the water, and pale sand."` | `"Make it a beach."` |
| `"Use the black cropped jacket from the reference, including the glossy leather texture and silver zipper. Apply it to the person's jacket."` | `"Use the reference image."` |
| `"Replace the shirt with a red silk blouse. Keep the person's identity, face, and hair unchanged."` | `"Change the person into someone wearing a red blouse."` |
| `"Glowing sparks emit from the person's fingertips, trail with their hand motion, and reflect on their fingers."` | `"A magical thing happens around the hands."` |

## Connection lifecycle

Lucy 2.5 shares the same connection lifecycle as all realtime models. See the [JavaScript SDK](/sdks/javascript-realtime#connection-state), [Python SDK](/sdks/python-realtime), or [Android SDK](/sdks/android-realtime#connection-state) 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:

<CodeGroup>
  ```typescript JavaScript theme={null}
  import { createDecartClient, models, type DecartSDKError } from "@decartai/sdk";

  async function setupLucy25() {
    const model = models.realtime("lucy-2.5");

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

    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;
      },
    });

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

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

    realtimeClient.on("error", (error: DecartSDKError) => {
      console.error("Lucy 2.5 error:", error.code, error.message);
    });

    document.getElementById("character-input").addEventListener("change", async (e) => {
      const file = (e.target as HTMLInputElement).files[0];
      if (file) {
        await realtimeClient.set({
          prompt: "Substitute the character in the video with the person in the reference image.",
          image: file,
          enhance: true,
        });
      }
    });

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

    return realtimeClient;
  }

  setupLucy25();
  ```

  ```python Python theme={null}
  import asyncio
  from decart import DecartClient, models

  async def main():
      async with DecartClient(api_key="your-api-key-here") as client:
          model = models.realtime("lucy-2.5")

          realtime = await client.realtime.connect(
              stream=media_stream,
              model=model,
              on_remote_stream=lambda s: display(s),
          )

          @realtime.on("connection_change")
          def on_state(state):
              print(f"Connection: {state}")

          @realtime.on("generation_tick")
          def on_tick(seconds):
              print(f"Usage: {seconds}s")

          @realtime.on("error")
          def on_error(error):
              print(f"Lucy 2.5 error: {error.code} {error.message}")

          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 Android theme={null}
  import ai.decart.sdk.*
  import ai.decart.sdk.realtime.*
  import org.webrtc.*

  val model = RealtimeModels.LUCY_2_5
  val client = DecartClient(context, DecartClientConfig(apiKey = "your-api-key"))
  client.realtime.initialize(eglBase)

  val videoSource = client.realtime.createVideoSource(false)!!
  val videoTrack = client.realtime.createVideoTrack("camera", videoSource)!!
  val enumerator = Camera2Enumerator(context)
  val capturer = enumerator.createCapturer(
      enumerator.deviceNames.first { enumerator.isFrontFacing(it) }, null
  )
  capturer.initialize(
      SurfaceTextureHelper.create("CaptureThread", client.realtime.getEglBaseContext()),
      context, videoSource.capturerObserver
  )
  capturer.startCapture(model.width, model.height, model.fps)

  client.realtime.connect(
      localVideoTrack = videoTrack,
      options = ConnectOptions(
          model = model,
          onRemoteVideoTrack = { track -> remoteRenderer.addSink(track) }
      )
  )

  lifecycleScope.launch {
      client.realtime.connectionState.collect { state -> statusText.text = state.name }
  }
  lifecycleScope.launch {
      client.realtime.generationTicks.collect { tick -> usageText.text = "${tick.seconds}s" }
  }
  lifecycleScope.launch {
      client.realtime.errors.collect { error ->
          Log.e("Lucy25", "Error: ${error.code} ${error.message}") }
  }

  fun onCharacterSelected(imageBytes: ByteArray) {
      val base64 = Base64.encodeToString(imageBytes, Base64.NO_WRAP)
      client.realtime.setImage(
          imageBase64 = base64,
          prompt = "Substitute the character in the video with the person in the reference image.",
          enhance = true
      )
  }

  capturer.stopCapture()
  client.realtime.disconnect()
  client.release()
  eglBase.release()
  ```
</CodeGroup>

## Client-side authentication

For browser and mobile apps, use client tokens instead of your permanent API key.

<CodeGroup>
  ```typescript JavaScript theme={null}
  // Backend: generate a short-lived token (expires in 60 s by default)
  const token = await client.tokens.create();

  // Frontend: let the SDK fetch a fresh token right before every connect and reconnect
  const frontendClient = createDecartClient({
    apiKeyProvider: async () => {
      const res = await fetch("/api/realtime-token", { method: "POST" });
      const { apiKey } = await res.json();
      return apiKey;
    },
  });
  ```

  ```python Python theme={null}
  # Backend: generate a short-lived token
  token = await client.tokens.create()

  # Frontend: connect with the token
  frontend_client = DecartClient(api_key=token.api_key)
  ```

  ```kotlin Android theme={null}
  // Fetch a short-lived token from your backend
  val ephemeralKey = fetchTokenFromBackend()

  // Connect with the token
  val client = DecartClient(context, DecartClientConfig(apiKey = ephemeralKey))
  ```
</CodeGroup>

See the full pattern for [JavaScript](/sdks/javascript-realtime#client-side-authentication) or [Android](/sdks/android-realtime#client-side-authentication).

Client tokens expire 60 seconds after minting by default, so fetch them per dial with `apiKeyProvider` rather than on page load. See [Token lifetime](/getting-started/client-tokens#token-lifetime).

## Technical specifications

| Property | Value |
| - | - |
| **Model ID** | `lucy-2.5` |
| **Resolution** | 1280×720 |
| **Orientation** | Landscape (16:9) and Portrait (9:16) |
| **Transport** | WebRTC |
| **Character reference** | Yes (JPEG, PNG, WebP) |
| **Prompt enhancement** | Yes (default: enabled) |
| **Self-anchoring** | Yes (default: enabled) |
| **Fast mode** | Yes (`speed: "fast"`; 2x rate) |
| **Auto-reconnect** | Yes (exponential backoff, up to 5 retries) |

### Portrait mode (9:16)

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`:

```typescript theme={null}
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",
  },
});
```

### Generation stability

In long sessions, Lucy 2.5 can use its own output as an additional anchor - feeding recent generated frames back as the reference image. This self-anchoring mechanism keeps the output stable over time, preventing drifting. It is enabled by default, so most integrations need to do nothing.

Self-anchoring is a connect-time setting. To turn it off, pass `self_anchor=false` as a connection query parameter - the model then anchors only to the live input. Changing it requires a reconnect; it can't be toggled mid-session with `set()`.

```typescript theme={null}
const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (transformedStream) => {
    document.getElementById("output").srcObject = transformedStream;
  },
  queryParams: { self_anchor: "false" }, // disable self-anchoring
});
```

<Note>
  Self-anchoring works best when the scene stays consistent. If the stream changes significantly - a different person enters the frame, the camera cuts, or the scene shifts entirely - the model may still anchor to the last edited frame, which no longer matches the new input. In these cases do not use self-anchoring.
</Note>

### Fast mode

Fast mode (`speed: "fast"`) gives the session lower latency and higher throughput; output quality is unchanged. It is available for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5`, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode. See [Pricing](/getting-started/pricing#realtime-models).

Like self-anchoring, fast mode is a connect-time setting: pass `speed: "fast"` when connecting. Changing it requires a reconnect; it can't be toggled mid-session with `set()`. The SDK carries the option across its automatic reconnects.

<CodeGroup>
  ```typescript JavaScript theme={null}
  const realtimeClient = await client.realtime.connect(stream, {
    model,
    speed: "fast", // fast mode
    onRemoteStream: (transformedStream) => {
      document.getElementById("output").srcObject = transformedStream;
    },
  });
  ```

  ```text Raw WebSocket theme={null}
  wss://api.decart.ai/v1/stream?api_key=YOUR_API_KEY&model=lucy-2.5&speed=fast
  ```
</CodeGroup>

The option ships in [JavaScript](/sdks/javascript-realtime#fast-mode) v0.2.2, [Python](/sdks/python-realtime#fast-mode) v0.2.1, [Android](/sdks/android-realtime#fast-mode) 0.8.1 and [Swift](/sdks/swift-realtime#fast-mode) v0.7.1. On earlier `@decartai/sdk` versions, pass `queryParams: { speed: "fast" }` instead — it lands on the same query parameter.

<Note>
  Standard mode is the *absence* of the option — don't send `speed=standard` or an empty value. If you run a [signaling proxy](/integrations/signaling-proxy-ws), forward the end user's `speed` to the upstream URL, or the session lands on the standard tier.
</Note>

## Next steps

<CardGroup>
  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript-realtime">
    Full JavaScript SDK reference for realtime features
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python-realtime">
    Full Python SDK reference for realtime features
  </Card>

  <Card title="Android SDK" icon="android" href="/sdks/android-realtime">
    Full Android SDK reference for realtime features
  </Card>

  <Card title="All Models" icon="layer-group" href="/getting-started/models">
    Compare all Decart models side by side
  </Card>
</CardGroup>


# Prompting Guide
Source: https://docs.platform.decart.ai/models/realtime/lucy-2.5-prompting

How to write effective prompts for Lucy 2.5, with templates and examples for every edit type.

Lucy 2.5 edits video from a short written prompt and an optional reference image. Describe the visible change you want — what to add, replace, remove, restyle, transform, or preserve. Then say how the edit should interact with the subject and scene.

<Tip>
  Lucy 2.5 uses a structured prompt format. [Prompt enhancement](/models/realtime/streaming-best-practices#use-prompt-enhancement) (`enhance: true`) rewrites your instruction to fit the input video and any reference image. It is on by default; keep it on.
</Tip>

<Note>
  **Prompt length.** Prompts have a maximum length. As a rough estimate, about 750 characters of English (around 120 words) fit. The exact limit depends on the wording, and other languages may allow fewer characters. If your prompt is too long, you get an error that tells you how many characters of it fit. This applies whether or not prompt enhancement is on.
</Note>

## Basics

Three inputs shape the result:

* **Input video:** What Lucy can see and track.
* **Reference image:** The visual material for an edit. It may not show every angle the video needs.
* **Prompt:** The change you want. Describe the edit, not every visible detail — enhancement fills in the rest.

### Choosing an input video

Lucy can only edit what it can clearly see and track. A good input video:

* Keeps the subject fully visible and well lit.
* Holds steady framing, and avoids fast motion, motion blur, and heavy occlusion.
* Uses a clean, uncluttered background, especially for background edits.

<Warning>
  Lucy edits your live video in real time. Make sure the thing you want to edit is visible in the current frame — or name it explicitly in your prompt.
</Warning>

### Core prompting principles

A strong prompt answers four questions, in four sentences or fewer:

* **What should change?** Describe the intended result: a new appearance, object, character, or scene.
* **Where is the change applied?** Anchor the edit to a visible location, such as a body part, garment detail, object surface, or background.
* **How does it interact and move?** Say how the edit attaches to the subject and holds up as the subject moves. Name the physical behavior — attaches to, wraps around, trails with motion, reflects on, casts light on, or is occluded by — so the result tracks the subject instead of looking pasted on.
* **What stays the same?** Name the details the edit should not affect, such as physical features, garment details, or objects.

Together, those answers form one prompt:

<div>
  ```text Example: theme={null}
  Add blue smoke and white smoke to the person's shoulders. It follows their movement, billows outward, and passes behind their arms and body. Keep their face, clothing, and background unchanged.
  ```
</div>

This names the change (blue and white smoke), where it goes (on the shoulders), how it behaves (follows the person's movement, billows outward, and passes behind the arms and body), and what to preserve (face, clothing, and background).

Make one focused edit per prompt. Combining several unrelated changes into one prompt makes each one less reliable — apply them one at a time.

Cut filler adjectives like realistic, seamless, natural, cinematic, or high quality. Concrete visual details do more; use such words only when the look itself is the edit.

Identify targets by visible details, not their position in the frame:

<div>
  | ✅ Visible detail | ❌ Frame position |
  | - | - |
  | `"the red hat on the woman's head"` | `"the hat on the right"` |
</div>

If several similar objects appear, tell them apart by color, material, pattern, text, logo, or shape.

Name each target with a concrete noun — the jacket, the left hand, the background — not a pronoun like it or this.

### Using reference images

A reference image supplies the visual material for an edit — a garment, object, character, or art style. The prompt tells Lucy which part to use and how to apply it.

Use a reference image when you need consistent results across different videos.

Good reference images:

* Show the intended item or style clearly and completely, with the full subject visible and centered.
* Keep important details visible, such as shape, material, color, pattern, and fit.
* Avoid cluttered backgrounds, occlusion, and extra people or objects.
* Use a sharp, lightly compressed image, about 1280px on the longest side.
* Pad unusual aspect ratios to the output orientation — 16:9 landscape or 9:16 portrait — instead of cropping or upscaling.

<Warning>
  Do not rely on an empty prompt. Even with a strong reference, specify the intended edit.
</Warning>

<div>
  | ✅ Specific | ❌ Too general |
  | - | - |
  | `"Put the black leather jacket from the reference image on the person in the video."` | `"Put this on the person."` |
</div>

When using a reference image, your prompt should:

* Name the item, character, or style to use.
* Call out the visual details that matter, such as color, material, texture, shape, pattern, logo placement, or fit.
* State where or how it should appear in the video.
* Ignore reference details that are not part of the edit, such as the reference subject's pose, lighting, or background.

## Prompt templates and examples

Each example starts on the unedited original clip, which shows the template for that edit type. Select a prompt beneath the video to see the edited result. Where a reference image was used, it appears next to the prompt.

### Character transformation

<div>
  <Tabs>
    <Tab title="Original person">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Space explorer">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Cartoon chef">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Día de Muertos">
      <div>
        <video />
      </div>
    </Tab>
  </Tabs>
</div>

<div>
  <Tabs>
    <Tab title="Original person">
      ```text Template: theme={null}
      Replace the character in the video with <description of character>.
      ```
    </Tab>

    <Tab title="Space explorer">
      ```text Prompt: theme={null}
      Replace the character in the video with a silver-armored space explorer with a reflective blue visor, white gloves, glowing shoulder lights, and a short navy cape.
      ```
    </Tab>

    <Tab title="Cartoon chef">
      ```text Prompt: theme={null}
      Replace the character in the video with a cheerful cartoon chef wearing a tall white hat, red neck scarf, double-breasted jacket, and round glasses.
      ```
    </Tab>

    <Tab title="Día de Muertos">
      <div>
        <div>
          ```text Prompt: theme={null}
          Replace the character in the video with the Día de Muertos festival dancer from the reference image. She has tangerine and ivory face paint, an orange flower crown, a black dress with blue and orange floral embroidery, cream lace edging, a tiered skirt, and a fringed shawl.
          ```
        </div>

        <div>
          <Frame>
            <img alt="Día de Muertos festival dancer reference image" />
          </Frame>
        </div>
      </div>
    </Tab>
  </Tabs>
</div>

**Tips**

* Capture the character's defining traits, not just how it looks — its materials, textures, and how they move, like rigid armor, flowing fabric, or glowing energy.
* Include distinctive details the reference may not show, such as wings, a tail, a shield, a backpack, or a cape.

**Troubleshooting**

* **If the person's face or identity changes:** This is the expected behavior – use Virtual Try-on (VTON) for costume changes that preserve identity.

<div>
  | ✅ Do | ❌ Don't |
  | - | - |
  | `"Replace the shirt with a red silk blouse. Keep the person's identity, face, and hair unchanged."` | `"Change the person into someone wearing a red blouse."` — changes the person, not the shirt |
</div>

### Add objects

<div>
  <Tabs>
    <Tab title="Original subject">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Macaw parrot">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Blue helmet">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Cape">
      <div>
        <video />
      </div>
    </Tab>
  </Tabs>
</div>

<div>
  <Tabs>
    <Tab title="Original subject">
      ```text Template: theme={null}
      Add <description of object> to <where it should appear>.
      ```
    </Tab>

    <Tab title="Macaw parrot">
      ```text Prompt: theme={null}
      Add two blue, yellow, white, and green macaw parrots to each of the person's shoulders.
      ```
    </Tab>

    <Tab title="Blue helmet">
      <div>
        <div>
          ```text Prompt: theme={null}
          Add the sparkly blue helmet to the person's head. The helmet has wings, chrome flames, and a transparent yellow glass visor that shows the person's face inside.
          ```
        </div>

        <div>
          <Frame>
            <img alt="Blue helmet reference image" />
          </Frame>
        </div>
      </div>
    </Tab>

    <Tab title="Cape">
      ```text Prompt: theme={null}
      Add a long sparkly blue cape attached to the person's shoulders. The cape has a stand collar, an opening for arms, silver trim, and a yellow inner fabric.
      ```
    </Tab>
  </Tabs>
</div>

**Tips**

* Describe the new object in detail — its parts, colors, and material properties.
* When adding more than one, say how many and where each one goes.

<div>
  | ✅ Do | ❌ Don't |
  | - | - |
  | `"Add a silver crown floating above the person's head."` | `"Make it royal."` — too vague |
  | `"Glowing blue sparks emit from the person's fingertips, trail with their hand motion, and reflect on the person's fingers."` | `"A magical thing happens around the hands."` — too vague |
</div>

### Replace objects or features

<div>
  <Tabs>
    <Tab title="Original objects">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Heart glasses">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Tropical plants">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Fountain">
      <div>
        <video />
      </div>
    </Tab>
  </Tabs>
</div>

<div>
  <Tabs>
    <Tab title="Original objects">
      ```text Template: theme={null}
      Replace <description of object or detail> with <description of change>.
      ```
    </Tab>

    <Tab title="Heart glasses">
      <div>
        <div>
          ```text Prompt: theme={null}
          Replace the person's sunglasses with the heart-shaped sunglasses, including the glossy hot-pink frame and mirrored rose-tint lenses.
          ```
        </div>

        <div>
          <Frame>
            <img alt="Heart-shaped sunglasses reference image" />
          </Frame>
        </div>
      </div>
    </Tab>

    <Tab title="Tropical plants">
      ```text Prompt: theme={null}
      Replace the plants in the background with tropical foliage.
      ```
    </Tab>

    <Tab title="Fountain">
      ```text Prompt: theme={null}
      Replace the fence with a waterfall-style fountain along the edge of the deck.
      ```
    </Tab>
  </Tabs>
</div>

**Tips**

* To change many similar elements, name the category — like the plants in the background — instead of listing each one.
* Describe what you want to see, not how the edit should be done.

**Troubleshooting**

* **If the original still shows through the replacement:** Describe the new object in full, including the parts that should change.

<div>
  | ✅ Do | ❌ Don't |
  | - | - |
  | `"Replace the person's sunglasses with heart-shaped sunglasses, including the glossy hot-pink frame and mirrored rose-tint lenses."` | `"Change the glasses."` — no visible details |
</div>

### Change attribute

<div>
  <Tabs>
    <Tab title="Original items">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Headphones color">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Sweater and bag">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Camo crossbody bag">
      <div>
        <video />
      </div>
    </Tab>
  </Tabs>
</div>

<div>
  <Tabs>
    <Tab title="Original items">
      ```text Template: theme={null}
      Change <object or feature> to <new color, material, texture, or style>.
      ```
    </Tab>

    <Tab title="Headphones color">
      ```text Prompt: theme={null}
      Change the material of the person's headphones to glossy orange plastic.
      ```
    </Tab>

    <Tab title="Sweater and bag">
      ```text Prompt: theme={null}
      Make the person's sweater medium blue and his bag white leather.
      ```
    </Tab>

    <Tab title="Camo crossbody bag">
      <div>
        <div>
          ```text Prompt: theme={null}
          Change the material of the person's black bag and its strap to the camouflage print from the reference image.
          ```
        </div>

        <div>
          <Frame>
            <img alt="Camouflage print reference image" />
          </Frame>
        </div>
      </div>
    </Tab>
  </Tabs>
</div>

**Tips**

* Describe material properties — gloss, transparency, reflectivity, weave, finish, or graphic placement — not just the base color.
* Change one or a few related attributes at once, and keep each one specific.
* Try a reference image to apply a specific pattern or texture.

<div>
  | ✅ Do | ❌ Don't |
  | - | - |
  | `"Use the black cropped jacket from the reference, including the glossy leather texture and silver zipper. Apply it to the person's jacket."` | `"Use the reference image."` — no target or details |
</div>

### Remove objects

<div>
  <Tabs>
    <Tab title="Original scene">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Foreground elements">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Background elements">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Sun umbrella">
      <div>
        <video />
      </div>
    </Tab>
  </Tabs>
</div>

<div>
  <Tabs>
    <Tab title="Original scene">
      ```text Template: theme={null}
      Remove <object> from <where it appears>.
      ```
    </Tab>

    <Tab title="Foreground elements">
      ```text Prompt: theme={null}
      Remove the woman sitting on the bench and the book she's holding so the result shows the people moving in the background.
      ```
    </Tab>

    <Tab title="Background elements">
      ```text Prompt: theme={null}
      Remove the cyclist behind the woman so the result shows only the path, bushes, trees, and grass in the background.
      ```
    </Tab>

    <Tab title="Sun umbrella">
      ```text Prompt: theme={null}
      Remove the large yellow sun umbrella, including its pole and cast shadow, so the result shows the woman in full sunlight.
      ```
    </Tab>
  </Tabs>
</div>

**Tips**

* Describe what should be visible after removal — the surface or background behind the object, including its texture and lighting.
* When removal changes what remains, such as the lighting or shadows on nearby objects, describe the new state.

**Troubleshooting**

* **If a shadow or outline of the removed object remains:** Name it in the prompt so it's removed along with the object.

<div>
  | ✅ Do | ❌ Don't |
  | - | - |
  | `"Remove the coffee mug from the desk, leaving the wooden tabletop visible."` | `"Remove the mug."` — no target details |
</div>

### Change background

<div>
  <Tabs>
    <Tab title="Original background">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Festive street">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Fall hike">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Art deco concourse">
      <div>
        <video />
      </div>
    </Tab>
  </Tabs>
</div>

<div>
  <Tabs>
    <Tab title="Original background">
      ```text Template: theme={null}
      Change the background to <description of scene>.
      ```
    </Tab>

    <Tab title="Festive street">
      <div>
        <div>
          ```text Prompt: theme={null}
          Change the background to a Mediterranean street scene with streamers and flags that blow in the breeze.
          ```
        </div>

        <div>
          <Frame>
            <img alt="Mediterranean street scene reference image" />
          </Frame>
        </div>
      </div>
    </Tab>

    <Tab title="Fall hike">
      <div>
        <div>
          ```text Prompt: theme={null}
          Change the background to a nature preserve in fall with red and yellow trees and river rapids flowing beside the dirt trail.
          ```
        </div>

        <div>
          <Frame>
            <img alt="Nature preserve in fall reference image" />
          </Frame>
        </div>
      </div>
    </Tab>

    <Tab title="Art deco concourse">
      <div>
        <div>
          ```text Prompt: theme={null}
          Change the background to an art deco concourse with softly glowing overhead lights.
          ```
        </div>

        <div>
          <Frame>
            <img alt="Art deco concourse reference image" />
          </Frame>
        </div>
      </div>
    </Tab>
  </Tabs>
</div>

**Tips**

* Say how background elements should move — flags blowing, water flowing — so the scene isn't static.
* To help the subject and new background read as one scene, try matching the light — direction, color, and time of day.
* Keep the prompt focused on the background change — extra instructions about the subject may steer the model toward changing the person instead.
* The background may be fit to the input's framing and camera angle rather than copied 1:1 from the reference — treat the image as a guide to the look, not an exact layout.

<div>
  | ✅ Do | ❌ Don't |
  | - | - |
  | `"Change the background to a beach with waves crashing, sunlight on the water, and pale sand."` | `"Make it a beach."` — too vague |
</div>

### Restyle the entire video

<div>
  <Tabs>
    <Tab title="Original style">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Watercolor">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Japanese woodblock print">
      <div>
        <video />
      </div>
    </Tab>

    <Tab title="Crocheted world">
      <div>
        <video />
      </div>
    </Tab>
  </Tabs>
</div>

<div>
  <Tabs>
    <Tab title="Original style">
      ```text Template: theme={null}
      Transform the entire scene into <style keyword or description>.
      ```
    </Tab>

    <Tab title="Watercolor">
      ```text Prompt: theme={null}
      Transform the entire scene into a watercolor painting.
      ```
    </Tab>

    <Tab title="Japanese woodblock print">
      ```text Prompt: theme={null}
      Transform the entire scene into a Japanese woodblock print with flat layered color, carved linework, visible grain, and simplified shadows.
      ```
    </Tab>

    <Tab title="Crocheted world">
      ```text Prompt: theme={null}
      Transform the entire scene into a handcrafted crocheted world with chunky yarn surfaces, stitched details, soft fibers, and rounded three-dimensional forms.
      ```
    </Tab>
  </Tabs>
</div>

**Tips**

* Name a specific style — a 2D or 3D technique like oil painting or origami, or a material like clay or yarn applied across the whole scene.
* Describe one style through concrete traits, such as palette, texture, brushstroke, linework, or material.

**Troubleshooting**

* **If the restyle flickers between styles:** Use one well-defined style — avoid vague labels like 'artistic' or 'stylized,' and don't mix several styles in one prompt.

<div>
  | ✅ Do | ❌ Don't |
  | - | - |
  | `"Transform the entire scene into a watercolor painting style. The final video should show translucent color washes, visible paper texture, and muted pastel colors."` | `"Make this 3D style."` — no concrete style traits |
</div>


# Oasis 3 Preview Realtime
Source: https://docs.platform.decart.ai/models/realtime/oasis-3

A real-time, promptable world model you can drive: set a scene with text, stream driving actions, and receive generated camera frames over a single gRPC session.

Oasis 3 Preview is a real-time, promptable **world model**. You set a scene with a text prompt, send it driving actions (throttle and steering), and it generates the next camera frames of that world — actions in, frames out, no model to host. Because it responds to your actions in real time, Oasis 3 Preview is also a learned driving simulator you can run reinforcement learning in.

The Python SDK, [`decart-oasis`](https://pypi.org/project/decart-oasis/), is the thin client that talks to it: it handles the gRPC session and VP9/JPEG frame decoding, and nothing heavier.

<Info>
  Want to try it first? A playable, realtime web version of Oasis 3 Preview runs in your browser at [oasis3-preview.decart.ai](https://oasis3-preview.decart.ai) — drive the model live, no setup. To build with it, use the Python gRPC SDK below: install `decart-oasis` and set `DECART_API_KEY`.
</Info>

## Quick start

<Steps>
  <Step title="Install">
    ```bash theme={null}
    pip install decart-oasis
    ```

    Requires Python 3.10+.
  </Step>

  <Step title="Set your API key">
    ```bash theme={null}
    export DECART_API_KEY="sk-..."
    ```
  </Step>

  <Step title="Drive the world model">
    ```python theme={null}
    from decart_oasis import A2VClient

    # Reads DECART_API_KEY from the environment; uses the hosted Oasis endpoint by default.
    with A2VClient() as client:
        client.prompt("driving in an urban area")          # set the scene
        result = client.infer(                             # send 4 actions, get 4 frames back
            [[0.2, 0.0], [0.2, 0.0], [0.2, 0.1], [0.2, 0.1]]
        )

    front = result.frames["front"]   # list of 4 RGB frames (H×W×3 uint8 numpy arrays)
    ```
  </Step>
</Steps>

<Info>
  `A2VClient` is a context manager. Entering it calls `initialize()` (opening the session); exiting it calls `close()` (releasing the session and the gRPC channel) even if an error is raised.
</Info>

## How a session works

Every interaction is one stateful session with four phases. The context-manager form above runs the lifecycle for you; you can also drive it explicitly:

<Steps>
  <Step title="Initialize">
    Opens a session, authenticates, and negotiates the output format. Returns the streams the server advertises (for Oasis 3 Preview: `left_forward`, `front`, `right_forward`).

    ```python theme={null}
    client = A2VClient()
    streams = client.initialize()
    ```
  </Step>

  <Step title="Prompt">
    Sets the scene the model generates. A new prompt resets the world-model context and the rollout, so the action sequence restarts. Call it before your first `infer`, and again any time you want a fresh scene.

    ```python theme={null}
    client.prompt("driving on a highway at sunset")
    ```
  </Step>

  <Step title="Infer">
    Sends exactly **four** `[throttle, steering]` actions and returns **four** generated frames for each stream. Call it in a loop to keep driving.

    ```python theme={null}
    for _ in range(12):
        result = client.infer([[0.2, 0.0], [0.2, 0.0], [0.2, 0.05], [0.2, 0.05]])
    ```
  </Step>

  <Step title="Finish">
    Releases the session and the channel.

    ```python theme={null}
    client.close()
    ```
  </Step>
</Steps>

## Authentication

Connecting requires a Decart API key. Pass it explicitly or set the `DECART_API_KEY` environment variable — the SDK reads the environment when no key is given.

<CodeGroup>
  ```python Environment variable theme={null}
  import os
  os.environ["DECART_API_KEY"] = "sk-..."

  from decart_oasis import A2VClient
  client = A2VClient()                      # picks up DECART_API_KEY
  ```

  ```python Explicit argument theme={null}
  from decart_oasis import A2VClient
  client = A2VClient(api_key="sk-...")      # overrides the environment
  ```
</CodeGroup>

<Warning>
  A non-empty key is required. If it is missing or rejected, `initialize()` raises — locally as a `DecartRoboticsError`, or from the server as an `A2VError` with code `ERROR_CODE_INVALID_API_KEY`.
</Warning>

## Actions and frames

Each `infer` call is one client-visible tick: a **chunk of four actions** in, **four frames per stream** out.

| Field | Shape / type | Range | Meaning |
| - | - | - | - |
| `throttle` | `float` | `[-1, 1]` | Forward (`+`) / brake or reverse (`−`) |
| `steering` | `float` | `[-1, 1]` | Steer left (`−`) / right (`+`) |
| action chunk | `(4, 2)` array-like | — | Four `[throttle, steering]` pairs, ordered in time |

```python theme={null}
import numpy as np

# A gentle forward arc. Any nested sequence or numpy array of shape (4, 2) works.
actions = np.array(
    [[0.15, -0.10], [0.20, -0.04], [0.22, 0.04], [0.18, 0.10]],
    dtype=np.float32,
)
result = client.infer(actions)
```

The call returns an `A2VResult`:

| Attribute | Type | Description |
| - | - | - |
| `sequence_num` | `int` | Server tick index, starting at 0 and resetting on each `prompt`. |
| `frames` | `dict[str, list[np.ndarray]]` | Per stream, the 4 decoded RGB frames (`H×W×3`, `uint8`). |
| `streams` | `tuple[StreamInfo, ...]` | The advertised streams and their dimensions. |

```python theme={null}
result = client.infer(actions)
result.sequence_num            # 0, then 1, 2, ...
result.frames["front"][0]      # first front-camera frame, shape (512, 768, 3)
set(result.frames)             # {"left_forward", "front", "right_forward"}
```

<Note>
  Actions must be finite and within `[-1, 1]`, and the chunk must be shape `(4, 2)` — otherwise `infer` raises `ValueError` before any request is sent.
</Note>

## Streaming frames live

`A2VClient` accepts a `frame_consumer`: any object with `submit(frames)` and `new_clip()` methods (the `FrameConsumer` protocol). The client hands every decoded chunk to it as inference runs, so you can render or record without re-fetching. A ready-made notebook preview ships in `oasis-demo` (`oasis_demo.live_preview.LiveCameraPreview`).

```python theme={null}
class Recorder:
    def __init__(self): self.clips = [[]]
    def new_clip(self): self.clips.append([])               # called on each prompt()
    def submit(self, frames): self.clips[-1].append(frames)  # called on each infer()

client = A2VClient(frame_consumer=Recorder())
```

## Client configuration

```python theme={null}
A2VClient(
    endpoint=None,            # defaults to the hosted Oasis endpoint
    *,
    api_key=None,             # defaults to $DECART_API_KEY
    timeout=120.0,
    tls=None,                 # auto-detected from the endpoint scheme
    required_streams=("left_forward", "front", "right_forward"),
    frame_consumer=None,
)
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `endpoint` | `str` | `https://oasis-grpc.decart.ai` | gRPC endpoint. `https://` ⇒ TLS, `http://` ⇒ insecure. |
| `api_key` | `str` | `$DECART_API_KEY` | Decart API key. Required. |
| `timeout` | `float \| None` | `120.0` | Per-RPC timeout, in seconds. |
| `tls` | `bool \| None` | `None` (auto) | Force TLS on/off. Bare `host:port` endpoints default to TLS on. |
| `required_streams` | `Sequence[str]` | left/front/right | Streams the server must advertise, else `initialize()` raises. |
| `frame_consumer` | `FrameConsumer` | `None` | Receives each decoded frame chunk during `infer`. |

### Endpoint

The SDK uses the hosted endpoint by default. Override it per-client, or via the `DECART_ROBOTICS_ENDPOINT` environment variable with `from_env()`:

<CodeGroup>
  ```python Default (hosted) theme={null}
  client = A2VClient()                       # https://oasis-grpc.decart.ai
  ```

  ```python From environment theme={null}
  # export DECART_ROBOTICS_ENDPOINT="https://your-oasis-grpc-endpoint"
  client = A2VClient.from_env()
  ```

  ```python Local / insecure theme={null}
  client = A2VClient("localhost:50051", tls=False)
  ```
</CodeGroup>

<Note>
  After `Initialize`, the load balancer pins the session by returning an `x-session-target` header. The SDK captures it and replays it on every later `Prompt`, `Infer`, and `Finish` — no action needed.
</Note>

## API reference

| Method / property | Returns | Description |
| - | - | - |
| `initialize()` | `tuple[StreamInfo, ...]` | Open the session, authenticate, negotiate format, return streams. |
| `prompt(text: str)` | `None` | Set the scene; resets the rollout (sequence restarts at 0). |
| `infer(actions)` | `A2VResult` | Send 4 `[throttle, steering]` actions; return 4 frames per stream. |
| `close()` | `None` | Finish the session and release the gRPC channel. |
| `from_env(...)` *(classmethod)* | `A2VClient` | Build a client, reading the endpoint from the environment. |
| `session_id` | `str \| None` | Active session id, or `None` before `initialize`. |
| `streams` | `tuple[StreamInfo, ...]` | The advertised streams. |

## Complete example

```python theme={null}
import numpy as np
from decart_oasis import A2VClient
from decart_oasis.exceptions import A2VError, DecartRoboticsError

actions = np.array(
    [[0.2, 0.0], [0.2, 0.0], [0.2, 0.05], [0.2, 0.05]],
    dtype=np.float32,
)

try:
    with A2VClient() as client:                 # initialize() on enter, close() on exit
        print("streams:", [s.name for s in client.streams])
        client.prompt("driving in an urban area")
        for _ in range(30):
            result = client.infer(actions)
        last_front = result.frames["front"][-1]  # (512, 768, 3) uint8
        print("final frame:", last_front.shape, "tick:", result.sequence_num)
except A2VError as exc:
    print(f"service error {exc.code}: {exc.message}")
except DecartRoboticsError as exc:
    print(f"client error: {exc}")
```

## Error handling

All SDK errors derive from `DecartRoboticsError`. Errors returned by the service are raised as `A2VError`, which carries the `code`, `message`, and `details` from the server.

```python theme={null}
from decart_oasis.exceptions import A2VError, DecartRoboticsError
```

| Code | Meaning |
| - | - |
| `ERROR_CODE_INVALID_SESSION` | Session id not found or expired. |
| `ERROR_CODE_ALREADY_FINISHED` | The session was already finished. |
| `ERROR_CODE_INVALID_REQUEST` | Malformed request (e.g. bad action chunk). |
| `ERROR_CODE_INVALID_FORMAT` | Requested output format not supported. |
| `ERROR_CODE_PROMPT_SET` | Prompt-related error. |
| `ERROR_CODE_UNSUPPORTED_SDK_VERSION` | The client SDK version is not accepted. |
| `ERROR_CODE_INVALID_API_KEY` | API key missing or invalid. |

## Reinforcement learning

Because Oasis 3 Preview turns actions into the next frames in real time, it is a learned driving simulator you can train a policy in — set a scene, let an agent drive, and reward the behavior you want. The easiest way to see this end-to-end is our Colab notebook, which trains a small PPO policy to drive inside Oasis 3 Preview, with a live preview.

<Card title="Train a driving policy with RL in Oasis 3 Preview" icon="rocket" href="https://colab.research.google.com/github/DecartAI/decart-robotics/blob/main/notebook/train_oasis3_ppo_colab.ipynb">
  Open the end-to-end Colab notebook
</Card>

Oasis 3 Preview (the simulator) and the depth model (the reward) are frozen and hosted — **only the PPO policy is trained**. The notebook wraps Oasis as a [Gymnasium](https://gymnasium.farama.org/) environment and runs the full loop with [Stable-Baselines3](https://stable-baselines3.readthedocs.io/):

<Steps>
  <Step title="Drive the simulator by hand">
    Send a fixed chunk of `[throttle, steering]` actions and stream the returned frames into a live `left | front | right` video with a collision-risk bar — a quick check that the API works.
  </Step>

  <Step title="Score each step with a reward">
    A depth model on the `front` frame measures how much of the scene is dangerously close. The reward rewards forward progress, penalizes net turning, and terminates the episode on a likely collision.
  </Step>

  <Step title="(Optional) Warm-start with behavior cloning">
    Clone the policy on recordings of people driving Oasis so it starts from human-like driving instead of random exploration.
  </Step>

  <Step title="Train the policy with RL">
    PPO drives the agent in Oasis, scores each step with the reward, and improves the policy. Every step is a live Oasis call, so the loop is small by default — enough to see it work.
  </Step>

  <Step title="Watch it drive">
    Roll out one clean, deterministic episode of the policy you trained and watch it in the live preview.
  </Step>
</Steps>

<Tip>
  To run it: open the notebook in Colab, choose **Runtime → Change runtime type → GPU**, add your `DECART_API_KEY` in the Colab secrets panel (🔑), and **Run all**.
</Tip>

## Technical specifications

| | |
| - | - |
| **Model** | `oasis-3-preview` |
| **Transport** | gRPC (HTTP/2), TLS by default |
| **Default endpoint** | `https://oasis-grpc.decart.ai` |
| **Output frames** | VP9, decoded to RGB `H×W×3` `uint8` (via PyAV) |
| **Streams** | `left_forward`, `front`, `right_forward` — 768×512 RGB |
| **Action chunk** | 4 × `[throttle, steering]`, each in `[-1, 1]` |
| **Frames per call** | 4 per stream |
| **Authentication** | API key (`DECART_API_KEY`) |
| **Python** | ≥ 3.10 |

## Next steps

<CardGroup>
  <Card title="Try Oasis 3 Preview live" icon="play" href="https://oasis3-preview.decart.ai">
    Drive the model in your browser — a playable realtime web version, no setup.
  </Card>

  <Card title="RL training notebook" icon="rocket" href="https://colab.research.google.com/github/DecartAI/decart-robotics/blob/main/notebook/train_oasis3_ppo_colab.ipynb">
    Train a PPO driving agent in Oasis 3 Preview end-to-end, with a live preview.
  </Card>

  <Card title="decart-robotics on GitHub" icon="github" href="https://github.com/DecartAI/decart-robotics">
    The SDK source, the RL examples, and the training notebook.
  </Card>

  <Card title="decart-oasis on PyPI" icon="python" href="https://pypi.org/project/decart-oasis/">
    Install the lightweight Python SDK.
  </Card>

  <Card title="All Models" icon="layer-group" href="/getting-started/models">
    Compare all Decart models side by side.
  </Card>
</CardGroup>


# Overview
Source: https://docs.platform.decart.ai/models/realtime/overview



Transform and edit live video streams in realtime with AI. Our realtime models enable creative style transformations and precise video editing with minimal latency.

Choose between style transformation (Lucy Restyle Live) for artistic effects or video editing and character transformation (Lucy 2.1) for adding, changing, or removing elements and becoming any character.

## Available Models

We offer specialized realtime models, each optimized for different use cases:

| Model | Use Case | Example Prompts | Best For |
| - | - | - | - |
| **Lucy Restyle Live** | Style transformation | "Anime style", "Cyberpunk city", "Studio Ghibli animation" | Creative effects, artistic filters, visual themes |
| **Lucy 2.1** | Video editing + character reference | "Transform into this character", "Add a dog", "Change hair to blonde" | Character transformation, object manipulation, scene editing |
| **Oasis 3 Preview** | World model / driving simulator | "driving in an urban area", "driving on a highway at sunset" | World-model simulation, RL training, robotics |

### Lucy Restyle Live - Video Restyling

Transform the overall visual style and aesthetic of your video stream. Perfect for creative applications, social media filters, and artistic effects.

### Lucy 2.1 - Video Editing & Character Reference

Make specific edits to videos by adding, modifying, or removing objects and elements. Lucy 2.1 (`lucy-2.1`) also supports character reference images — upload any face and see yourself transformed into that character in realtime.

### Oasis 3 Preview - Realtime World Model

Set a scene with a text prompt and drive it with actions (throttle + steering); Oasis 3 Preview (`oasis-3-preview`) generates the next camera frames in realtime — a learned driving simulator you can run reinforcement learning in. Unlike the Lucy models, it uses the dedicated Python gRPC SDK [`decart-oasis`](https://pypi.org/project/decart-oasis/). [Learn more →](/models/realtime/oasis-3)

## Quick Start

### Installation

```bash theme={null}
npm install @decartai/sdk
```

### Basic Usage

<Tabs>
  <Tab title="Video Editing (Lucy 2.1)">
    ```tsx theme={null}
    import { createDecartClient, models } from "@decartai/sdk";

    // Use Lucy 2.1 for video editing — supports text prompts and character reference
    const model = models.realtime("lucy-latest");

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

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

    const realtimeClient = await client.realtime.connect(stream, {
      model,
      onRemoteStream: (editedStream) => {
        videoElement.srcObject = editedStream;
      },
    });

    // Text-only editing
    await realtimeClient.set({ prompt: "Add a small dog in the background", enhance: true });

    // Character transformation with a reference image
    const characterPhoto = document.querySelector("input[type=file]").files[0];
    await realtimeClient.set({
      prompt: "Transform into this character",
      image: characterPhoto,
      enhance: true,
    });
    ```
  </Tab>

  <Tab title="Video Restyling (Lucy Restyle Live)">
    ```tsx theme={null}
    import { createDecartClient, models } from "@decartai/sdk";

    // Use Lucy Restyle Live for style transformation
    const model = models.realtime("lucy-restyle-2");

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

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

    const realtimeClient = await client.realtime.connect(stream, {
      model,
      onRemoteStream: (transformedStream) => {
        videoElement.srcObject = transformedStream;
      },
      initialState: {
        prompt: { text: "Anime style", enhance: true }
      }
    });

    // Change styles dynamically
    realtimeClient.setPrompt("Cyberpunk city");
    realtimeClient.setPrompt("Studio Ghibli animation");
    ```
  </Tab>
</Tabs>

## Use Cases & Examples

### Video Restyling with Lucy Restyle Live

Perfect for creative applications and visual effects:

* **Social Media Filters**: "Anime style", "Vintage film", "Oil painting"
* **Content Creation**: "Studio Ghibli animation", "Cyberpunk aesthetic", "Watercolor art"
* **Live Streaming**: "Cartoon style", "Neon synthwave", "Impressionist painting"
* **Virtual Events**: "Fantasy world", "Futuristic setting", "Medieval theme"

### Video Editing & Character Transform with Lucy 2.1

Ideal for content modification, character-driven experiences, and interactive apps:

* **Character Transformation**: Upload a reference image and become that character — your movements and expressions map onto the reference identity
* **Object Addition**: "Add a dog running around", "Add birds flying overhead", "Add flowers in the foreground"
* **Appearance Changes**: "Change hair to blonde", "Add sunglasses", "Change shirt color to red"
* **Object Removal**: "Remove the car from the scene", "Remove the tree", "Remove background objects"
* **Scene Modifications**: "Replace the background with a beach", "Add snow falling", "Change day to night"

## Getting Started

Choose your model based on your use case:

<CardGroup>
  <Card title="Video Restyling" icon="palette" href="/models/realtime/video-restyling">
    Transform video styles with the Lucy Restyle Live model. Perfect for creative effects and artistic transformations.
  </Card>

  <Card title="Lucy 2.1" icon="sparkles" href="/models/realtime/lucy-2.1">
    Character transformation and video editing with Lucy 2.1.
  </Card>

  <Card title="Video Editing (Legacy)" icon="pen-to-square" href="/models/realtime/video-editing">
    Edit video content with the original Lucy model.
  </Card>

  <Card title="Oasis 3 Preview" icon="globe" href="/models/realtime/oasis-3">
    Drive a realtime world model and train policies in it with the `decart-oasis` SDK.
  </Card>
</CardGroup>


# Reference Images
Source: https://docs.platform.decart.ai/models/realtime/reference-images

Best practices for character and style reference images in realtime models

Reference images guide how realtime models transform your video. Lucy 2.1 uses them for character transformation — your face maps onto the reference identity. Lucy Restyle Live uses them for style guidance — the visual aesthetic of the reference carries into the output.

This guide covers image requirements, best practices for character portraits, style references, and troubleshooting.

## How reference images work

<Tabs>
  <Tab title="Lucy 2.1 — Character Reference">
    Upload a face photo and Lucy 2.1 maps your movements, expressions, and gestures onto that character in realtime. The reference image provides the **visual identity** — your camera provides the **motion**.

    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";

    const client = createDecartClient({ apiKey: "your-api-key-here" });
    const model = models.realtime("lucy-2.1");

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

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

    // Upload a character reference
    const photo = document.querySelector("input[type=file]").files[0];
    await realtimeClient.set({
      prompt: "Transform into this character",
      image: photo,
      enhance: true,
    });
    ```
  </Tab>

  <Tab title="Lucy Restyle Live — Style Reference">
    Upload a style image and Lucy Restyle Live uses its visual aesthetic — colors, textures, lighting — to guide the transformation of your live stream.

    ```typescript theme={null}
    import { createDecartClient, models } from "@decartai/sdk";

    const client = createDecartClient({ apiKey: "your-api-key-here" });
    const model = models.realtime("lucy-restyle-2");

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

    const realtimeClient = await client.realtime.connect(stream, {
      model,
      onRemoteStream: (s) => { document.getElementById("output").srcObject = s; },
      initialState: {
        prompt: { text: "Apply this artistic style", enhance: true },
      },
    });

    // Set a style reference image
    const styleImage = await fetch("/style-reference.jpg").then((r) => r.blob());
    await realtimeClient.setImage(styleImage);
    ```
  </Tab>
</Tabs>

## Image requirements

| Property | Requirement |
| - | - |
| **Formats** | JPEG, PNG, WebP |
| **Minimum resolution** | 512×512 pixels recommended |
| **Maximum size** | No hard limit, but keep under 5MB for fast uploads |
| **Accepted input types** | `File`, `Blob`, URL string |

```typescript theme={null}
// From a file input
const file = document.querySelector("input[type=file]").files[0];
await realtimeClient.set({ image: file });

// From a URL
await realtimeClient.set({ image: "https://example.com/character.jpg" });

// From a fetch
const blob = await fetch("/character.jpg").then((r) => r.blob());
await realtimeClient.set({ image: blob });
```

## Character reference best practices (Lucy 2.1)

The quality of the character transformation depends heavily on the reference image. Follow these guidelines for the best results:

### What works well

<CardGroup>
  <Card title="Clear, well-lit portraits" icon="sun">
    Front-facing photos with even lighting and a neutral background produce the most consistent transformations.
  </Card>

  <Card title="Head-and-shoulders framing" icon="crop">
    Cropped portraits with the face centered and clearly visible. Full-body shots reduce face detail.
  </Card>

  <Card title="Neutral expressions" icon="face-smile">
    Neutral or mildly expressive faces transfer better. Extreme expressions can conflict with your live movements.
  </Card>

  <Card title="High resolution" icon="expand">
    At least 512×512 pixels. Higher resolution captures more identity detail.
  </Card>
</CardGroup>

### What to avoid

* **Heavy occlusion** — Images where the face is partially hidden by hands, hair, or objects reduce transformation quality
* **Extreme angles** — Profile shots or heavily tilted faces don't transfer well to front-facing camera input
* **Low resolution** — Blurry or pixelated images lose identity details
* **Multiple faces** — The model picks one face, but results are unpredictable. Crop to a single face.
* **Non-face images** — Character reference expects a face. For non-face references, use Lucy Restyle Live's style reference instead.

### Switching characters

You can change the reference image at any time without reconnecting. The transition is near-instant:

```typescript theme={null}
// Switch to a new character
const newCharacter = document.querySelector("input[type=file]").files[0];
await realtimeClient.set({
  prompt: "Transform into this character",
  image: newCharacter,
  enhance: true,
});

// Or clear the reference entirely to fall back to text-only editing
await realtimeClient.set({ image: null });
```

<Tip>
  `set()` replaces the entire state — always include every field you want to keep. When changing the prompt, include the image again to preserve it.
</Tip>

### Combining with text prompts

Character reference and text prompts work together. The reference sets the identity; the prompt adds modifications:

```typescript theme={null}
// Character reference + text modification
await realtimeClient.set({
  prompt: "Transform into this character, wearing a red cape",
  image: characterPhoto,
  enhance: true,
});

// Change the prompt while keeping the character — include the image to preserve it
await realtimeClient.set({
  prompt: "Same character but in a dark room with dramatic lighting",
  image: characterPhoto,
});
```

## Style reference best practices (Lucy Restyle Live)

When using Lucy Restyle Live for style transfer, the reference image sets the overall visual aesthetic — colors, textures, artistic style, lighting.

### What works well

* **Artworks and illustrations** — Paintings, digital art, and stylized illustrations transfer their visual language effectively
* **Strong visual identity** — Images with distinct color palettes, textures, or lighting produce recognizable style transfers
* **Clean compositions** — Simple, focused images with a clear style are more effective than busy scenes

### What to avoid

* **Photos of real scenes** — These often lack a distinctive "style" for the model to extract
* **Very dark or very bright images** — Extreme exposure can produce washed-out or muddy results
* **Text-heavy images** — The model may try to reproduce text elements, which usually looks wrong in video

### Using style references

```typescript theme={null}
// Set initial style with a reference image
const styleRef = await fetch("/monet-painting.jpg").then((r) => r.blob());
await realtimeClient.setImage(styleRef);

// Combine with a text prompt for more control
realtimeClient.setPrompt("Apply this painting style with warm golden lighting");
```

## Managing reference images in your app

### Image upload UI

Build a simple image picker that sends the file to the realtime client:

```typescript theme={null}
const fileInput = document.getElementById("character-upload") as HTMLInputElement;

fileInput.addEventListener("change", async (e) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (!file) return;

  // Validate before uploading
  if (!["image/jpeg", "image/png", "image/webp"].includes(file.type)) {
    showError("Please upload a JPEG, PNG, or WebP image.");
    return;
  }

  // Show preview
  const preview = document.getElementById("preview") as HTMLImageElement;
  preview.src = URL.createObjectURL(file);

  // Send to Lucy 2.1
  await realtimeClient.set({
    prompt: "Transform into this character",
    image: file,
    enhance: true,
  });
});
```

### Preset characters

Pre-load a gallery of character options that users can tap to transform:

```typescript theme={null}
const characters = [
  { name: "Anime Hero", url: "/characters/anime-hero.jpg", prompt: "Transform into this anime character" },
  { name: "Viking Warrior", url: "/characters/viking.jpg", prompt: "Transform into this fierce viking warrior" },
  { name: "Robot", url: "/characters/robot.jpg", prompt: "Transform into this metallic robot" },
];

async function selectCharacter(character: typeof characters[0]) {
  const imageBlob = await fetch(character.url).then((r) => r.blob());
  await realtimeClient.set({
    prompt: character.prompt,
    image: imageBlob,
    enhance: true,
  });
}
```

### Clearing the reference

Remove the reference image to return to text-only editing:

```typescript theme={null}
// Clear the character reference
await realtimeClient.set({ image: null });

// Now text prompts apply directly to your camera feed
await realtimeClient.set({ prompt: "Add sunglasses" });
```

## Troubleshooting

| Issue | Cause | Solution |
| - | - | - |
| Character doesn't resemble reference | Low-resolution or occluded face | Use a clear, high-res portrait (512×512+) |
| Transformation looks generic | Reference image too small or blurry | Crop to head-and-shoulders, ensure sharp focus |
| Flickering between original and transformed | Prompt and image updated separately | Use `set()` to update both atomically |
| Style reference not taking effect | Using Lucy Restyle Live with `set()` | Use `setImage()` for Lucy Restyle Live style references |
| Image upload fails | Unsupported format | Use JPEG, PNG, or WebP only |
| Slow image upload | Large file size | Resize to under 2048px on longest side before uploading |

## Next steps

<CardGroup>
  <Card title="Lucy 2.1 Guide" icon="sparkles" href="/models/realtime/lucy-2.1">
    Full Lucy 2.1 integration guide
  </Card>

  <Card title="Streaming Best Practices" icon="bolt" href="/models/realtime/streaming-best-practices">
    Optimize your realtime integration
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/examples/use-cases">
    Explore what you can build with realtime models
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript-realtime">
    Full SDK reference for `set()`, `setImage()`, and more
  </Card>
</CardGroup>


# Streaming Best Practices
Source: https://docs.platform.decart.ai/models/realtime/streaming-best-practices

Optimize your realtime video integration for quality, performance, and reliability

Build production-ready realtime video integrations. This guide covers camera setup, connection management, prompt strategy, error handling, and mobile-specific considerations.

## Camera setup

Always use the model's built-in constraints when requesting camera access. Each model defines the `fps`, `width`, and `height` it expects — passing these directly avoids scaling artifacts and wasted bandwidth.

```typescript theme={null}
import { models } from "@decartai/sdk";

const model = models.realtime("lucy-latest");

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

<Warning>
  Requesting a resolution that doesn't match the model's expectations forces the browser to scale the video. This adds latency and can reduce output quality.
</Warning>

### Handling constraint failures

Not every device supports every resolution. Use `ideal` constraints as a fallback when targeting a wide range of hardware:

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

### Front vs back camera

On mobile devices, specify the `facingMode` to select the camera:

```typescript theme={null}
const stream = await navigator.mediaDevices.getUserMedia({
  video: {
    facingMode: "user", // front camera
    // facingMode: "environment" // back camera
    frameRate: model.fps,
    width: model.width,
    height: model.height,
  },
});
```

<Tip>
  When switching between front and back cameras, recapture the stream — each camera has different hardware capabilities that affect resolution and frame rate.
</Tip>

## Front-camera mirroring

For selfie streams, pre-flip the input with `mirror`. Server-baked pixels (watermarks, overlays) then come out in display orientation, and the output renders as-is.

```typescript theme={null}
const realtimeClient = await client.realtime.connect(stream, {
  model,
  mirror: "auto",
  onRemoteStream: (s) => { videoElement.srcObject = s; },
});
```

* `"auto"` mirrors when the input track reports `facingMode: "user"`.
* Pass `true` when your app already knows the camera is front-facing (desktop webcams often don't report `facingMode`).

The SDK only flips the stream it sends — not your local preview.

## Connection management

### Connect once, update prompts

Establishing a WebRTC connection takes a few hundred milliseconds. Don't reconnect just to change the style or prompt — use `set()` or `setPrompt()` instead:

```typescript theme={null}
// Good: update prompt without reconnecting
await realtimeClient.set({ prompt: "New style" });

// Avoid: disconnecting and reconnecting for every prompt change
realtimeClient.disconnect(); // unnecessary
await client.realtime.connect(stream, { model, ... }); // slow
```

### When to reconnect

Reconnect only when you need to:

* **Switch models** (e.g., from Lucy Restyle Live to Lucy 2.1) — each model runs on a different pipeline
* **Switch cameras** — the stream changes, so you need a new connection
* **Change the speed tier** — [fast mode](/models/realtime/lucy-2.5#fast-mode) (`speed: "fast"`) is a connect-time option, not session state
* **Recover from a failed connection** after auto-reconnect gives up

```typescript theme={null}
async function switchModel(newModel: ModelDefinition) {
  realtimeClient.disconnect();
  await new Promise((r) => setTimeout(r, 100)); // allow cleanup
  realtimeClient = await client.realtime.connect(stream, {
    model: newModel,
    onRemoteStream: (s) => { videoElement.srcObject = s; },
  });
}
```

### Track connection state

Always listen to `connectionChange` events to update your UI:

```typescript theme={null}
realtimeClient.on("connectionChange", (state) => {
  switch (state) {
    case "connecting":
      showSpinner();
      break;
    case "connected":
    case "generating":
      hideSpinner();
      break;
    case "reconnecting":
      showReconnectingBanner();
      break;
    case "disconnected":
      showDisconnectedUI();
      break;
  }
});
```

**Connection states:**

| State | Meaning | User-visible action |
| - | - | - |
| `connecting` | Initial connection in progress | Show loading spinner |
| `connected` | Ready to send prompts | Show connected UI |
| `generating` | Actively producing transformed video | Show "live" indicator |
| `reconnecting` | Auto-reconnecting after drop | Show "reconnecting" banner |
| `disconnected` | Not connected | Show reconnect button |

## Prompt strategy

### Use prompt enhancement

Enable `enhance: true` (the default) to let Decart expand short prompts into detailed descriptions. This dramatically improves output quality for simple inputs:

```typescript theme={null}
// Short prompt → enhanced automatically
realtimeClient.setPrompt("Anime style"); // enhanced behind the scenes

// Detailed prompt → disable enhancement for full control
realtimeClient.setPrompt(
  "A highly detailed 2D anime character with smooth cel-shaded lines, soft pastel highlights, large expressive eyes",
  { enhance: false }
);
```

<Tip>
  Start with enhancement enabled. Only disable it when you need exact control over the prompt text.
</Tip>

<Note>
  **Prompt length.** Prompts have a maximum length. As a rough estimate, about 750 characters of English (around 120 words) fit. The exact limit depends on the wording, and other languages may allow fewer characters. If your prompt is too long, you get an error that tells you how many characters of it fit. This applies whether or not prompt enhancement is on.
</Note>

### Atomic updates with `set()`

Since `set()` replaces the entire state, always include every field you want to keep. When using Lucy 2.1 with both a prompt and reference image, include both in every call:

```typescript theme={null}
// Good: atomic update
await realtimeClient.set({
  prompt: "Transform into this character",
  image: characterPhoto,
  enhance: true,
});

// Avoid: separate calls can cause flickering
await realtimeClient.setPrompt("Transform into this character");
await realtimeClient.setImage(characterPhoto); // brief mismatch between prompt and image
```

### Debounce rapid prompt changes

If your UI lets users type prompts in a text field, debounce the input to avoid sending dozens of rapid updates:

```typescript theme={null}
let debounceTimer: ReturnType<typeof setTimeout>;

function onPromptInput(text: string) {
  clearTimeout(debounceTimer);
  debounceTimer = setTimeout(() => {
    realtimeClient.setPrompt(text, { enhance: true });
  }, 300); // wait 300ms after the user stops typing
}
```

## Error handling

### Listen for errors

Always register an error handler. Without one, connection failures go unnoticed:

```typescript theme={null}
import type { DecartSDKError } from "@decartai/sdk";

realtimeClient.on("error", (error: DecartSDKError) => {
  console.error(`[${error.code}] ${error.message}`);

  switch (error.code) {
    case "INVALID_API_KEY":
      redirectToLogin();
      break;
    case "TOKEN_EXPIRED":
      // The client token expired before a reconnect; the session is disconnected.
      showSessionExpired();
      break;
    case "WEB_RTC_ERROR":
      showNetworkError();
      break;
    case "MODEL_NOT_FOUND":
      showModelError();
      break;
    default:
      showGenericError(error.message);
  }
});
```

### Auto-reconnect

The SDK automatically reconnects when an unexpected disconnection occurs (e.g., network interruption). It retries with exponential backoff up to 5 times:

1. Connection drops → state moves to `"reconnecting"`
2. SDK retries with increasing delays
3. If reconnection succeeds → state moves back to `"generating"`
4. If all retries fail → state moves to `"disconnected"` and an `error` event fires

You don't need to implement reconnection logic yourself — but you should update your UI to reflect the `reconnecting` state.

Each reconnect dials with a credential. A static `apiKey` is the token the session started with, and client tokens expire after 60 seconds by default, so pass `apiKeyProvider` to keep reconnects working. See [Token freshness](#token-freshness).

### Wrap setup in try/catch

Camera access and connection can both fail. Catch errors early:

```typescript theme={null}
async function startRealtime() {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      video: { frameRate: model.fps, width: model.width, height: model.height },
    });
    const realtimeClient = await client.realtime.connect(stream, {
      model,
      onRemoteStream: (s) => { videoElement.srcObject = s; },
    });
    return realtimeClient;
  } catch (error) {
    if (error instanceof DOMException && error.name === "NotAllowedError") {
      showCameraPermissionError();
    } else {
      showConnectionError(error);
    }
  }
}
```

## Cleanup

Always release resources when the session ends or the component unmounts:

```typescript theme={null}
function cleanup() {
  // 1. Disconnect from Decart
  realtimeClient.disconnect();

  // 2. Remove event listeners
  realtimeClient.off("connectionChange", onConnectionChange);
  realtimeClient.off("error", onError);

  // 3. Stop the camera
  stream.getTracks().forEach((track) => track.stop());
}

// Browser: cleanup on page unload
window.addEventListener("beforeunload", cleanup);

// React: cleanup on unmount
useEffect(() => {
  return () => cleanup();
}, []);
```

<Warning>
  Forgetting to call `disconnect()` leaves WebRTC connections open, consuming bandwidth and server resources. Always clean up.
</Warning>

## Client-side authentication

Never expose your permanent API key in client-side code. Use short-lived client tokens instead:

<Steps>
  <Step title="Create a backend endpoint">
    ```typescript theme={null}
    // Your server (Express, Next.js, etc.)
    const token = await client.tokens.create(); // expires in 60 s by default (expiresIn: 1–3600)
    res.json(token);
    ```
  </Step>

  <Step title="Let the SDK fetch a token for every dial">
    ```typescript theme={null}
    const client = createDecartClient({
      apiKeyProvider: async () => {
        const res = await fetch("/api/realtime-token", { method: "POST" });
        const { apiKey } = await res.json(); // short-lived client token, not your permanent key
        return apiKey;
      },
    });
    ```
  </Step>
</Steps>

### Token freshness

Client tokens expire **60 seconds** after minting by default. A token minted on page load is usually dead by the time the user has granted the camera and pressed start, and a reconnect with the same token is refused too. The SDK reads the token's `exp` before every dial and rejects an expired one with `TOKEN_EXPIRED` instead of opening a socket: `connect()` rejects, and a reconnect emits `error` and moves to `disconnected`.

`apiKeyProvider` avoids both, because the SDK calls it right before every connect and reconnect. With a static `apiKey`, mint right before `connect()` and size `expiresIn` to your connect window. See [Token lifetime](/getting-started/client-tokens#token-lifetime).

<Info>
  Client tokens only prevent **new** connections after expiry. Active WebRTC sessions continue working even after the token expires.
</Info>

## Firewall and network configuration

Realtime integrations need outbound access to Decart's API, signaling, diagnostics, and media endpoints. The full list of domains, ports, bandwidth requirements, and proxy guidance lives in the [Network Requirements](/integrations/network-requirements) guide — share it with the IT or security team responsible for the deployment environment.

<Warning>
  UDP restrictions and proxy behavior are the most common causes of "it connects, but the video freezes" issues.
</Warning>

## Mobile considerations

### React Native / Expo

React Native realtime runs on [LiveKit's React Native stack](https://github.com/livekit/client-sdk-react-native) — plain `react-native-webrtc` is not supported.

* **Install the LiveKit packages and register globals.** `registerGlobals()` must run before your app/router entrypoint so the SDK can reach WebRTC:

```typescript theme={null}
// livekit-bootstrap.ts — imported before expo-router/entry
import { registerGlobals } from "@livekit/react-native";

registerGlobals();
```

For Expo, add the `@livekit/react-native-expo-plugin` and `@config-plugins/react-native-webrtc` config plugins to `app.json`, then run `npx expo prebuild`. LiveKit does not run in Expo Go.

* **Select VP8 with `preferredVideoCodec`.** React Native works best with VP8. Set it as an option — the SDK negotiates the codec, so there's no manual SDP rewriting:

```typescript theme={null}
const realtimeClient = await client.realtime.connect<MediaStream>(stream, {
  model,
  preferredVideoCodec: "vp8",
  onRemoteStream: (s) => setRemoteStream(s),
});
```

* **Size the camera with `resolveFpsNumber`.** Use the model's dimensions and resolve its FPS descriptor to a number for native capture:

```typescript theme={null}
import { resolveFpsNumber } from "@decartai/sdk";
import { mediaDevices } from "@livekit/react-native-webrtc";

const stream = await mediaDevices.getUserMedia({
  audio: false,
  video: {
    facingMode: "user",
    frameRate: resolveFpsNumber(model.fps),
    width: model.width,
    height: model.height,
  },
});
```

* **Browser-only features are rejected.** `mirror` and the deep connectivity preflight fail with `UNSUPPORTED_PLATFORM_FEATURE` on React Native. Mirror the local preview with LiveKit's `<RTCView mirror>` instead.

* **Handle app lifecycle.** Disconnect when backgrounded, reconnect when foregrounded:

```typescript theme={null}
const handleAppState = (nextState: AppStateStatus) => {
  if (nextState === "active") {
    initializeWebRTC({ model, facingMode });
  } else {
    cleanupWebRTC();
  }
};

AppState.addEventListener("change", handleAppState);
```

<Tip>
  See the [Realtime Mobile App](/examples/real-time-mobile-app) walkthrough for a complete Expo integration with model switching and style presets.
</Tip>

### Battery and bandwidth

Realtime WebRTC streaming consumes significant resources on mobile:

* **Disconnect when not visible.** Use app lifecycle events to pause streaming in the background.
* **Match camera constraints to model.** Don't request 4K when the model expects 720p — this wastes encoding power and bandwidth.
* **Use front camera when possible.** Front cameras typically have lower resolution, which reduces encoding overhead.

## Session tracking

Use the `generationTick` event to track session duration and display billing information to users:

```typescript theme={null}
realtimeClient.on("generationTick", ({ seconds }) => {
  document.getElementById("timer").textContent = `${seconds}s`;
});
```

## Quick reference

| Topic | Recommendation |
| - | - |
| Camera setup | Use `model.fps`, `model.width`, `model.height` |
| Prompt changes | Use `set()` or `setPrompt()` — don't reconnect |
| Prompt + image | Use `set()` atomically — avoid separate calls |
| Enhancement | Keep `enhance: true` unless you need exact control |
| Error handling | Register `error` and `connectionChange` listeners |
| Reconnection | Handled by SDK automatically (5 retries, backoff) |
| Cleanup | Always `disconnect()` + stop media tracks |
| Auth | Client tokens in the browser, never your API key; `apiKeyProvider` keeps every connect and reconnect fresh |
| Network | Follow the [Network Requirements](/integrations/network-requirements) guide — TCP 443 plus outbound UDP 7882 / 3478 |
| Mobile | Use the LiveKit RN stack + `registerGlobals()`, set `preferredVideoCodec: "vp8"`, handle app lifecycle |

## Next steps

<CardGroup>
  <Card title="Lucy 2.1 Guide" icon="sparkles" href="/models/realtime/lucy-2.1">
    Character transformation with reference images
  </Card>

  <Card title="Reference Image Guide" icon="image" href="/models/realtime/reference-images">
    Best practices for character and style reference images
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript-realtime">
    Full SDK reference for realtime features
  </Card>

  <Card title="Mobile App" icon="mobile" href="/examples/real-time-mobile-app">
    Complete Expo walkthrough
  </Card>
</CardGroup>


# Video Editing
Source: https://docs.platform.decart.ai/models/realtime/video-editing



Edit live video streams in realtime with precise modifications. Add objects, change elements, or modify appearances in any live video feed with minimal latency.

The Video Editing Realtime API takes a video stream and editing instructions, then generates a modified version of the video with your requested changes applied in realtime.

## Model Specifications

The model processes video with these specifications:

* **Frame Rate:** 25 FPS
* **Resolution:** 1280x704 (16:9 aspect ratio)

## Realtime API

The realtime API uses WebRTC for low-latency video editing. Clients establish a connection with our inference server, stream video with editing instructions, and receive a modified video stream in return.

The connection remains active as long as the input video stream continues, allowing you to apply different edits on-the-fly to modify the output video dynamically.

### Installation

```bash theme={null}
npm install @decartai/sdk
```

### Basic Usage

```tsx theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const model = models.realtime("lucy-2.1");

// Get user's camera stream with model specifications
const stream = await navigator.mediaDevices.getUserMedia({
  audio: true,
  video: {
    frameRate: model.fps,
    width: model.width,
    height: model.height,
  }
});

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

// Connect and edit the video stream
const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (editedStream) => {
    // Display the edited video
    const videoElement = document.querySelector("#video-output");
    videoElement.srcObject = editedStream;
  }
});

// Apply different edits on the fly
realtimeClient.setPrompt("Change the person's shirt to red");

// Disconnect when done
realtimeClient.disconnect();
```

### Advanced Features

#### Character Reference

Use a reference image to transform yourself into a different character. Lucy 2.1 supports both text-only editing and character reference in the same realtime session. Use `set()` to replace the session state atomically. Include all fields you want to keep — omitted fields are cleared.

```tsx theme={null}
import { createDecartClient, models } from "@decartai/sdk";

// Use Lucy 2.1 for character reference support
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: "your-api-key-here"
});

const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (editedStream) => {
    videoElement.srcObject = editedStream;
  }
});

// Set prompt and character reference image together
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    await realtimeClient.set({
      prompt: "Transform into this character",
      image: file,
      enhance: true,
    });
  }
});

// Or set from a URL
await realtimeClient.set({
  prompt: "Look like this person",
  image: "https://example.com/character-reference.jpg",
});

// Set a new image only (clears any previous prompt)
await realtimeClient.set({ image: file });

// Set a new prompt only (clears any previous image)
await realtimeClient.set({ prompt: "Add sunglasses" });
```

**Supported formats:** JPEG, PNG, WebP

<Tip>`set()` replaces the entire state — fields you omit are cleared. Always include every field you want to keep. Use `set()` instead of separate `setPrompt()` and `setImage()` calls to avoid intermediate states.</Tip>

#### Dynamic Video Editing

```tsx theme={null}
// Add objects to the scene
realtimeClient.setPrompt("Add a bird flying overhead");

// Modify existing elements
realtimeClient.setPrompt("Change the car color to blue");

// Remove objects from the scene
realtimeClient.setPrompt("Remove the tree from the background");

// Change appearances
realtimeClient.setPrompt("Make the person's hair blonde");
```

#### Connection State Management

```tsx theme={null}
import { createDecartClient, type DecartSDKError } from "@decartai/sdk";

const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (editedStream) => {
    videoElement.srcObject = editedStream;
  }
});

// Monitor connection state
realtimeClient.on("connectionChange", (state) => {
  console.log(`Connection: ${state}`); // "connecting" | "connected" | "disconnected"
  
  if (state === "connected") {
    document.getElementById("status").textContent = "Live Editing";
  } else if (state === "disconnected") {
    document.getElementById("status").textContent = "Disconnected";
  }
});

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

// Check connection synchronously
const isConnected = realtimeClient.isConnected();
const currentState = realtimeClient.getConnectionState();
```

#### Complete Example with Error Handling

```tsx theme={null}
import { createDecartClient, models, type DecartSDKError } from "@decartai/sdk";

async function setupVideoEditing() {
  try {
    const model = models.realtime("lucy-2.1");
    
    // Get camera with optimal settings
    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 videoElement = document.getElementById("output-video");
        videoElement.srcObject = editedStream;
      }
    });

    // Set up event handlers
    realtimeClient.on("connectionChange", (state) => {
      updateUIStatus(state);
    });

    realtimeClient.on("error", (error) => {
      console.error("Error:", error);
      showErrorMessage(error.message);
    });

    // Editing controls
    document.getElementById("add-dog").addEventListener("click", () => {
      realtimeClient.setPrompt("Add a small dog running around");
    });

    document.getElementById("change-hair").addEventListener("click", () => {
      realtimeClient.setPrompt("Change the person's hair to curly brown hair");
    });

    document.getElementById("add-sunglasses").addEventListener("click", () => {
      realtimeClient.setPrompt("Add stylish sunglasses to the person");
    });

    // Cleanup on page unload
    window.addEventListener("beforeunload", () => {
      realtimeClient.disconnect();
    });

    return realtimeClient;
  } catch (error) {
    console.error("Setup failed:", error);
    throw error;
  }
}
```

### WebSocket + WebRTC (Vanilla)

For direct WebSocket communication without the SDK:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Video Editing - WebRTC</title>
</head>
<body>
  <!-- Local and edited video streams -->
  <video id="localVideo" autoplay muted playsinline width="45%"></video>
  <video id="remoteVideo" autoplay playsinline width="45%"></video>
  <br>
  
  <!-- Controls -->
  <button id="startBtn">Start</button>
  <input id="promptInput" placeholder="Enter editing instruction...">
  <button id="sendBtn">Apply Edit</button>
  
  <!-- Quick edit buttons -->
  <br><br>
  <button onclick="quickEdit('Add a small dog in the background')">Add Dog</button>
  <button onclick="quickEdit('Change the shirt color to blue')">Blue Shirt</button>
  <button onclick="quickEdit('Add sunglasses to the person')">Add Sunglasses</button>

  <script>
    // WebSocket connection with API key and model
    const ws = new WebSocket('wss://api.decart.ai/v1/stream?api_key=YOUR_API_KEY&model=lucy-2.1');
    let peerConnection;

    // Handle server messages
    ws.onmessage = async (event) => {
      const message = JSON.parse(event.data);
      
      if (message.type === 'answer' && peerConnection) {
        await peerConnection.setRemoteDescription({
          type: 'answer', 
          sdp: message.sdp
        });
      }
    };

    // Start WebRTC connection
    async function startConnection() {
      if (ws.readyState !== WebSocket.OPEN) return;

      // Create peer connection
      peerConnection = new RTCPeerConnection({
        iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
      });

      // Send ICE candidates to server
      peerConnection.onicecandidate = (event) => {
        if (event.candidate) {
          ws.send(JSON.stringify({
            type: 'ice-candidate',
            candidate: event.candidate
          }));
        }
      };

      // Receive edited video stream
      peerConnection.ontrack = (event) => {
        document.getElementById('remoteVideo').srcObject = event.streams[0];
      };

      // Get user camera with optimal settings
      const localStream = await navigator.mediaDevices.getUserMedia({
        video: {
          width: { ideal: 1280 },
          height: { ideal: 704 },
          frameRate: { ideal: 25 }
        },
        audio: false
      });

      // Display local video
      document.getElementById('localVideo').srcObject = localStream;
      
      // Add tracks to peer connection
      localStream.getTracks().forEach(track => {
        peerConnection.addTrack(track, localStream);
      });

      // Create and send offer
      const offer = await peerConnection.createOffer();
      await peerConnection.setLocalDescription(offer);
      
      ws.send(JSON.stringify({
        type: 'offer',
        sdp: offer.sdp
      }));
    }

    // Send editing instruction
    function sendPrompt() {
      const promptInput = document.getElementById('promptInput');
      const prompt = promptInput.value.trim();
      
      if (prompt && ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({
          type: 'prompt',
          prompt: prompt
        }));
      }
    }

    // Quick edit function
    function quickEdit(prompt) {
      if (ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({
          type: 'prompt',
          prompt: prompt
        }));
      }
    }

    // Event listeners
    document.getElementById('startBtn').onclick = startConnection;
    document.getElementById('sendBtn').onclick = sendPrompt;
    document.getElementById('promptInput').onkeypress = (e) => {
      if (e.key === 'Enter') sendPrompt();
    };
  </script>
</body>
</html>
```


# Video Restyling
Source: https://docs.platform.decart.ai/models/realtime/video-restyling



Transform live video streams in realtime. Insert your imagination into any live video feed, turning passive viewing into active creation.

The Video Restyling Realtime API takes a video stream and a prompt, then generates a transformed version of the video based on that prompt with minimal latency.

## Model Specifications

The model expects video input with these specifications:

* **Frame Rate:** 25 FPS
* **Resolution:** 1280x704 (16:9 aspect ratio)

## Realtime API

The realtime API uses WebRTC for low-latency video transformation. Clients establish a connection with our inference server, stream video with a prompt, and receive a transformed video stream in return.

The connection remains active as long as the input video stream continues, allowing you to change prompts on-the-fly to modify the output video dynamically.

### Installation

```bash theme={null}
npm install @decartai/sdk
```

### Basic Usage

```tsx theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const model = models.realtime("lucy-restyle-2");

// Get user's camera stream with model specifications
const stream = await navigator.mediaDevices.getUserMedia({
  audio: true,
  video: {
    frameRate: model.fps,
    width: model.width,
    height: model.height,
  }
});

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

// Connect and transform the video stream
const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (transformedStream) => {
    // Display the transformed video
    const videoElement = document.querySelector("#video-output");
    videoElement.srcObject = transformedStream;
  }
});

// Change the style on the fly
realtimeClient.setPrompt("Cyberpunk city");

// Disconnect when done
realtimeClient.disconnect();
```

### Advanced Features

#### Image Reference

Use a reference image to guide the style transformation. Instead of describing a style with text, you can provide an image that the model will use as a visual reference.

```tsx theme={null}
// Set a reference image to guide the style
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    await realtimeClient.setImage(file);
  }
});

// Or set from a URL
await realtimeClient.setImage('https://example.com/style-reference.jpg');
```

**Supported formats:** JPEG, PNG, WebP

<Tip>Image reference works great for capturing specific artistic styles, color palettes, or visual aesthetics that are hard to describe in text.</Tip>

#### Dynamic Prompt Management

```tsx theme={null}
// Change prompts without reconnecting
realtimeClient.setPrompt("Studio Ghibli animation style");
```

#### Connection State Management

```tsx theme={null}
import { createDecartClient, type DecartSDKError } from "@decartai/sdk";

const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (transformedStream) => {
    videoElement.srcObject = transformedStream;
  }
});

// Monitor connection state
realtimeClient.on("connectionChange", (state) => {
  console.log(`Connection: ${state}`); // "connecting" | "connected" | "disconnected"
  
  if (state === "connected") {
    document.getElementById("status").textContent = "Live";
  } else if (state === "disconnected") {
    document.getElementById("status").textContent = "Disconnected";
  }
});

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

// Check connection synchronously
const isConnected = realtimeClient.isConnected();
const currentState = realtimeClient.getConnectionState();
```

#### Complete Example with Error Handling

```tsx theme={null}
import { createDecartClient, models, type DecartSDKError } from "@decartai/sdk";

async function setupVideoTransform() {
  try {
    const model = models.realtime("lucy-restyle-2");
    
    // Get camera with optimal settings
    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: (transformedStream) => {
        const videoElement = document.getElementById("output-video");
        videoElement.srcObject = transformedStream;
      }
    });

    // Set up event handlers
    realtimeClient.on("connectionChange", (state) => {
      updateUIStatus(state);
    });

    realtimeClient.on("error", (error) => {
      console.error("Error:", error);
      showErrorMessage(error.message);
    });

    // Style controls
    document.getElementById("style-input").addEventListener("change", (e) => {
      realtimeClient.setPrompt(e.target.value);
    });

    // Cleanup on page unload
    window.addEventListener("beforeunload", () => {
      realtimeClient.disconnect();
    });

    return realtimeClient;
  } catch (error) {
    console.error("Setup failed:", error);
    throw error;
  }
}
```

### WebSocket + WebRTC (Vanilla)

For direct WebSocket communication without the SDK:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Decart Video Restyling - WebRTC</title>
</head>
<body>
  <!-- Local and transformed video streams -->
  <video id="localVideo" autoplay muted playsinline width="45%"></video>
  <video id="remoteVideo" autoplay playsinline width="45%"></video>
  <br>
  
  <!-- Controls -->
  <button id="startBtn">Start</button>
  <input id="promptInput" placeholder="Enter style prompt...">
  <button id="sendBtn">Send Prompt</button>

  <script>
    // WebSocket connection with API key and model
    const ws = new WebSocket('wss://api.decart.ai/v1/stream?api_key=YOUR_API_KEY&model=lucy-restyle-2');
    let peerConnection;

    // Handle server messages
    ws.onmessage = async (event) => {
      const message = JSON.parse(event.data);
      
      if (message.type === 'answer' && peerConnection) {
        await peerConnection.setRemoteDescription({
          type: 'answer', 
          sdp: message.sdp
        });
      }
    };

    // Start WebRTC connection
    async function startConnection() {
      if (ws.readyState !== WebSocket.OPEN) return;

      // Create peer connection
      peerConnection = new RTCPeerConnection({
        iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
      });

      // Send ICE candidates to server
      peerConnection.onicecandidate = (event) => {
        if (event.candidate) {
          ws.send(JSON.stringify({
            type: 'ice-candidate',
            candidate: event.candidate
          }));
        }
      };

      // Receive transformed video stream
      peerConnection.ontrack = (event) => {
        document.getElementById('remoteVideo').srcObject = event.streams[0];
      };

      // Get user camera with optimal settings
      const localStream = await navigator.mediaDevices.getUserMedia({
        video: {
          width: { ideal: 1280 },
          height: { ideal: 704 },
          frameRate: { ideal: 25 }
        },
        audio: false
      });

      // Display local video
      document.getElementById('localVideo').srcObject = localStream;
      
      // Add tracks to peer connection
      localStream.getTracks().forEach(track => {
        peerConnection.addTrack(track, localStream);
      });

      // Create and send offer
      const offer = await peerConnection.createOffer();
      await peerConnection.setLocalDescription(offer);
      
      ws.send(JSON.stringify({
        type: 'offer',
        sdp: offer.sdp
      }));
    }

    // Send style prompt
    function sendPrompt() {
      const promptInput = document.getElementById('promptInput');
      const prompt = promptInput.value.trim();
      
      if (prompt && ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({
          type: 'prompt',
          prompt: prompt
        }));
      }
    }

    // Event listeners
    document.getElementById('startBtn').onclick = startConnection;
    document.getElementById('sendBtn').onclick = sendPrompt;
    document.getElementById('promptInput').onkeypress = (e) => {
      if (e.key === 'Enter') sendPrompt();
    };
  </script>
</body>
</html>
```


# Virtual Try-On
Source: https://docs.platform.decart.ai/models/realtime/virtual-try-on

Dress people in live or recorded video with text prompts, garment images, or both.

Try on clothing and accessories in realtime. Stream a live camera feed, describe the outfit or provide a reference image of the garment, and Lucy VTON will realistically dress the subject while preserving motion and body shape — all with minimal latency.

<Note>
  **Versions.** The examples below use `lucy-vton-latest`, which resolves to `lucy-vton-3.6`. `lucy-vton-3.5` remains available by name on both surfaces at 720p. Both versions support [fast mode](#fast-mode).
</Note>

## Quick start (Realtime)

<CodeGroup>
  ```tsx JavaScript SDK theme={null}
  import { createDecartClient, models } from "@decartai/sdk";

  const model = models.realtime("lucy-vton-latest");

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

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

  const realtimeClient = await client.realtime.connect(stream, {
    model,
    mirror: "auto",
    onRemoteStream: (editedStream) => {
      document.querySelector("#video-output").srcObject = editedStream;
    },
  });

  // Try on with a garment image and descriptive prompt
  const garmentFile = document.querySelector('input[type="file"]').files[0];
  await realtimeClient.set({
    prompt: "Substitute the current top with a navy blue hoodie with a white cross logo on the chest",
    image: garmentFile,
    enhance: false,
  });

  // Disconnect when done
  realtimeClient.disconnect();
  ```

  ```python Python SDK theme={null}
  from decart import models
  from decart.realtime import RealtimeClient, RealtimeConnectOptions
  from decart.types import ModelState

  model = models.realtime("lucy-vton-latest")

  realtime_client = await RealtimeClient.connect(
      api_key="your-api-key-here",
      stream=camera_stream,
      options=RealtimeConnectOptions(
          model=model,
          initial_state=ModelState(
              prompt="Substitute the current top with a red leather jacket with a zip front",
          ),
          on_remote_stream=lambda edited_stream: handle_stream(edited_stream),
      ),
  )

  # Change outfit on the fly
  await realtime_client.set_prompt("Substitute the current top with a blue denim jacket with a relaxed fit")

  # Disconnect when done
  await realtime_client.disconnect()
  ```

  ```kotlin Android SDK 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 client = DecartClient(context, DecartClientConfig(apiKey = "your-api-key"))
  val realtime = client.realtime

  realtime.initialize(eglBase)

  realtime.connect(
      localVideoTrack = cameraTrack,
      localAudioTrack = null,
      options = ConnectOptions(
          model = RealtimeModels.LUCY_VTON_LATEST,
          onRemoteVideoTrack = { track ->
              remoteRenderer.addSink(track)
          },
          initialPrompt = InitialPrompt("Substitute the current top with a red leather jacket with a zip front")
      )
  )

  // Change outfit on the fly
  realtime.setPrompt("Substitute the current top with a blue denim jacket with a relaxed fit", enhance = true)
  ```

  ```swift Swift SDK theme={null}
  import DecartSDK

  let config = DecartConfiguration(apiKey: "your-api-key-here")
  let client = DecartClient(decartConfiguration: config)

  let model = Models.realtime(.lucyVtonLatest)

  let realtimeManager = try await client.realtime.connect(
      stream: cameraStream,
      model: model,
      initialState: .init(prompt: "Substitute the current top with a red leather jacket with a zip front")
  ) { editedStream in
      // Display the edited video
      videoView.stream = editedStream
  }

  // Change outfit on the fly
  try await realtimeManager.setPrompt("Substitute the current top with a blue denim jacket with a relaxed fit")
  ```
</CodeGroup>

### Realtime Parameters

* **`prompt`** — Text description of the outfit change. Use the **substitute** or **add** patterns described in the [VTON 3.5 Prompting Guide](/models/realtime/vton-3.5-prompting).
* **`image`** — A garment reference image to guide the try-on. Supported formats: JPEG, PNG, WebP.
* **`enhance`** — Whether to auto-enhance the prompt (default: `true`). Set to `false` when you provide detailed prompts yourself.
* **`speed`** — Connect-time option. `"fast"` opts into [fast mode](#fast-mode): lower latency and higher throughput, billed at 2x the standard realtime rate. Omit for standard mode.

<Tip>`set()` replaces the entire state — fields you omit are cleared. Always include every field you want to keep.</Tip>

### Fast mode

Fast mode (`speed: "fast"`) gives the session lower latency and higher throughput; output quality is unchanged. It is available for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5`, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode. See [Pricing](/getting-started/pricing#realtime-models).

Fast mode is a connect-time setting: pass `speed: "fast"` when connecting. Changing it requires a reconnect; it can't be toggled mid-session with `set()`.

<CodeGroup>
  ```tsx JavaScript SDK theme={null}
  const realtimeClient = await client.realtime.connect(stream, {
    model,
    mirror: "auto",
    speed: "fast", // fast mode
    onRemoteStream: (editedStream) => {
      document.querySelector("#video-output").srcObject = editedStream;
    },
  });
  ```

  ```python Python SDK theme={null}
  options = RealtimeConnectOptions(
      model=model,
      on_remote_stream=on_remote_stream,
      speed="fast",  # fast mode
  )
  ```

  ```text Raw WebSocket theme={null}
  wss://api.decart.ai/v1/stream?api_key=YOUR_API_KEY&model=lucy-vton-latest&speed=fast
  ```
</CodeGroup>

<Note>
  Standard mode is the *absence* of the option — don't send `speed=standard`. The option ships in [JavaScript](/sdks/javascript-realtime#fast-mode) v0.2.2, [Python](/sdks/python-realtime#fast-mode) v0.2.1, [Android](/sdks/android-realtime#fast-mode) 0.8.1 and [Swift](/sdks/swift-realtime#fast-mode) v0.7.1; on earlier `@decartai/sdk` versions pass `queryParams: { speed: "fast" }` instead.
</Note>

### Using Reference Images

For the best results, provide a **garment reference image** paired with a **descriptive prompt**. This gives the model the clearest signal of what to apply.

```tsx theme={null}
// Best approach: reference image + descriptive prompt
await realtimeClient.set({
  prompt: "Substitute the current top with a black bomber jacket with a blue logo on the chest and a zip front",
  image: garmentFile,
  enhance: false,
});

// Reference image only — the model dresses the person to match
await realtimeClient.set({ image: garmentFile });
```

**Reference image tips:**

* **Clean garment images work best** — just the clothing item, no person wearing it
* **White or plain backgrounds** are ideal
* **At least 512×512 pixels** — the model reproduces what it sees, so a clear image produces better results
* If your source image shows a person wearing the garment, consider using an image editing model to extract just the clothing item first

### Dynamic Outfit Changes

Switch outfits instantly during a live session — call `setPrompt()` or `set()` again at any time without reconnecting:

```tsx theme={null}
// Start with a casual look
realtimeClient.setPrompt("Substitute the current top with a grey crewneck sweatshirt with a large blue logo on the front");

// Switch to formal
realtimeClient.setPrompt("Substitute the current top with a navy blue blazer, worn over a light blue dress shirt");

// Try an accessory
realtimeClient.setPrompt("Add a black baseball cap with a blue logo to the person's head");
```

### Client Token Security

In production, never expose your permanent API key (`dct_*`) to the browser. Instead, create a short-lived **client token** on your server and pass it to the frontend:

```typescript theme={null}
// Server: app/api/tokens/route.ts
import { createDecartClient } from "@decartai/sdk";

export async function POST() {
  const client = createDecartClient({ apiKey: process.env.DECART_API_KEY });
  const token = await client.tokens.create();
  return Response.json(token);
}
```

```typescript theme={null}
// Client: let the SDK fetch a token right before every connect and reconnect
const client = createDecartClient({
  apiKeyProvider: async () => {
    const res = await fetch("/api/tokens", { method: "POST" });
    const { apiKey } = await res.json(); // short-lived client token, never your dct_ key
    return apiKey;
  },
});
const rtClient = await client.realtime.connect(stream, { model, onRemoteStream });
```

<Note>
  Client tokens expire 60 seconds after minting by default. Fetch one per dial with `apiKeyProvider`, as above, rather than minting when the page loads. Active WebRTC sessions continue working after the token expires. See [Token lifetime](/getting-started/client-tokens#token-lifetime).
</Note>

## Prompting

For how to write effective try-on prompts — patterns, examples, and common mistakes — see the [VTON 3.5 Prompting Guide](/models/realtime/vton-3.5-prompting).

### Generating Prompts with an LLM

For user-uploaded garment images where you don't have a pre-written prompt, you can use any vision LLM (GPT-4o-mini, Claude, Gemini) to auto-generate a descriptive prompt from the garment image:

```typescript theme={null}
// Send the garment image (and optionally a camera frame) to your LLM
const formData = new FormData();
formData.append("image", garmentBlob);
formData.append("personFrame", cameraFrameBlob); // optional — improves accuracy

const res = await fetch("/api/enhance-prompt", { method: "POST", body: formData });
const { prompt } = await res.json();
// → "Substitute the grey crewneck sweater with a blue and pink flame print hoodie with an oversized fit"
```

<Tip>
  Sending a camera frame of the person gives the LLM context about what they're currently wearing, so it generates more accurate prompts (e.g. "Substitute the grey sweater" instead of generic "Substitute the current top").
</Tip>

### Extracting Clothing from Model Photos

When users upload photos from fashion websites where a model is wearing the garment, the image contains a person and background rather than a clean garment shot. Use an image editing model to extract just the clothing item on a white background before sending it to the try-on model.

## Batch API

Lucy VTON is also available as a batch/queue model for processing pre-recorded videos asynchronously. Submit a job, poll for completion, then download the result.

<CodeGroup>
  ```bash Curl theme={null}
  # Submit job
  JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-vton-latest \
    -H "X-API-KEY: $DECART_API_KEY" \
    -F "data=@person.mp4" \
    -F "prompt=Substitute the current top with a red leather jacket with a zip front" \
    -F "reference_image=@garment.jpg" | jq -r '.job_id')

  # Poll until completed
  while true; do
    STATUS=$(curl -s -H "X-API-KEY: $DECART_API_KEY" \
      https://api.decart.ai/v1/jobs/$JOB_ID | jq -r '.status')
    echo "Status: $STATUS"
    [ "$STATUS" = "completed" ] && break
    [ "$STATUS" = "failed" ] && exit 1
    sleep 2
  done

  # Download result
  curl -H "X-API-KEY: $DECART_API_KEY" \
    https://api.decart.ai/v1/jobs/$JOB_ID/content --output output.mp4
  ```

  ```javascript JavaScript SDK theme={null}
  import { createDecartClient, models } from "@decartai/sdk";
  import { readFileSync, writeFileSync } from "fs";

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

  const videoBuffer = readFileSync("person.mp4");
  const videoBlob = new Blob([videoBuffer], { type: "video/mp4" });

  const imageBuffer = readFileSync("garment.jpg");
  const imageBlob = new Blob([imageBuffer], { type: "image/jpeg" });

  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-vton-latest"),
    prompt: "Substitute the current top with a red leather jacket with a zip front",
    data: videoBlob,
    reference_image: imageBlob,
    onStatusChange: (job) => console.log(`Status: ${job.status}`),
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("output.mp4", buffer);
  }
  ```

  ```python Python SDK theme={null}
  import asyncio
  from decart import DecartClient, models

  async def virtual_try_on():
      async with DecartClient(api_key="your-api-key-here") as client:
          with open("person.mp4", "rb") as video_file:
              with open("garment.jpg", "rb") as garment_image:
                  result = await client.queue.submit_and_poll({
                      "model": models.video("lucy-vton-latest"),
                      "prompt": "Substitute the current top with a red leather jacket with a zip front",
                      "data": video_file,
                      "reference_image": garment_image,
                      "on_status_change": lambda job: print(f"Status: {job.status}"),
                  })

          if result.status == "completed":
              with open("output.mp4", "wb") as f:
                  f.write(result.data)

  asyncio.run(virtual_try_on())
  ```
</CodeGroup>

### Batch Parameters

* `data` (**required**) — Input video of the person to dress.
* `prompt` (**optional**) — Text description of the outfit change. Use the substitute/add patterns from the [prompting guide](/models/realtime/vton-3.5-prompting). Defaults to empty string.
* `reference_image` (**optional**) — An image of the garment or accessory to try on.
* `resolution` (**optional**) — Output resolution: `720p` (default).
* `seed` (**optional**) — Seed for reproducible generation (0–4294967295).
* `enhance_prompt` (**optional**) — Whether to enhance the prompt (default: `true`).

### Video Requirements

* **Format:** MP4 (H.264 or VP8 codec)
* **Aspect Ratio:** 16:9 (landscape) or 9:16 (portrait) — a 2:1 (landscape) / 1:2 (portrait) shape is also supported
* **File Size:** Maximum 200MB
* **Output Resolution:** 1280×720 / 720×1280 (16:9 / 9:16) or 1280×640 / 640×1280 (2:1 / 1:2)

VTON infers the aspect ratio from the input video stream and maps it to the nearest supported generation shape.

## Next steps

<CardGroup>
  <Card icon="cube" title="Try in the Platform" href="https://platform.decart.ai/models/lucy-vton">
    Try virtual try-on in the interactive platform.
  </Card>

  <Card icon="code" title="Batch API Reference" href="/api-reference/lucy-vton-latest">
    Full API documentation for the batch virtual try-on endpoint.
  </Card>

  <Card icon="bolt" title="Streaming Best Practices" href="/models/realtime/streaming-best-practices">
    Optimize your realtime integration for the best experience.
  </Card>

  <Card icon="github" title="Try-On Examples" href="https://github.com/DecartAI/tryon-examples">
    Production-ready examples: e-commerce, digital mirror, outfit builder, and more.
  </Card>
</CardGroup>


# Prompting Guide
Source: https://docs.platform.decart.ai/models/realtime/vton-3.5-prompting

How to write effective prompts for Lucy VTON — principles, examples, and common mistakes for every try-on.

Lucy VTON applies garments and accessories from a reference image onto a person. This guide covers both `lucy-vton-3.5` and `lucy-vton-3.6` — they share the same prompt-enhancement model server-side, so the guidance below is identical for either. A strong prompt tells the model what item or outfit to apply, where it belongs, and which visible garment details matter.

Write the prompt like clear styling direction: name the item, describe what it looks like, and avoid asking for unrelated changes.

<Note>
  **Prompt length.** Prompts have a maximum length. As a rough estimate, about 750 characters of English (around 120 words) fit. The exact limit depends on the wording, and other languages may allow fewer characters. If your prompt is too long, you get an error that tells you how many characters of it fit. This applies whether or not prompt enhancement is on.
</Note>

## At a glance

| ✅ Do | ❌ Don't |
| - | - |
| `"Substitute the upper body garment with a grey sleeveless crew-neck t-shirt featuring a single chest pocket with a small logo."` | `"Make me fashionable."` — too vague |
| `"Substitute the footwear with white low-top leather sneakers with a clean toe box and thin rubber sole."` | `"Change the background."` — unrelated change |
| `"Add a black thick ribbed-knit beanie with a folded cuff and a small white brand label to the outfit."` | `"Add the [Brand name] logo."` — inventing a detail not visible in the reference |

## Core prompting principles

### 1. Use one clear action

Each prompt should focus on one try-on action.

Use **substitute** when an existing clothing region should be replaced:

* “**Substitute** the upper body garment with a cropped black leather jacket.”
* “**Substitute** the lower body garment with wide-leg white tailored trousers.”
* “**Substitute** the outfit with a red sleeveless midi dress.”

Use **add** when the item sits on top of the existing outfit and does not replace clothing:

* “**Add** a black ribbed-knit beanie to the outfit.”
* “**Add** a tan leather shoulder bag to the outfit.”
* “**Add** a gold pendant necklace to the outfit.”

Avoid mixing actions in one prompt, such as replacing a jacket and adding a bag at the same time.

### 2. Name the region being changed

Be specific about what part of the outfit should change.

| Region to change | Start the prompt with |
| - | - |
| Tops, jackets, coats, hoodies, shirts, and sweaters | `"Substitute the upper body garment with <description>."` |
| Pants, skirts, shorts, and other bottoms | `"Substitute the lower body garment with <description>."` |
| Dresses, jumpsuits, matching sets, or full looks | `"Substitute the outfit with <description>."` |
| Shoes | `"Substitute the footwear with <description>."` |
| Hats | `"Substitute the hat with <description>."` |
| Necklaces | `"Substitute the necklace with <description>."` |
| Accessories to add on top | `"Add <description> to the outfit."` |

### 3. Let the reference image lead

<Note>
  The reference image is the source of truth for the garment. Describe what it actually shows, explicitly — not a new imagined version of it.
</Note>

Good prompts describe the visible item directly:

* “Substitute the upper body garment with **a dark green hooded jacket**.”
* “Substitute the lower body garment with **white tailored trousers**.”
* “Add **a black ribbed beanie with a folded cuff** to the outfit.”

Avoid relying on vague phrases:

* “Use this.”
* “Make it stylish.”
* “Give me the same vibe.”

### 4. Describe visible garment details

VTON works best when the prompt includes concrete fashion details. Describe what can actually be seen.

Useful details include:

* Color
* Fabric or material
* Garment type
* Fit or silhouette
* Length
* Sleeves
* Neckline or collar
* Closures, such as zipper, buttons, snaps, or drawstrings
* Pockets
* Texture
* Pattern
* Visible logo, graphic, or brand text

Examples:

* “Substitute the upper body garment with **a dark green hooded jacket, zipped closed, with large front utility pockets and a small white logo on the left chest**.”
* “Substitute the lower body garment with **oversized burnt orange sherpa fleece trousers with a drawstring waistband**.”
* “Add **a black thick ribbed-knit beanie with a folded cuff and a small white brand label** to the outfit.”

<Warning>
  Do not invent logos, text, or details that are not visible in the reference image.
</Warning>

### 5. Say whether garments are open or closed

For garments with buttons, zippers, or front openings, include how they are worn.

This matters for:

* Jackets
* Coats
* Cardigans
* Blazers
* Vests
* Dress shirts
* Zip hoodies
* Button-up garments

Examples:

* “Substitute the upper body garment with a black blazer, **worn open on top of a white crew-neck t-shirt**.”
* “Substitute the upper body garment with a navy zip-up hoodie, **zipped closed**.”
* “Substitute the outfit with a **closed** two-button black blazer, a black ribbed turtleneck sweater, and white tailored trousers.”

If the garment is open over another visible layer, describe the base layer too.

## Strong prompt examples

* “Substitute the upper body garment with a grey sleeveless crew-neck t-shirt featuring a single chest pocket with a small logo.”
* “Substitute the outfit with a closed two-button black blazer, a black ribbed turtleneck sweater, and white tailored trousers.”
* “Substitute the lower body garment with oversized wide-leg burnt orange sherpa fleece trousers featuring a drawstring waistband.”
* “Substitute the footwear with white low-top leather sneakers with a clean toe box and thin rubber sole.”
* “Add a black thick ribbed-knit beanie with a folded cuff and a small white brand label to the outfit.”

## Common mistakes

**Being too vague:**

* “Make me fashionable.”
* “Use the reference.”
* “Try this look.”

**Requesting unrelated changes:**

* “Change my face.”
* “Make me taller.”
* “Change the background.”

**Inventing details:**

* “Add the \[Brand name] logo,” unless the logo is clearly visible.
* “Make it silk,” if the reference does not show silk.

<Tip>
  The best VTON prompts are short, visual, and specific: one action, one target region, and a faithful description of the visible garment.
</Tip>

## Writing prompts with an AI assistant

If you would rather not write the prompt yourself, a chat assistant such as ChatGPT, Claude, or Gemini can turn a garment photo into a ready-to-use prompt.

<Steps>
  <Step title="Upload the garment image">
    Open the assistant and upload the garment image (a screenshot from a store page works too).
  </Step>

  <Step title="Add a photo of the person (optional)">
    Also upload a photo of the person who will wear it — this helps the assistant name the region correctly (for example, "the upper body garment").
  </Step>

  <Step title="Paste an instruction and copy the result">
    Paste an instruction like the one below, then copy the result into Lucy VTON.

    ```text Prompt to paste wrap theme={null}
    Look at the attached garment image and write a single virtual try-on prompt. Start it with "Substitute the upper body garment with…" (or "Add … to the outfit" for accessories). Describe only what is visible: color, fabric, garment type, fit, length, sleeves, neckline, closures, pockets, texture, pattern, and any visible logo. Do not invent details that are not shown. Keep it to one sentence.
    ```
  </Step>
</Steps>

Always review the result before using it — check that every detail actually appears in the image, and delete anything the assistant guessed.

## Preparing a clean garment image

Lucy VTON works best from a clean garment image: just the item, on a plain background, with no one wearing it. Photos from fashion websites usually show a model, a background, and props instead.

You can create a clean version with an image-generating assistant (for example, ChatGPT, Gemini, or another image tool):

<Steps>
  <Step title="Upload the original photo">
    Add the source photo to the assistant.
  </Step>

  <Step title="Ask the tool to isolate the garment">
    Ask the tool to isolate the garment on a plain background, for example:

    ```text Prompt to paste wrap theme={null}
    Extract just the [garment, e.g. green hooded jacket] from this photo and place it on a plain white background. Keep the garment's exact color, shape, and details. Remove the person, the background, and any props.
    ```
  </Step>

  <Step title="Use the cleaned image in Lucy VTON">
    Use the cleaned image as your reference, paired with a descriptive prompt.
  </Step>
</Steps>

Keep the garment's real color and details — do not let the tool restyle or "improve" the item, because VTON reproduces what the reference shows.


# Non-realtime Models
Source: https://docs.platform.decart.ai/models/video/overview

Edit videos and edit images

Decart offers models for video editing and image editing. Transform existing media with intelligent edits while preserving important details like motion, temporal consistency, identity, and structure.

## Available models

<CardGroup>
  <Card title="Video Editing" href="/models/video/video-editing" icon="pen-to-square">
    Transform and edit existing videos with Lucy 2.5
  </Card>

  <Card title="Image Editing" href="/models/image/image-editing" icon="image">
    Transform and edit existing images with Lucy Image
  </Card>
</CardGroup>

## Quick comparison

| Feature | Video Editing | Image Editing |
| - | - | - |
| **Models** | Lucy 2.5 & Lucy 2.1 (Previous generation) | Lucy Image |
| **Input types** | Video + text prompt, video + reference image, or both | Image + text prompt |
| **Resolution** | 720p | 720p |
| **Best for** | Editing existing videos | Editing existing images |
| **Strengths** | Motion preservation, temporal consistency | Identity preservation, structure retention |

## Model capabilities

### Video Editing (Lucy 2.5)

* **Flexible inputs:** Use a text prompt, a reference image, or both together
* **Reference image mode:** Transform video to match a reference image without needing a prompt
* **Combined mode:** Pair a reference image with a text prompt for maximum control
* **Excels at:** Clothing changes, character/object replacement, style transfers, background replacement
* **Preserves:** Original motion patterns, temporal consistency, scene structure
* **Unlimited duration**
* Best results with 20-40 word prompts focusing on specific changes

### Image Editing (Lucy Image)

* **Excels at:** Clothing changes, character/object replacement
* **Good for:** Color changes, adding accessories, background transformations
* **Preserves:** Core structure, pose, identity
* Best results with 20-30 word prompts focusing on specific changes

## API endpoints

### Video

* **Lucy 2.5** *(Latest)*: [`/v1/jobs/lucy-2.5`](/api-reference/lucy-25) or `/v1/jobs/lucy-latest`
* **Lucy 2.1**: [`/v1/jobs/lucy-2.1`](/api-reference/lucy-21)
* **Lucy VTON 3.6** *(Latest)*: [`/v1/jobs/lucy-vton-3.6`](/api-reference/lucy-vton-36) or `/v1/jobs/lucy-vton-latest`
* **Lucy VTON 3.5**: [`/v1/jobs/lucy-vton-3.5`](/api-reference/lucy-vton-35)

### Image

* **Lucy Image**: [`/v1/generate/lucy-image-2`](/api-reference/lucy-image-2)

## Next steps

<CardGroup>
  <Card title="Go to Platform" href="https://platform.decart.ai/" icon="cube">
    Test all models interactively
  </Card>

  <Card title="API Reference" href="/api-reference/lucy-25" icon="code">
    Complete documentation for all endpoints
  </Card>
</CardGroup>


# Video Editing
Source: https://docs.platform.decart.ai/models/video/video-editing

Learn how to edit and transform existing videos with AI.

Transform and edit existing videos using text prompts, reference images, or both. Upload a video, describe the changes you want, and Lucy 2.5 will modify it while preserving motion and temporal consistency — perfect for style transfers, object modifications, character replacements, and visual transformations.

## Quick start

Here's a simple example using `lucy-latest`, which always targets the newest video editing model (currently Lucy 2.5).

<CodeGroup>
  ```bash Curl theme={null}
  # Submit job
  JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-latest \
    -H "X-API-KEY: $DECART_API_KEY" \
    -F "data=@input-video.mp4" \
    -F "prompt=Change the car to a vintage motorcycle" | jq -r '.job_id')

  # Poll until completed
  while true; do
    STATUS=$(curl -s -H "X-API-KEY: $DECART_API_KEY" \
      https://api.decart.ai/v1/jobs/$JOB_ID | jq -r '.status')
    echo "Status: $STATUS"
    [ "$STATUS" = "completed" ] && break
    [ "$STATUS" = "failed" ] && exit 1
    sleep 2
  done

  # Download result
  curl -H "X-API-KEY: $DECART_API_KEY" \
    https://api.decart.ai/v1/jobs/$JOB_ID/content --output edited-video.mp4
  ```

  ```python Python SDK theme={null}
  import asyncio
  from decart import DecartClient, models

  async def edit_video():
      async with DecartClient(api_key="your-api-key-here") as client:
          with open("input-video.mp4", "rb") as video_file:
              result = await client.queue.submit_and_poll({
                  "model": models.video("lucy-latest"),
                  "prompt": "Change the car to a vintage motorcycle",
                  "data": video_file,
                  "on_status_change": lambda job: print(f"Status: {job.status}"),
              })

          if result.status == "completed":
              with open("edited-video.mp4", "wb") as f:
                  f.write(result.data)

  asyncio.run(edit_video())
  ```

  ```javascript JavaScript SDK theme={null}
  import { createDecartClient, models } from "@decartai/sdk";
  import { readFileSync, writeFileSync } from "fs";

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

  const videoBuffer = readFileSync("input-video.mp4");
  const videoBlob = new Blob([videoBuffer], { type: "video/mp4" });

  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-latest"),
    prompt: "Change the car to a vintage motorcycle",
    data: videoBlob,
    onStatusChange: (job) => console.log(`Status: ${job.status}`),
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("edited-video.mp4", buffer);
  }
  ```

  ```python Python (REST) theme={null}
  import requests
  import os
  import time

  headers = {"X-API-KEY": os.getenv("DECART_API_KEY")}

  # Submit job
  with open("input-video.mp4", "rb") as video:
      response = requests.post(
          "https://api.decart.ai/v1/jobs/lucy-latest",
          headers=headers,
          files={"data": video},
          data={"prompt": "Change the car to a vintage motorcycle"}
      )
  job_id = response.json()["job_id"]

  # Poll until completed
  while True:
      status_response = requests.get(f"https://api.decart.ai/v1/jobs/{job_id}", headers=headers)
      status = status_response.json()["status"]
      print(f"Status: {status}")
      if status == "completed":
          break
      elif status == "failed":
          raise Exception("Job failed")
      time.sleep(2)

  # Download result
  result = requests.get(f"https://api.decart.ai/v1/jobs/{job_id}/content", headers=headers)
  with open("edited-video.mp4", "wb") as f:
      f.write(result.content)
  ```

  ```javascript JavaScript (REST) theme={null}
  const headers = { "X-API-KEY": process.env.DECART_API_KEY };

  // Submit job
  const formData = new FormData();
  formData.append("data", videoFile);
  formData.append("prompt", "Change the car to a vintage motorcycle");

  const submitResponse = await fetch("https://api.decart.ai/v1/jobs/lucy-latest", {
    method: "POST",
    headers,
    body: formData,
  });
  const { job_id } = await submitResponse.json();

  // Poll until completed
  while (true) {
    const statusResponse = await fetch(`https://api.decart.ai/v1/jobs/${job_id}`, { headers });
    const { status } = await statusResponse.json();
    console.log(`Status: ${status}`);
    if (status === "completed") break;
    if (status === "failed") throw new Error("Job failed");
    await new Promise((r) => setTimeout(r, 2000));
  }

  // Download result
  const resultResponse = await fetch(`https://api.decart.ai/v1/jobs/${job_id}/content`, { headers });
  const editedVideo = await resultResponse.blob();
  ```
</CodeGroup>

### Parameters

* `data` (**required**) — Input video file to edit.
* `prompt` (**required**) — Text description of the changes to apply. For Lucy 2.5 and 2.1, send an empty string if you want to use only a reference image.
* `reference_image` (**optional**) — An image to guide the edit. Use this to show the model exactly what you want to add or change (e.g., a specific pair of sunglasses, a logo, or a style reference).
* `resolution` (**optional**) — Output resolution: `720p` (default: `720p`).

<Note>
  You can drive edits with text, a visual reference, or a combination of both.
</Note>

### Video Requirements

* **Format:** MP4 (H.264 or VP8 codec)
* **Aspect Ratio:** 16:9 (landscape) or 9:16 (portrait)
* **Duration:** Unlimited with Lucy 2.5 and Lucy 2.1
* **File Size:** Maximum 200MB
* **Output Resolution:**
  * `720p`: 720×1280 (portrait) or 1280×720 (landscape)

<Note>
  For complete API documentation including response formats and error codes, see the [API Reference](/api-reference/lucy-25).
</Note>

## Available Models and Options

Decart provides different editing models to balance **precision, creativity, and cost** depending on your use case.

We currently offer:

* **Lucy 2.5** *(Recommended)* — our latest and most advanced editing model. Fastest speed, excellent quality, unlimited duration, supports prompt and optional reference image.
* **Lucy 2.1** *(Previous generation)* — earlier editing model. Still available for pinned integrations.

<Warning>
  **Lucy 2.1 is a previous-generation model.** We recommend Lucy 2.5 (`lucy-2.5`, or the `lucy-latest` alias) for all new video editing projects. It is the fastest, supports unlimited duration, and costs the same or less.
</Warning>

### Model Comparison

| Model | Status | Quality | Speed | Reference Image | Duration | Cost | Best For |
| - | - | - | - | - | - | - | - |
| **Lucy 2.5** | Recommended | Excellent | Fastest | ✅ Supported | Unlimited | \$0.04/sec | All video editing use cases (latest) |
| **Lucy 2.1** | Previous generation | Excellent | Fastest | ✅ Supported | Unlimited | \$0.04/sec | Pinned integrations |

## Prompting Guide

Lucy 2.5 responds best when your prompts follow specific patterns for each edit type. Focus only on what needs to change — you don't need to describe the entire scene.

| Edit type | Prompt template |
| - | - |
| **Character transformation** | "Substitute the character in the video with \<description>." |
| **Add** | "Add \<description of object> to \<where to add it>." |
| **Replace** | "Change \<object to change> with \<description of new object>." |
| **Change attribute** | "Change \<object> to \<description of new attribute>." |
| **Style transfer** | "Transform to \<style> with \<specific visual details>." |

### Character Transformation

Swap the person in the video with a different character. When using a reference image, describe the character's appearance in the prompt for best results.

* *"Substitute the character with an older man with pale skin, light blue eyes, a powdered white wig, and a dark formal coat with a white ruffled neckpiece."*
* *"Substitute the character with a young person wearing a pink top with white ribbon ties, loose pink pants, and short brown hair."*

### Adding & Replacing Objects

Add new elements or swap existing ones. Always specify placement for additions.

* *"Add a red conical hat covered in sequins with a white fluffy trim to the person's head."*
* *"Change the person's sweater to a red knit sweater with a white-outlined gold emblem on the chest."*
* *"Replace the car with a futuristic hoverbike, metallic finish."*

### Changing Attributes

Modify a property of an existing object — color, texture, material — without replacing it entirely.

* *"Change the wall's color to light blue, natural consistent paint finish."*
* *"Change the shirt's texture to knitted, woven fabric."*

### Style Transfer

Apply consistent visual styles across all frames.

* *"Transform to anime style with vibrant colors and cel shading."*
* *"Apply film noir aesthetic with high contrast black and white."*

### Prompt Tips

* **Be specific** — "a red knit sweater with a white emblem on the chest" outperforms "a red sweater"
* **Describe the reference image** — when using character transformation, describe what you see in the reference (skin, hair, clothing, features)
* **One edit per prompt** — combining multiple edits can produce unpredictable results
* **Detail improves results** — detailed prompts (20–40 words) describing style, appearance, and context produce significantly better results than short instructions

## Using Reference Images

For more precise edits, **Lucy 2.5** supports an optional `reference_image` parameter. This allows you to provide a visual reference that guides the edit—perfect for when you want to add a specific item (like a particular style of sunglasses) or match a specific look.

<Note>
  Reference images are supported with **Lucy 2.5** (`lucy-2.5`) and the previous-generation **Lucy 2.1** (`lucy-2.1`).
</Note>

With **Lucy 2.5**, you can use a reference image with an empty prompt — the model will transform the video to match the reference image directly:

<CodeGroup>
  ```bash Curl (Reference Image Only) theme={null}
  # Submit job with reference image and empty prompt
  JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-latest \
    -H "X-API-KEY: $DECART_API_KEY" \
    -F "data=@input-video.mp4" \
    -F "prompt=" \
    -F "reference_image=@style-reference.jpg" | jq -r '.job_id')

  # Poll and download as before...
  ```

  ```python Python SDK (Reference Image Only) theme={null}
  import asyncio
  from decart import DecartClient, models

  async def edit_video_with_reference():
      async with DecartClient(api_key="your-api-key-here") as client:
          with open("input-video.mp4", "rb") as video_file:
              with open("style-reference.jpg", "rb") as reference_image:
                  result = await client.queue.submit_and_poll({
                      "model": models.video("lucy-latest"),
                      "prompt": "",
                      "data": video_file,
                      "reference_image": reference_image,
                      "on_status_change": lambda job: print(f"Status: {job.status}"),
                  })

          if result.status == "completed":
              with open("edited-video.mp4", "wb") as f:
                  f.write(result.data)

  asyncio.run(edit_video_with_reference())
  ```

  ```javascript JavaScript SDK (Reference Image Only) theme={null}
  import { createDecartClient, models } from "@decartai/sdk";
  import { readFileSync, writeFileSync } from "fs";

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

  const videoBuffer = readFileSync("input-video.mp4");
  const videoBlob = new Blob([videoBuffer], { type: "video/mp4" });

  const imageBuffer = readFileSync("style-reference.jpg");
  const imageBlob = new Blob([imageBuffer], { type: "image/jpeg" });

  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-latest"),
    prompt: "",
    data: videoBlob,
    reference_image: imageBlob,
    onStatusChange: (job) => console.log(`Status: ${job.status}`),
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("edited-video.mp4", buffer);
  }
  ```
</CodeGroup>

<CodeGroup>
  ```bash Curl theme={null}
  # Submit job with reference image
  JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-latest \
    -H "X-API-KEY: $DECART_API_KEY" \
    -F "data=@input-video.mp4" \
    -F "prompt=Add these sunglasses to her face" \
    -F "reference_image=@sunglasses.jpg" | jq -r '.job_id')

  # Poll and download as before...
  ```

  ```python Python SDK theme={null}
  import asyncio
  from decart import DecartClient, models

  async def edit_video_with_reference():
      async with DecartClient(api_key="your-api-key-here") as client:
          with open("input-video.mp4", "rb") as video_file:
              with open("sunglasses.jpg", "rb") as reference_image:
                  result = await client.queue.submit_and_poll({
                      "model": models.video("lucy-latest"),
                      "prompt": "Add these sunglasses to her face",
                      "data": video_file,
                      "reference_image": reference_image,
                      "on_status_change": lambda job: print(f"Status: {job.status}"),
                  })

          if result.status == "completed":
              with open("edited-video.mp4", "wb") as f:
                  f.write(result.data)

  asyncio.run(edit_video_with_reference())
  ```

  ```javascript JavaScript SDK theme={null}
  import { createDecartClient, models } from "@decartai/sdk";
  import { readFileSync, writeFileSync } from "fs";

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

  const videoBuffer = readFileSync("input-video.mp4");
  const videoBlob = new Blob([videoBuffer], { type: "video/mp4" });

  const imageBuffer = readFileSync("sunglasses.jpg");
  const imageBlob = new Blob([imageBuffer], { type: "image/jpeg" });

  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-latest"),
    prompt: "Add these sunglasses to her face",
    data: videoBlob,
    reference_image: imageBlob,
    onStatusChange: (job) => console.log(`Status: ${job.status}`),
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("edited-video.mp4", buffer);
  }
  ```
</CodeGroup>

## Endpoint and Full API Reference

* **Lucy 2.5** *(Latest)*: [`/v1/jobs/lucy-2.5`](/api-reference/lucy-25) or `/v1/jobs/lucy-latest`
* **Lucy 2.1**: [`/v1/jobs/lucy-2.1`](/api-reference/lucy-21)

## Next steps

Now that you know the basics of video editing, you might want to check out one of these resources next.

<CardGroup>
  <Card icon="cube" title="Edit a video in the Platform" href="https://platform.decart.ai/models/lucy?surface=batch">
    Try out video editing and other models in the interactive platform.
  </Card>

  <Card icon="code" title="Full API reference" href="/api-reference/lucy-25">
    Check out all the options for video editing in the API reference.
  </Card>

  <Card icon="shirt" title="Virtual Try-On" href="/models/realtime/virtual-try-on">
    Dress people in videos with text prompts or garment reference images.
  </Card>
</CardGroup>


# Video Restyling
Source: https://docs.platform.decart.ai/models/video/video-restyling

Learn how to apply new visual styles to entire videos with AI.

With the Decart API, you can restyle entire videos using text prompts. Simply upload a video and describe the style you want to apply, and Lucy Restyle will transform your video while maintaining temporal consistency and motion throughout.

Lucy Restyle excels at applying artistic styles, aesthetic transformations, and visual filters to videos of any length up to 30 minutes. It supports long-form content, making it perfect for restyling full videos from start to finish in a single workflow.

<Note>
  Lucy Restyle supports videos up to 30 minutes in length, making it ideal for long-form content restyling.
</Note>

## Quick start

Here's a simple example using **Lucy Restyle**, our long-form video restyling model.

<CodeGroup>
  ```bash Curl theme={null}
  # Submit job
  JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-restyle-2 \
    -H "X-API-KEY: $DECART_API_KEY" \
    -F "data=@input-video.mp4" \
    -F "prompt=Transform to anime style with vibrant colors and cel shading" | jq -r '.job_id')

  # Poll until completed
  while true; do
    STATUS=$(curl -s -H "X-API-KEY: $DECART_API_KEY" \
      https://api.decart.ai/v1/jobs/$JOB_ID | jq -r '.status')
    echo "Status: $STATUS"
    [ "$STATUS" = "completed" ] && break
    [ "$STATUS" = "failed" ] && exit 1
    sleep 2
  done

  # Download result
  curl -H "X-API-KEY: $DECART_API_KEY" \
    https://api.decart.ai/v1/jobs/$JOB_ID/content --output restyled-video.mp4
  ```

  ```python Python SDK theme={null}
  import asyncio
  from decart import DecartClient, models

  async def restyle_video():
      async with DecartClient(api_key="your-api-key-here") as client:
          with open("input-video.mp4", "rb") as video_file:
              result = await client.queue.submit_and_poll({
                  "model": models.video("lucy-restyle-2"),
                  "prompt": "Transform to anime style with vibrant colors and cel shading",
                  "data": video_file,
                  "on_status_change": lambda job: print(f"Status: {job.status}"),
              })

          if result.status == "completed":
              with open("restyled-video.mp4", "wb") as f:
                  f.write(result.data)

  asyncio.run(restyle_video())
  ```

  ```javascript JavaScript SDK theme={null}
  import { createDecartClient, models } from "@decartai/sdk";
  import { readFileSync, writeFileSync } from "fs";

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

  const videoBuffer = readFileSync("input-video.mp4");
  const videoBlob = new Blob([videoBuffer], { type: "video/mp4" });

  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-restyle-2"),
    prompt: "Transform to anime style with vibrant colors and cel shading",
    data: videoBlob,
    onStatusChange: (job) => console.log(`Status: ${job.status}`),
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("restyled-video.mp4", buffer);
  }
  ```

  ```python Python (REST) theme={null}
  import requests
  import os
  import time

  headers = {"X-API-KEY": os.getenv("DECART_API_KEY")}

  # Submit job
  with open("input-video.mp4", "rb") as video:
      response = requests.post(
          "https://api.decart.ai/v1/jobs/lucy-restyle-2",
          headers=headers,
          files={"data": video},
          data={"prompt": "Transform to anime style with vibrant colors and cel shading"}
      )
  job_id = response.json()["job_id"]

  # Poll until completed
  while True:
      status_response = requests.get(f"https://api.decart.ai/v1/jobs/{job_id}", headers=headers)
      status = status_response.json()["status"]
      print(f"Status: {status}")
      if status == "completed":
          break
      elif status == "failed":
          raise Exception("Job failed")
      time.sleep(2)

  # Download result
  result = requests.get(f"https://api.decart.ai/v1/jobs/{job_id}/content", headers=headers)
  with open("restyled-video.mp4", "wb") as f:
      f.write(result.content)
  ```

  ```javascript JavaScript (REST) theme={null}
  const headers = { "X-API-KEY": process.env.DECART_API_KEY };

  // Submit job
  const formData = new FormData();
  formData.append("data", videoFile);
  formData.append("prompt", "Transform to anime style with vibrant colors and cel shading");

  const submitResponse = await fetch("https://api.decart.ai/v1/jobs/lucy-restyle-2", {
    method: "POST",
    headers,
    body: formData,
  });
  const { job_id } = await submitResponse.json();

  // Poll until completed
  while (true) {
    const statusResponse = await fetch(`https://api.decart.ai/v1/jobs/${job_id}`, { headers });
    const { status } = await statusResponse.json();
    console.log(`Status: ${status}`);
    if (status === "completed") break;
    if (status === "failed") throw new Error("Job failed");
    await new Promise((r) => setTimeout(r, 2000));
  }

  // Download result
  const resultResponse = await fetch(`https://api.decart.ai/v1/jobs/${job_id}/content`, { headers });
  const restyledVideo = await resultResponse.blob();
  ```
</CodeGroup>

### Parameters

* `data` (**required**) — Input video file to restyle.
* `prompt` (**required**) — Text description of the style to apply.
* `resolution` (**optional**) — Output resolution: `720p` (default: `720p`).
* `seed` (**optional**) — Random seed for reproducibility (0-4294967295).
* `enhance_prompt` (**optional**) — Whether to enhance the prompt automatically (default: `true`).

### Video Requirements

* **Format:** MP4, WebM, or QuickTime
* **Duration:** Up to 30 minutes
* **File Size:** Maximum 200MB
* **Output Resolution:**
  * `720p`: 720×1280 (portrait) or 1280×720 (landscape)

<Note>
  For complete API documentation including response formats and error codes, see the [API Reference](/api-reference/lucy-restyle-2).
</Note>

## What Makes Lucy Restyle Unique

Lucy Restyle is specifically designed for **long-form video restyling**. It can process videos up to 30 minutes in length while maintaining consistent style application and temporal coherence throughout.

Key advantages:

* **Long-form support** — Process entire videos, not just short clips
* **Temporal consistency** — Maintains style coherence across the entire video duration
* **Motion preservation** — Preserves original motion patterns while applying new styles
* **Prompt-controlled** — Full control over the style transformation through text descriptions

## Prompt Engineering for Video Restyling

Video restyling prompts should focus on **visual style, aesthetic qualities, and artistic transformations** rather than specific object changes. Your prompts describe how the video should look, not what should change.

Effective restyling prompts are **specific about style** (artistic movements, visual aesthetics), **descriptive about appearance** (colors, textures, lighting), and **clear about the transformation** (what style to apply). Lucy Restyle interprets your style description and applies it consistently across all frames.

**Pro tip:** Reference well-known artistic styles or visual aesthetics for best results. Include details about color palettes, textures, and lighting conditions.

### Example Prompts

**Artistic Styles:**

* "Transform to anime style with vibrant colors and cel shading"
* "Apply impressionist painting style with soft brushstrokes and pastel colors"
* "Convert to film noir aesthetic with high contrast black and white"

**Visual Aesthetics:**

* "Apply warm sunset color grade with orange and pink tones throughout"
* "Transform to cyberpunk style with neon lights and dark urban atmosphere"
* "Convert to vintage 8mm film look with grain and color shifts"

**Artistic Movements:**

* "Apply watercolor painting style with flowing colors and soft edges"
* "Transform to pop art style with bold colors and high contrast"
* "Convert to minimalist aesthetic with clean lines and muted colors"

## Supported Style Types

### ✅ Best Performance

#### 1. Artistic Style Transfer

Lucy Restyle excels at applying consistent artistic styles across entire videos.

* Example: "Transform to anime style with vibrant colors and cel shading"
* Example: "Apply impressionist painting style with soft brushstrokes"
* Example: "Convert to watercolor painting aesthetic with flowing colors"

#### 2. Visual Aesthetic Transformations

Strong results when applying specific visual aesthetics and color grading.

* Example: "Apply warm sunset color grade with orange and pink tones"
* Example: "Transform to cyberpunk style with neon lights and dark atmosphere"
* Example: "Convert to vintage film look with grain and color shifts"

#### 3. Lighting and Atmosphere

Reliable for changing lighting conditions and atmospheric effects.

* Example: "Apply golden hour lighting with warm, soft illumination"
* Example: "Transform to moody, dramatic lighting with high contrast shadows"
* Example: "Convert to bright, airy aesthetic with soft diffused lighting"

### ⚠️ Considerations

#### 4. Complex Scene Transformations

Works well but may require more specific prompts for complex scenes with multiple elements.

* Tip: Be specific about which elements should be transformed and which should remain unchanged
* Tip: Reference specific artistic movements or well-known visual styles for consistency

#### 5. Temporal Consistency

The model maintains temporal consistency, but very rapid style changes may require multiple passes.

* Tip: For best results, apply consistent styles throughout the video duration
* Tip: Gradual style transitions work better than abrupt changes

### Additional Optimization Tips

* **Style specificity**: Reference well-known artistic movements or visual aesthetics for best results
* **Color descriptions**: Include specific color palettes and tones in your prompts
* **Long-form advantage**: Take advantage of the 10-minute limit for full video restyling
* **Consistent prompts**: Use similar style descriptions for related videos to maintain brand consistency

**Bottom line:** Lucy Restyle performs best with detailed style descriptions that reference artistic movements, visual aesthetics, or specific color and lighting conditions. Focus on describing how the video should look rather than what should change.

## Endpoint and Full API Reference

* **Lucy Restyle**: [`/v1/jobs/lucy-restyle-2`](/api-reference/lucy-restyle-2)

## Next steps

Now that you know the basics of video restyling, you might want to check out one of these resources next.

<CardGroup>
  <Card icon="cube" title="Restyle a video in the Platform" href="https://platform.decart.ai/models/lucy-restyle?surface=batch">
    Try out video restyling and other models in the interactive platform.
  </Card>

  <Card icon="code" title="Full API reference" href="/api-reference/lucy-restyle-2">
    Check out all the options for video restyling in the API reference.
  </Card>

  <Card icon="film" title="Video Editing" href="/models/video/video-editing">
    Learn how to edit videos with targeted changes using Lucy.
  </Card>
</CardGroup>


# API Terms of Service
Source: https://docs.platform.decart.ai/resources/api-terms



**Last Updated: July 26, 2026**

These API Service Terms ("API Terms") constitute a legally binding contract between you ("Developer" or "you") and Decart.ai Inc. ("we," "us," "our," and "Decart.ai") and govern your access to, and use of, the Decart.AI Models using our API, and related services made available by Decart.AI (collectively, "Services"). The API Terms, together with any specific terms, the Data Processing Agreement, Order Form, the Acceptable Use Policy, API Documentation and any other documents incorporated by reference set out the parties' respective rights and obligations (collectively the "Agreement").

You may access and use the API and the Services only for business and professional purposes and not for personal, household or other consumer use. By accessing or using the API or Services, creating a developer account, or otherwise using the Decart.ai Models, you agree to be bound by this Agreement. You must be at least 18 years of age to access or use the API. If you are accepting on behalf of a company or other legal entity, and you represent that you have authority to bind it, the definition "Developer" and "you" refer to such entity. If you do not agree, you may not access or use the API or Service, or create a developer account, or allow any of your personnel to do so.

## 1. Definitions

"**API**" means our application programming interface(s), and related tools, documentation, data, technology, code, and other materials that are made available to allow Developers to implement Output or Decart.ai Models within their applications, subject to this Agreement.

"**Authorized Users**" means Developer's employees, independent contractors, or Developer's affiliated company.

"**Account**" means the account created by the Developer to access and use the API.

"**Beta Services**" means any features, endpoints, functionalities, or components that are identified as alpha, beta, preview, early access, or evaluation, or words or phrases with similar meanings, and which are made available to Developer for testing and evaluation purposes prior to general commercial release.

"**Confidential Information**" means any confidential or proprietary information of the disclosing Party (the "Discloser") that is marked as "Confidential" or under the circumstances of disclosure should reasonably be considered confidential or proprietary. Confidential Information includes the Order Form and non-public information regarding features, functionality and performance of the Services. Confidential Information does not include information that (a) is lawfully in or enters the public domain through no fault of or breach by the receiving party (the "Recipient"); (b) the Recipient was lawfully in possession of without any obligation of confidentiality prior to receiving it from the Discloser; (c) the Recipient developed independently and without use of or reference to the Discloser's Confidential Information; or (d) the Recipient receives from a third party without restriction on disclosure and without breach of a nondisclosure obligation.

"**Credits**" means the usage units purchased by Developer that are consumed when Developer uses the Services, as further described in the Fees and Payment Section.

"**Decart.ai Models**" shall mean model weights, algorithms, software, checkpoints, parameters, source code (inference code, evaluation code, fine-tuning code) - that Decart.ai offers for use as part of the Service and are available at: [https://platform.decart.ai/models](https://platform.decart.ai/models)

"**Developer Application**" means Developer's owned (or lawfully licensed) and operated application, web-app, website, mobile app, game, or software, products, or services that interact with or incorporate Decart.ai API. For clarity, the Services are provided solely for use in Developer Applications and may not be sublicensed, resold, or otherwise made available to any third party for their independent use.

"**DPA**" shall mean the data processing agreement available at: [Data Processing Agreement](/resources/dpa)

"**Input**" means the information, data, or content, in any form or medium, that is provided by Developer or its Authorized Users and End Users, directly or indirectly, submit, upload, or otherwise provide to the API and Decart.ai Models.

"**Intellectual Property Rights**" means any and all registered and unregistered rights granted, applied for, or otherwise now or hereafter in existence under or related to any patent, copyright, trademark, trade secret, or other intellectual property rights, in any part of the world.

"**Output**" means data, content, video, or other material generated, returned, or otherwise provided by the Decart.ai Models in response to an Input.

"**Order Form**" means any written or electronic document, agreement, or online form that specifies the Services being provided to Developer, including but not limited to the type of API access, Credits, usage limits, fees, payment terms, and any other commercial terms agreed upon between the parties. Order Forms are incorporated into and form part of this Agreement.

"**Usage Data**" means data and information related to Developer's use of the Services, API, Account, Decart.ai Models, including telemetry data, time stamp, time and date access the Services and duration of use, for the purpose of complying statistical and performance information related to the provision and operation of the Services, for billing purposes, for support services (if applicable). Usage Data is governed by Decart.ai Privacy Policy.

## 2. License and Integration

**2.1** API License. Subject to the terms of this Agreement and Decart.ai's rights (including any limitations arising from applicable Third Party Terms, open-source license terms, or other contractual or regulatory obligations binding on Decart.ai), Decart.ai grants Developer, and Authorized Users, a limited, non-exclusive, non-transferable, non-sublicensable, revocable license, during the Term, to: (i) access and use the API and Decart.ai Models solely to develop integrations within the Developer Application; and (ii) use the libraries, and documentation solely as necessary to integrate with the API.

**2.2** API Documentation. Developer's and Authorized Users' use of the API and Decart.ai Models shall comply with the API documentation, which includes technical specifications, usage guidelines, and other materials provided by Decart.ai ("API Documentation"). The API Documentation forms an integral part of this Agreement and may be updated by Decart.ai from time to time.

**2.3** Developer License. Developer hereby grants Decart.ai a fully paid, royalty-free, perpetual, irrevocable, worldwide, non-exclusive and fully sublicensable right and license to use, distribute, reproduce, modify, adapt, publicly perform, and publicly display Developer's Input and Output for the purpose of operating the Services, improving the products and Services, and developing new products and services. You acknowledge the foregoing means Decart.ai may use Inputs and Outputs to train and improve our artificial intelligence models, algorithms, and related technology, products, and services and may reuse and generate the Input and Output as part of its training data in its sole discretion. Developer assumes sole and exclusive responsibility and liability for ensuring that it and Authorized Users have and maintain during the Term all necessary rights, licenses, and permissions to provide Input to the API and to use Output in connection with its Developer Applications.

**2.4** Reservation of Rights. Except for the licenses expressly granted, each party shall retain all rights, title, and interest in and to any related Intellectual Property Right.

## 3. Developer's Obligations and Restrictions

**3.1** Sole Responsibility. Developer assumes sole and exclusive responsibility and liability for any acts or omissions related to the use or misuse of the API and any Output generated through the Developer Applications, whether by Developer itself or its Authorized Users, or by their end users, customers, or any third parties accessing the API through Developer Application ("End Users"). Without limiting the foregoing, Developer assumes sole and exclusive responsibility and liability for integrating and configuring the API, Services and Decart.ai Models in the Developer Applications (including any combinations with other products, services or software) and implementing appropriate technical and organizational safety measures. The Developer assumes sole and exclusive responsibility and liability for ensuring that the Inputs do not include sensitive data (including health information) and that the Developer, Authorized Users, and End Users comply with the Acceptable Use Policy ("AUP"). To the extent applicable, Developer assumes sole and exclusive responsibility and liability for adding applicable disclosures to End Users regarding data protection practices, notices and obtaining consents to the extent required and regarding the limitations and potential inaccuracy of AI-generated content.

**3.2** Compliance with Terms and Law. Developer must use, and ensure all Authorized Users use, the API and Services only in compliance with this Agreement, the AUP, the API Documentation, and all applicable laws and regulations, including but not limited to laws related to data protection, privacy, intellectual property, export control, consumer protection, and content regulation. Developer assumes sole and exclusive responsibility and liability for ensuring that its Developer Applications comply with all applicable legal requirements in the jurisdictions where Developer and its End Users operate, including by adding AI disclosures as required by applicable laws (including State AI laws and EU AI Act). Developer must not misrepresent the nature, source, or authenticity of Output generated by the API. Without limiting the foregoing, Developer assumes sole and exclusive responsibility and liability for complying with any AI-specific, sector-specific, consumer protection, or platform rules applicable to its use of the Services and Output, including transparency, labelling, logging, documentation, risk management, and human oversight obligations. For clarity, Developer is solely responsible for determining whether Output constitutes a "deep fake" or is otherwise subject to transparency or disclosure requirements under applicable law. Developer shall not and shall ensure that its Authorized Users and End Users do not, remove, obscure, disable or circumvent any watermark, label, provenance information or other machine-readable marker applied by or through the Services.

**3.3** Security and Credential Management. Developer must securely store and protect its API keys, tokens, authentication credentials, and any other access materials provided by Decart.ai. Developer may not share its API credentials with unauthorized parties or allow third parties to access the API using Developer's credentials without Decart.ai's prior written consent. Developer must implement appropriate technical and organizational measures to prevent unauthorized access, use, or disclosure of its Account and licenses provided herein, and shall report to Decart.ai immediately upon becoming aware of any unusual or unauthorized use of the Account or Services.

**3.4** Registration Information. Developer must provide accurate, complete, and current information when registering for API access and must promptly update such information if it changes. Developer represents and warrants that the information provided to Decart.ai is truthful and accurate.

**3.5** Content Moderation. Developer is responsible for implementing appropriate content moderation measures, safety controls, and filtering mechanisms (substantially similar to the AUP) to prevent its Developer Applications from generating, distributing, or facilitating access to harmful, illegal, or misleading content through the API and Decart.ai Models. The Developer, on behalf of itself and its Authorized Users, acknowledges that Decart.ai has no obligation, and it may be impossible, to pre-screen Developer (or End User) Input or Output, although Decart.ai reserves the right in its sole discretion to do so or to enable reporting of such abuse to the extent applicable. Decart.ai also reserves the right to remove any Input or Output from the Services that violate this Agreement, and if required, Decart.ai will report to applicable law enforcement. For the avoidance of doubt, Developer's failure to comply with its content moderation obligations under this Section 3.5 shall constitute a material violation of this Agreement for the purposes of Section 6.2(iii), and Decart.ai reserves the right to suspend or terminate Developer's access to the API in accordance with Section 6.2.

**3.6** Restrictions. Developer may not, and shall ensure its Authorized Users, or End Users, as applicable, do not: (a) reverse engineer, decompile, or disassemble the API or Decart.ai Models unless permitted by mandatory applicable law; (b) circumvent or attempt to circumvent rate limits, quotas, authentication mechanisms, or access controls; (c) sell, sublicense, or otherwise provide the API, Decart.ai Models or Output to third parties without Decart.ai's prior written consent; (d) interfere with, disrupt, or otherwise compromise the security, integrity, or availability of the Services; (e) use the API or Output to generate, disseminate, or otherwise make available illegal content or content that is not compliant with the AUP; (f) allow access to the API, Decart.ai Models or Services from any other source other than as described in the Developer Application, meaning you may not host (or authorize or direct a third party to host) an API endpoint to any Decart.ai Models that allows third parties to integrate or otherwise use the Decart.ai Models in or with their own products or services; and (h) attempt to bypass, disable, interfere with, circumvent or otherwise undermine safety features, usage restrictions, content filters or protective measures implemented in the API, services or Decart.ai Models, including by prompt engineering, automated queries or other techniques.

**3.7** Developer must ensure that its contracts, terms of use and privacy notices with End Users: (a) are consistent with this Agreement and the AUP; (b) clearly state that Decart.ai is not responsible for the Developer Application, any Output, any products or services provided by Developer, or any relationship between Developer and End Users; and (c) effectively disclaim, to the maximum extent permitted by law, any liability of Decart.ai to End Users. Upon Decart.ai's request, Developer will provide Decart.ai with a copy of the then-current End User terms (which may be reasonably redacted for confidential information not relevant to this Agreement).

## 4. Input and Output Data

**4.1** Developer understands and acknowledges that, due to the nature of machine learning, the Output involves inherent risk, including that the Output (i) may not be unique across users, and the Decart.ai Models may generate the same or similar Output for other users, (ii) may be inaccurate, objectionable, inappropriate, or otherwise unsuited to Developer's purpose; and (iii) are dependent on the Input submitted by Developer, End User or Authorized User as applicable. Decart.ai will have no liability whatsoever for any Output or any damages you or any third party incurs or alleges to incur as a result of or relating to any Output or use thereof. Additionally, Developer acknowledges it shall not use or permit the use of any Output to impersonate real persons or falsely attribute Output as originating from real individuals. Developer shall be solely responsible for verifying and evaluating all Output before any use, publication or distribution, such as by using human review. Developer understands and acknowledges that the use of the Services is made solely at Developer's own risk and responsibility.

**4.2** No Confidentiality. Developer acknowledges and agrees that Input and Output are not considered confidential information. Developer must not submit to through the API any Input that contains confidential, proprietary, personal, or sensitive information unless Developer has all necessary rights and accepts the risk of disclosure and to ensure the use as described in this Agreement.

**4.3** Representations. You represent and warrant that you have sufficient rights in the Input to submit it to the Services. This means that if you upload a photograph, image, video, or likeness of any person to the Services, you represent and warrant that you have obtained any and all required permissions or consent necessary to submit such person's likeness to the Services, in compliance with all applicable laws and regulations, including but not limited to laws related to data protection, privacy, intellectual property, export control, consumer protection, and content regulation.

## 5. Fees and Payment

**5.1** Credit-Based Usage. The Services operate on a credit-based usage model. Developer must purchase Credits in advance and Credits are consumed when Developer uses the API, based on the type of video or image generated and taking into account factors such as duration, quality, and resolution, as detailed on our pricing page at [https://platform.decart.ai/pricing](https://platform.decart.ai/pricing) or in your Order Form.

**5.2** Purchase and Allocation of Credits. Credits must be purchased in advance through Decart.ai's designated payment channels. Upon receipt of payment, Credits will be allocated to the Developer's Account. Developer may monitor Credit usage and balance through the Account. All Credit purchases are final, non-refundable, and non-transferable, except as required by applicable law. Credits do not entitle the Developer to any particular feature, functionality, or version of the Services.

**5.3** Credit Validity and Expiration. Credits are valid for twelve (12) months, or for the period described in the applicable Order Form. Any unused Credits after this period will automatically expire without refund or compensation.

**5.4** Exceeding Available Credits. If Developer's available Credits are exhausted, access to the API will be suspended until additional Credits are purchased. Developer assumes sole and exclusive responsibility and liability for monitoring its Credit balance and ensuring sufficient Credits are available for continued use of the API.

**5.5** Pricing and Changes. Decart.ai may update Credit pricing, consumption rates, or Credit packages at any time, with or without notice. Any such changes will apply only to Credits purchased after the effective date of such change and will not affect Credits already purchased by Developer.

**5.6** Payment Terms. All payment-related information is available on our pricing page [https://platform.decart.ai/pricing](https://platform.decart.ai/pricing). You must review this information before making any purchase. Decart.ai do not implement automatic renewals for any packages or subscriptions - all Credit purchases must be made manually by you when needed.

**5.7** Taxes. All fees and Credit purchases are exclusive of applicable taxes, duties, or levies, which Developer is responsible for paying in accordance with applicable law.

## 6. Termination

**6.1** Term. This Agreement commences on the date Developer first accesses or uses the API and will remain in effect until terminated in accordance with this Section 6 ("Term").

**6.2** Termination by Decart.ai. Decart.ai may suspend or terminate Developer's access to the API, in whole or in part, at any time and in its sole discretion, by providing no less than 30 days' notice to Developer (including via email or through the Developer's account dashboard). Without limiting the foregoing, Decart.ai may immediately suspend or terminate access: (i) to prevent or mitigate a security risk, operational risk, or other credible risk of harm or liability to Decart.ai, the API, or any third party; (ii) if required to do so by applicable law, regulation, or governmental authority; (iii) in the event of repeated or material violations of this Agreement; or (iv) if Developer institutes litigation or other proceedings against Decart.ai or any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Materials or Output, or any portion of any of the foregoing, infringes intellectual property or other rights owned or licensable by Developer, in which case any licenses granted to Developer under this Agreement shall terminate as of the date such litigation or claim is filed or instituted.

**6.3** Termination by Developer. Developer may terminate this Agreement at any time, for any reason, by ceasing all use of the API and deleting its account (if applicable).

**6.4** Effect of Termination. Upon termination of this Agreement for any reason: (i) all rights and licenses granted to Developer under this Agreement will immediately cease; (ii) Developer must stop making API calls and promptly delete all API keys, credentials, and related integration materials provided by Decart.ai; (iii) Developer may retain and continue to use any Output generated prior to termination, subject to this Agreement and applicable law; (iv) Developer remains responsible for any obligations accrued prior to termination, including payment obligations; (v) Decart.ai's license to use Input and Output shall survive termination; and (vi) Developer assumes sole and exclusive responsibility and liability for downloading and securing the Output prior to the effective date of termination, as Decart.ai makes no commitment to store or maintain such Output following termination, except as required under applicable law.

**6.5** Survival. Sections 3.1 (Sole Responsibility), 9 (Disclaimer of Warranties), 10 (Limitation of Liability), and 13 (Governing Law and Jurisdiction) shall survive termination of this Agreement.

## 7. Support

Decart.ai will use commercially reasonable efforts to maintain the availability of the API and to provide Developer with technical support for questions or issues regarding the API during Decart.ai's normal business hours and through its designated support channels. Decart.ai does not guarantee uninterrupted or error-free operation of the API and shall not be responsible for providing support directly to End Users of Developer Applications.

## 8. Confidentiality; DPA; Intellectual Property

**8.1** Privacy. If the Input includes personal data, it will be processed subject to the DPA, Decart.ai shall collect, process and use such personal data as the "processor" or "service provider" as applicable.

**8.2** Intellectual Property. As between the parties, Decart.ai owns and retains all right, title and interest in and to the Services and all Intellectual Property Rights therein. Developer retains ownership of Input and Output.

**8.3** Feedback. Decart.ai may use and exploit, without any payment or attribution obligation of any kind, any comments, feedback, suggestions, or ideas ("Feedback") Developer, Authorized User, End User or any of its personnel, employees, agents, or subcontractors provides in connection with the Agreement or the Services. To the maximum extent permitted by applicable law, Developer waives any moral and similar rights relating to Feedback that Developer may have under any applicable law.

**8.4** Open Source. The Decart.ai Models may include third party open source software that is subject to third party terms and conditions, ("Third Party Terms"). If there is a conflict between any Third Party Terms and the terms of this Agreement, then the Third Party Terms shall prevail but solely in connection with the related third party open source software.

**8.5** Confidentiality. Each party will: (a) hold in strict confidence all Confidential Information of the other party, using at least the same degree of care to protect the Discloser's Confidential Information as it uses to protect its own Confidential Information of like nature, but at least reasonable care; (b) use such Confidential Information only to exercise its rights and perform its obligations and exercise its rights under the Agreement; and (c) not transfer or disclose such Confidential Information to any individual or entity except to the directors, officers, employees, agents, contractors, accountants, auditors, or legal and financial advisors of such party who need to know such Confidential Information and who are under confidentiality obligations substantially similar to those set forth hereunder; provided, that the handling and treatment of Confidential Information in accordance with the Agreement by any such individual or entity will be such party's full responsibility. A Recipient may disclose the Discloser's Confidential Information to the extent required by law provided that the Recipient (i) notifies the Discloser in writing prior to disclosure of the information so that the Discloser has a reasonable opportunity to obtain a protective order; (ii) assists the Discloser, at the Discloser's expense, in any attempt to limit or prevent the disclosure of the Confidential Information; and (iii) discloses only the minimum Confidential Information actually required to be disclosed. Neither party will disclose the existence or terms and conditions of the Agreement to any third party.

## 9. Disclaimer of Warranties

THE API, SERVICES, DECART.AI MODELS AND OUTPUT ARE PROVIDED "AS IS" AND "AS AVAILABLE." TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, DECART.AI DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND ANY WARRANTIES ARISING FROM COURSE OF DEALING OR USAGE OF TRADE. DECART.AI DOES NOT WARRANT THAT THE API OR SERVICES WILL BE UNINTERRUPTED, ERROR-FREE, OR COMPLETELY SECURE.

## 10. Limitation of Liability

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, DECART.AI SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, PUNITIVE, OR EXEMPLARY DAMAGES, INCLUDING BUT NOT LIMITED TO DAMAGES FOR LOSS OF PROFITS, REVENUES, DATA, GOODWILL, OR OTHER INTANGIBLE LOSSES, ARISING OUT OF OR RELATED TO DEVELOPER'S USE OF THE API, SERVICES, DECART.AI MODELS OR OUTPUT, REGARDLESS OF THE THEORY OF LIABILITY AND EVEN IF DECART.AI HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT SHALL DECART.AI'S TOTAL LIABILITY EXCEED THE AMOUNTS PAID BY DEVELOPER TO DECART.AI FOR THE API IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM.

NOTWITHSTANDING ANYTHING TO THE CONTRARY, DECART.AI PROVIDES THE BETA SERVICES "AS IS" AND "AS AVAILABLE", WITHOUT ANY WARRANTIES OR REPRESENTATIONS OF ANY KIND, WHETHER EXPRESS OR IMPLIED. TO THE MAXIMUM EXTENT PERMITTED BY LAW, DECART.AI DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. DEVELOPER ASSUMES ALL RISKS AND COSTS ASSOCIATED WITH USING THE BETA SERVICES. DECART.AI'S OBLIGATIONS TO INDEMNIFY, DEFEND, OR HOLD HARMLESS UNDER THIS AGREEMENT DO NOT APPLY TO BETA SERVICES. THE LIABILITY CAP FOR BETA SERVICES IS \$0 (ZERO DOLLARS).

## 11. Indemnification

**11.1** Developer's Indemnity to Decart.ai. Developer agrees to defend, indemnify, and hold harmless Decart.ai, its affiliates, and each of their respective directors, officers, employees, agents, and representatives (collectively, the "Decart.ai Indemnified Parties") from and against any and all third-party claims, demands, actions, damages, losses, liabilities, judgments, costs, and expenses (including reasonable attorneys' fees) arising out of or in connection with: (i) Developer Application, products, or services that integrate or interact with the API; (ii) any data, content, include Inputs, or Outputs, or materials Developer, Authorized Users or the End Users input, upload, or otherwise provide through or in connection with the API; (iii) Developer's use of the API, Documentation, or any other Decart.ai Models in violation of this Agreement, applicable laws, or third-party rights; (iv) any combination of the API with products, services, or software not provided by Decart.ai; (v) any claim, demand, action or proceeding brought by or on behalf of any natural person under any applicable product‑liability law, to the extent such claim arises out of or relates to any Developer Application or any products or services provided by or on behalf of Developer that use or integrate the API, Services, Decart.ai Models, Input or Output; or (vi) any breach or alleged breach by you of this Agreement. Such indemnified matters include, without limitation, any governmental or regulatory investigations, proceedings, fines or penalties arising out of or relating to Developer's, Authorized Users' or any End User's use of the Services, Input or Output, including any alleged non‑compliance with AI‑specific, data‑protection, consumer‑protection or platform laws, the AUP, or any applicable transparency or labelling obligations.

**11.2** Decart.ai may, at its option, participate in the defense and settlement of any such claim with its own counsel and at its own expense. You shall not settle any claim without Decart.ai's prior written consent if the settlement requires Decart.ai to take or refrain from taking any action, admit liability, or incur any obligation.

## 12. Changes to These API Terms

**12.1** Modifications. Decart.ai may update or modify this Agreement from time to time. Material changes will be communicated through Developer's account dashboard, email notification, or posting on the Decart.ai website. Developer's continued use of the API after any changes constitutes acceptance of the revised API Terms. If Developer does not agree to the changes, it must discontinue use of the API.

**12.2** Modifications to API. Decart.ai reserves the right, in its sole discretion, to modify, update, enhance, or discontinue the API at any time, including, without limitation, its level of access, content, functionality, performance specifications, or availability. While Decart.ai will endeavor to provide reasonable notice of material changes to the API, you acknowledge that some changes may be implemented immediately without prior notice, particularly those related to security, legal compliance, or system stability. Developer is responsible for regularly reviewing the API Documentation and implementing necessary updates to ensure continued compatibility and functionality of its Developer Applications. Decart.ai will have no liability whatsoever to Developer or any third party for any modification, suspension or discontinuation of the API or any part thereof, including any resulting loss of data, functionality, revenue or goodwill.

## 13. Dispute Resolution

**13.1** Mandatory Informal Dispute Resolution. For any dispute or claim between the parties arising out of or relating to this Agreement or the Services, including any privacy or data security claims, (collectively, "Disputes", and each a "Dispute"), Developer and Decart.ai agree to attempt to first resolve the Dispute informally. If Developer and Decart.ai cannot reach an agreement to resolve the Dispute within 30 days after Developer or Decart.ai receives notice of the Dispute, then either party may submit the Dispute to binding arbitration as set forth below. The statute of limitations and any filing fee deadlines shall be tolled for 30 days from the date that either Developer or Decart.ai first send the applicable notice so that the parties can engage in this informal dispute-resolution process.

**13.2** Mandatory Arbitration. Except for any disputes exclusively related to the intellectual property or Intellectual Property Rights of Developer or Decart.ai, including any disputes in which Developer or Decart.ai seek injunctive or other equitable relief for the alleged unlawful use of Developer's or Decart.ai' intellectual property or other infringement of Developer's or Decart.ai' Intellectual Property Rights, all Disputes that are not resolved in accordance with Section 13.1 will be resolved by a neutral arbitrator through final and binding arbitration instead of in a court by a judge or jury. The arbitration shall be administered by the American Arbitration Association ("AAA"), [https://www.adr.org/](https://www.adr.org/) pursuant to the then-current version of the AAA's Commercial Arbitration Rules and Mediation Procedures. The arbitrator will have the authority to grant any remedy or relief that would otherwise be available in court. The remedies and reliefs rendered by the arbitrator may be confirmed and enforced in any court having jurisdiction. Unless Developer and Decart.ai agree otherwise, any decision or award will include a written statement stating the decision of each claim and the basis for any award, including the arbitrator's essential factual and legal findings and conclusions. The parties will cooperate to seek from the arbitrator protection for any confidential, proprietary, trade secret, or otherwise sensitive information, documents, testimony, and other materials that might be exchanged or the subject of discovery in the arbitration.

## 14. Governing Law

The Agreement shall be governed by the laws of the State of New York without regard to its conflict of laws provisions. Subject to Section 13, any actions and proceedings not subject to mandatory arbitration under this Agreement shall be brought exclusively in the state or federal courts in New York County, New York.

## 15. General Provisions

**15.1** Entire Agreement. This Agreement, together with the API Documentation and any referenced policies, constitute the entire agreement between Developer and Decart.ai regarding the API. In the event of any conflict or inconsistency between the components of the Agreement, the following order of precedence will apply (in descending order): (a) any Order Form (solely with respect to commercial terms); (b) these API Terms; (c) the DPA; (d) the AUP and any other referenced policies; and (e) the API Documentation.

**15.2** Independent Contractors. The parties are independent contractors. Nothing in this Agreement shall be construed to create a partnership, joint venture, agency, or employment relationship between the parties. Neither party has authority to bind the other.

**15.3** Severability. If any provision of this Agreement is found to be unenforceable, the remaining provisions shall remain in full force and effect.

**15.4** No Waiver. Decart.ai's failure to enforce any provision of this Agreement shall not constitute a waiver of such provision or any other provision.

**15.5** Assignment. Developer may not assign this Agreement without Decart.ai's prior written consent. Decart.ai may assign this Agreement without restriction.

**15.6** No Third‑Party Beneficiaries. Except for the Decart.ai Indemnified Parties, who are express third‑party beneficiaries of Section 11, this Agreement is for the sole benefit of the parties and their permitted successors and assigns, and nothing herein is intended to confer any rights or remedies on any other person or entity.

**15.7** Force Majeure. Decart.ai will have no liability whatsoever for any delay or failure to perform any obligation under this Agreement (except for payment obligations) to the extent caused by events beyond its reasonable control, including acts of God, natural disasters, war, terrorism, riots, labor disputes, internet or telecommunications failures, denial‑of‑service attacks, failures of third‑party systems or services, governmental actions, or power outages.

## 16. Contact Information

If you have questions about this Agreement, please contact us at [compliance@decart.ai](mailto:compliance@decart.ai).


# Acceptable Use Policy
Source: https://docs.platform.decart.ai/resources/aup

("AUP" or "Policy")

**Last Updated: February 12th, 2026**

## Purpose and Scope

Decart.ai Inc. ("**Decart**" or "**we**", "**us**", "**ours**") is committed to promote safe and fair use of its tools, apps, platforms, offers, features, models, model weights, and API (collectively "**Offers**"). This AUP governs the use of all Offers provided by Decart. By accessing or using the Offers, you agree to this AUP in addition to any applicable license, terms of service, and any requirements and regulations under applicable laws and regulations. The AUP is designed to ensure a safe and responsible online environment, to protect individuals and users right, to uphold applicable legal obligations, including without limitations the EU Digital Service Act ("**DSA**"), the EU AI Act ("**AIA**"), Digital Millennium Copyright Act ("**DMCA**") and any other applicable regulatory requirements. We take our ethical responsibilities very seriously and have implemented robust safeguards to enhance our safety standards.

## Applicability

This AUP applies to business, users, consumers, developers, integrators, resellers, authorities, individuals, organizations (all collectively hereinunder "**you**", "**your**") making use of the Offers, whether free, paid or other type of usage, for any purpose. Violations may result in warnings, suspension, termination, model, key revocation, legal action, and reporting to authorities. You may be liable for damages and costs.

If you redistribute models, code, or products implementing Decart models or API (including under the community license or open source, to the extent applicable): Include this AUP (or materially equivalent terms) and any license files; prevent use in prohibited contexts where reasonably possible (e.g., usage warnings, filters, or gating); and clearly label modified versions and do not misrepresent them as official Decart releases subject to the attribution clauses applicable to the license terms governing your use of the Offers.

## Prohibited Uses & Activities

You may not use the Offers:

* In violation of the law, regulations, or other party's right, or for any illegal activity, violation of court orders, evasion of sanctions or export controls.

* In a manner that infringes, misappropriates, or violates the intellectual property rights or trade secrets of a third party.

* In a manner that contributes, endorses, or promotes, illegal content (including as such term is defined under DSA and applicable laws) including, without limitations, content that:

  * Incites, facilitates, or promotes terrorism or violent extremism, or that provides material support for organizations or individuals associated with terrorism, violent extremism, or hateful behavior
  * Depicts, describes, promotes, or facilitates sexual abuse, suggestive content involving minors, sexual violence, non-consensual intimate imagery, or human trafficking
  * Hate speech, bullying, discrimination, or content that promotes discriminatory practices against individuals or groups on the basis of one or more protected characteristics, such as race, ethnicity, religion, national origin, gender, sexual orientation, or any other identifying trait
  * Content that facilitates, incites or threatens violence,
  * Creates instructions to harm self or others,
  * Infringes intellectual property rights

  The aforesaid shall include content provided as inputs and generated as outputs or results of the Offers.

* To collect, process, disclose, generate, or infer private or sensitive information about individuals, including information about individuals' identity, health, or demographic information, unless you have obtained the right to do so in accordance with applicable law.

* To create, generate, or facilitate the creation of malicious code, malware, computer viruses or do anything else that could disable, overburden, interfere with or impair the proper working, integrity, operation or appearance of a website or computer system. Including by engaging in actions that circumvent or remove usage restrictions or other safety measures.

* To deceit or manipulate by creating deepfakes, media that impersonate a real person without clear, conspicuous disclosure and verifiable consent from the person (or their authorized agent), create, including through prompts and outputs or results of the Offers, misinformation, spam, or content presented as authentic news, evidence, or reportage among others. This provision includes generating or facilitating false online engagement, including fake reviews and other means of fake online engagement through use of the Offers, including by outputs.

* For military, warfare, nuclear industries or applications, espionage, use for materials or activities that are subject to the International Traffic Arms Regulations (ITAR) maintained by the United States Department of State or to the U.S. Biological Weapons Anti-Terrorism Act of 1989 or the Chemical Weapons Convention Implementation Act of 1997.

## Principles to Prevent Child Sexual Abuse

We have made efforts to prevent misuse of the generative AI technology for sexual harms against children, therefore we prohibit harm or exploitation against children:

* Maintain model and platform safety by continuing to understand and respond to child safety risks, if we receive a report regarding misuse of the Offers or Content containing child sexual abuse material ("**CSAM**") or child sexual exploitation material ("**CSEM**") we will remove such content and if required by law, report to the authorities.

* We urge you to report CSAM and CSEM Content

* Users are strictly prohibited from using our Offers to:
  * Create, distribute, or promote CSAM or CSEM, including AI-generated CSAM and CSEM
  * Facilitate trafficking, sextortion, or any other form of exploitation of a minor.
  * Facilitate grooming of a minor.
  * Facilitate child abuse in any form, including instructions about how to conceal abuse.
  * Promote or facilitate pedophilic relationships.
  * Fetishize or sexualize minors in any way.

* By defining specific training data and model development policies, we make best efforts to ensure training data does not contain CSAM or CSEM, if detected it is immediately removed, we expect you to act in the same ethics and responsibilities.

* Any CSAM solicitation reported will be treated seriously – we reserve the right to terminate your use of the Offers and the right to report to the appropriate authorities upon becoming aware if such solicitation.

## Specific AIA Prohibitions

The following uses and activities are strictly prohibited:

* Using the Offers for medical diagnosis, treatment, autonomous weapons, surveillance, or any use where failure could cause death, severe injury, or significant property or environmental damage.

* Engage in, promote, incite, facilitate, or assist in the planning or development of activities that present a risk of death or bodily harm to individuals.

* Untargeted scraping of facial images or real-time remote biometric identification in publicly accessible spaces for law enforcement.

* Evaluating or classifying people based on their social behavior, personal characteristics, or the use of social scoring leading to detrimental or unfavorable treatment

* Inferring emotions of individuals in areas of workplace and education institutions, except where strictly for duly authorised medical or safety reasons.

* Making risk assessments of individuals in order to assess or predict the risk of committing a criminal offence, based solely on the profiling or personality traits and characteristics.

* Exploiting the Offers to deploy subliminal, manipulative or deceptive techniques with the objective of materially distorting the behaviour of individuals or a group of individuals by appreciably impairing their ability to make an informed decision.

The following high-risk uses and activities are prohibited unless otherwise agreed between Decart and you, and only where you can demonstrate full compliance with applicable law:

* Using the Offers to compromise the privacy of others, including the use for biometric categorization, emotion recognition and as a biometric identification system.

* Determining access and admission, evaluating learning outcomes or monitoring and detecting prohibited behavior during tests.

* Making sensitive decisions in the context of employment including the recruitment and selection of individuals and any other decisions affecting terms of work-related relationships such as promotion, termination or work-allocation.

* Making sensitive decisions impacting an individual's enjoyment of essential public and private services and benefits, such as eligibility for public assistance, creditworthiness assessments or assessments concerning the pricing of life and health insurance.

* Using the Offers for law enforcement purposes, as part of critical infrastructure, for migration, asylum and border control management or for the administration of justice and democratic processes.

## Transparency and Disclosure

When using the Decart model:

* You shall disclose content that has been generated or manipulated by AI, as required by law.

* You shall disclose content that constitutes a deepfake - i.e. AI-generated or AI-manipulated image, audio or video content that appreciably resembles real persons, objects, places, entities or events and would falsely appear authentic or truthful - as generated or manipulated by AI, as required by law.

* You shall disclose text which is published with the purpose of informing the public on matters of public interest (e.g. political, social, economic, health, or safety issues) that has been generated or manipulated by AI, as required by law.

* Where the output is marked in a machine-readable format (including watermarks or metadata), you shall not remove, obfuscate, alter, or interfere with such marks unless.

* Maintain internal processes to identify when your use of the Decart model triggers disclosure obligations and to apply appropriate labelling consistently.

* You shall implement content moderation appropriate to your product and audience, including reporting mechanism for prohibited content, human review for edge cases, and age gates where appropriate

* If you distribute outputs, preserve metadata where technically feasible and legally permissible and ensure that downstream distribution channels do not strip such metadata by default.

## Safety and Responsible AI Practices

If we detect that you have violated this AUP, we reserve the right to throttle, suspend, or terminate your use of the Offers, remove any content you publish and to the extent applicable, report to authorities and legal enforcements.

## Reporting and Appeals

* Report suspected violations or safety issues to: [security@decart.ai](mailto:security@decart.ai) please include relevant ID, timestamps, and sample requests, responses or any additional information that is needed for us to manage this issue.

* Content moderation, if you are not able to report directly from the social feed, image, video, output or app, please submit a report to [dsa@decart.ai](mailto:dsa@decart.ai). Decart reserves the right to remove any infringing and misleading content or terminate the use or account of any user using the Offers in breach of applicable laws and this AUP.

* Copyright Infringement and Intellectual Property Infringement shall be reported separately as stated herein below.

* Authority and Government Reporting shall be submitted here: [security@decart.ai](mailto:security@decart.ai)

* Appeals If we believe there has been a policy violation, we may remove the content, warn, suspend or terminate the specific user account. If you believe we made a mistake, please submit an appeal at [appeal@decart.ai](mailto:appeal@decart.ai) specifying the reason you are appealing and adding supporting documentation and evidence.

## Copyright Reporting Specifications

1. **Removal of Content.** Decart respects the legitimate rights of copyright owners, and we will respond to clear notices of alleged copyright infringement. Pursuant to the Digital Millennium Copyright Act ("**DMCA**"), we have designated a Copyright Agent (as specified below) to receive notifications of claimed copyright infringement in connection with the Offers. Please be advised that we enforce a policy that provides for the termination of inappropriate circumstances of users who are repeat infringers. If you believe that your work has been copied in a way that constitutes copyright infringement, please provide the Copyright Agent with the following information in accordance with the DMCA:
   1. An electronic or physical signature of the person authorized to act on behalf of the owner of the copyright.
   2. A description of the copyrighted work you claim has been infringed.
   3. A description of where the material that you claim is infringing is located on the Platform, with enough detail that we may find it. Providing URLs or images in the body of an email is the best way to help us locate content quickly.
   4. Your address, telephone number, and email address;
   5. A statement by you that you have a good faith belief that the disputed use is not authorized by the copyright owner, its agent, or the law.
   6. A statement by you, made under penalty of perjury, that the above information in your notice is accurate and that you are the copyright owner or authorized to act on the copyright owner's behalf.

2. **Counter-Notification.** If you believe that the material you posted was removed from the Platform by mistake and that you have the right to post the material, you may elect to send us a counter-notification. To be effective the counter-notification must be a written communication provided to our Copyright Agent that includes substantially the following (please consult your legal counsel or see the DMCA to confirm these requirements):
   1. Your physical or electronic signature.
   2. Identification of the material that has been removed or to which access has been disabled and the location at which the material appeared before it was removed or access to it was disabled. Providing URLs or images in the body of an email is the best way to help us locate content quickly.
   3. A statement under penalty of perjury that you have a good faith belief that the material was removed or disabled as a result of a mistake or misidentification of the material to be removed or disabled.
   4. Your name, address, and telephone number, and a statement that you consent to the jurisdiction of the Federal District Court for the judicial district in which the address is located, or if your address is outside of the United States, for any judicial district in which the Platform may be found or accessed, and that you will accept service of process from the person who provided notification of infringement or an agent of such person.

3. **Misrepresentations.** Please note that under the DMCA (at 17 U.S.C. Section 512(f)) any person who knowingly materially misrepresents that material or activity is infringing or was removed or disabled by mistake or misidentification may be subject to liability.

4. **Copyright Agent.** Our agent for notice of claims of copyright infringement ("**Copyright Agent**") can be reached as follows: Copyright Compliance Department Email: [info@decart.ai](mailto:info@decart.ai). Address: 1007 North Orange Street, 10th Floor; Wilmington, DE 19801, USA.

## Changes

We reserve the right to change and update this AUP, the effective date shall be stated above under the "Last Update" publication date. Your use of the Offers is subject to this AUP. If material prohibitions are made, we will provide notice through accounts, website or apps, solely to the extent applicable, otherwise, any changes are enforceable from the date published herein.


# Data Processing Agreement
Source: https://docs.platform.decart.ai/resources/dpa



**Last Updated: May 28, 2026**

This Data Processing Agreement ("DPA") forms part of and is governed by the [API Terms of Services](/resources/api-terms) ("Agreement") executed by and between Decart.ai Inc. ("Decart.ai") and the Developer, as such terms are defined in the Agreement. All capitalized terms not defined herein shall have the meaning set forth in the Agreement.

This DPA is effective as of the date on which the Developer first accesses Service, Account or uses the API or Decart.ai Models ("Effective Date"). The term of this DPA coincides with the term of the Agreement and terminates upon expiration or earlier termination (as set forth in Section 6 of the Agreement), or, if later, on the date when Decart.ai ceases all Processing of Developer Data.

WHEREAS, Decart.ai provides Developer with the Services as defined under the Agreement; and

WHEREAS, as part of the Services Decart.ai will Process Developer Data, which includes Personal Data (as defined below) on behalf of the Developer, in accordance with the terms of this DPA and all applicable Data Protection Laws.

## 1. Definitions

"**Adequate Country**" is a country that at the time of the provision of the relevant Services, has been recognized as providing adequate protection by the European Commission based on Art. 45 GDPR.

The terms "**Business**", "**Business Purpose**", "**Consumer**", "**Controller**", "**Database Owner**", "**Personal Data Breach**", "**Processing**" (and "**Process**"), "**Processor**", "**Holder**", "**Service Provider**", "**Sale**" "**Sell**" and "**Share**", "**Special Categories of Personal Data**", "**Sensitive Data**" and "**Supervisory Authority**", shall all have the same meanings as ascribed to them under the applicable Data Protection Laws.

"**Data Protection Law**" means any and all applicable privacy and data protection laws and regulations (including, where applicable, EU Data Protection Law, UK Data Protection Laws, Swiss Data Protection Laws, Israeli Data Protection Law and the U.S. Data Protection Laws) as may be amended or superseded from time to time.

"**Data Subject**" means an identified or identifiable natural person.

"**Data Privacy Framework**" or "**DPF**" means the EU-U.S. Data Privacy Framework, the UK Extension to the EU-U.S. Data Privacy Framework and the Swiss-U.S. Data Privacy Framework self-certification programs (as applicable) operated by the U.S. Department of Commerce; as may be amended, superseded, or replaced.

"**Developer Data**" means any Input and Output (as defined in the Agreement) containing Personal Data, including, to the extent applicable, End User Personal Data, Processed by Decart.ai in the course of providing the Services, all as detailed in Annex I attached herein.

"**DPF Principles**" means the Principles and Supplemental Principles available at: [https://www.dataprivacyframework.gov/program-articles/Participation-Requirements-Data-Privacy-Framework-(DPF)-Principles](https://www.dataprivacyframework.gov/program-articles/Participation-Requirements-Data-Privacy-Framework-\(DPF\)-Principles); as may be amended, superseded or replaced.

"**EEA**" means the European Economic Area.

"**European Data Protection Law**" means, collectively, the laws and regulations of the European Union, the EEA, their member states, and the United Kingdom, applicable to the Processing of Personal Data, including (where applicable): (i) "EU Data Protection Laws" - EU General Data Protection Regulation (Regulation 2016/679) ("EU GDPR"); Regulation 2018/1725; and the e-Privacy Directive (Directive 2002/58/EC), as amended (e-Privacy Law); (ii) "UK Data Protection Laws" - the Data Protection Act 2018 (DPA 2018), as amended, and EU GDPR as incorporated into UK law as amended ("UK GDPR" and collectively with the EU GDPR shall be referred to herein as the "GDPR"); (iii) "Swiss Data Protection Laws" or "FADP" - the Swiss Federal Data Protection Act (dated June 19, 1992, as of March 1, 2019) ("FDPA") and the Ordinance on the Federal Act on Data Protection ("FODP"); (iv) any national data protection laws made under, pursuant to, replacing or succeeding the EU GDPR or the e-Privacy Law; (v) any amendment or legislation replacing or updating any of the foregoing; and (vi) any judicial or administrative interpretation of any of the above, including any binding judicial or administrative interpretation of any of the above, or approved certification mechanisms issued by any relevant Supervisory Authority.

"**Instructions**" means the written, documented instructions provided by the Developer to Decart.ai directing Decart.ai to perform a specific or general action with regard to Developer Data.

"**Israeli Data Protection Laws**" means, collectively, the: (i) Israeli Protection of Privacy Law, 5741-1981 (as amended under Amendment 13); (ii) the regulations promulgated pursuant thereto, including the Israeli Protection of Privacy (Data Security) Regulations, 5777-2017 and the Israeli Protection of Privacy (Transfer of Data to Databases Abroad) Regulations, 5761-2001; (iii) any amendments or legislation replacing or updating any of the foregoing; and (iv) any judicial or administrative interpretation of any of the above, including any binding guidance, guidelines, codes of practice, approved codes of conduct or certification mechanisms approved by the Israeli Privacy Protection Authority.

"**Personal Data**" means any information relating to a Data Subject uploaded by or for Developer or Developer's agents, employees, or contractors to the Service as Developer Data, including "Personal Information," "Special Categories of Data," or "Highly Sensitive Data," or "Sensitive Data" or equivalent terms under applicable Data Protection Law.

"**Security Incident**" means any accidental or unlawful destruction, loss, alteration, unauthorized disclosure of, or access to Developer Data. Any Personal Data Breach will comprise a Security Incident.

"**Standard Contractual Clauses**" or "**SCCs**" means: (i) the standard contractual clauses for the transfer of Personal Data to third countries pursuant to Regulation (EU) 2016/679 of the European Parliament and of the Council adopted by the European Commission Decision 2021/914 of 4 June 2021, which may be found at: [https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32021D0914\&from=EN](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32021D0914\&from=EN) and incorporated herein by reference ("EU SCC"); (ii) the UK "International Data Transfer Addendum to the European Commission Standard Contractual Clauses" available at: [https://ico.org.uk/media/for-organisations/documents/4019539/international-data-transfer-addendum.pdf](https://ico.org.uk/media/for-organisations/documents/4019539/international-data-transfer-addendum.pdf) and incorporated herein by reference ("UK SCC"); or (iii) the applicable standard data protection clauses issued, approved or recognized by the Swiss Federal Data Protection and Information Commissioner ("Swiss SCC").

"**US Data Protection Laws**" means federal and state privacy laws applicable to the Decart.ai Processing activities of Developer Data under this DPA, and any implementing regulations and amendment thereto, including without limitation the: (i) California Consumer Privacy Act (Cal. Civ. Code §§ 1798.100 - 1798.199) of 2018 including as modified by the California Privacy Rights Act as well as all regulations promulgated thereunder from time to time ('CCPA'); and (ii) other state privacy laws. All as amended or superseded from time to time and including any implementing regulations and amendments thereto.

## 2. Roles and Details of Processing

**2.1** The parties acknowledge and agree that, in connection with their respective obligations under the Agreement, and with respect to the Processing of Developer Data, Decart.ai is acting as a Data Processor (or Sub-processor, as applicable) and Developer is acting as a Data Controller (or Processor, on behalf of its End Users, as applicable). Each party will comply with Data Protection Law to which it is subject in the performance on this DPA.

**2.2** Notwithstanding the above, Decart.ai shall remain the owner and Data Controller of the Usage Data (as defined in the Agreement) and certain Developer Account information, including contact information, transactions records, credit purchases and other commercial information of the Developer or Authorized Users. This information is processed by Decart.ai to manage the customer relationship, customer success, provide support, address bugs, facilitate security, provide maintenance and carry out core business functions such as accounting, billing, and filing taxes.

**2.3** The Developer shall be exclusively responsible for defining the lawful basis for Processing Developer Data, including by obtaining any required consent and providing any required disclosures under applicable Data Protection Laws. Decart.ai shall act based on such lawful basis and Instructions provided by the Developer.

**2.4** The subject matter and duration of the Processing carried out by Decart.ai on behalf of the Developer, the nature and purpose of the Processing, the type of Personal Data and categories of Data Subjects are described in Annex I attached hereto.

**2.5** The Developer acknowledges and agrees that, as part of the Processing, the Developer Data will be processed using Decart.ai Models which incorporate Artificial Intelligence features and technologies, as described in the Agreement and provided by Decart.ai.

## 3. Processing of Personal Data

**3.1** Decart.ai represents and warrants that it shall Process Developer Data, on behalf of the Developer, solely for the purpose of providing the Services, in accordance with the Instructions. Notwithstanding the above, in the event Decart.ai is required under applicable laws, including Data Protection Law, to Process Developer Data other than as instructed by Developer, it shall make reasonable efforts to inform the Developer of such requirement prior to Processing such Developer Data, unless prohibited under applicable law.

**3.2** Decart.ai shall inform Developer without undue delay (unless otherwise required by law) in the event that, according to Decart.ai's reasonable discretion, any of the Instructions infringes applicable laws, and Decart.ai shall have the right to immediately cease and suspend any such Processing activity related to the infringing Instruction.

**3.3** Decart.ai shall provide reasonable cooperation and assistance to the Developer in ensuring compliance with its obligation to carry out data protection impact assessments and prior consultations with Supervisory Authorities or other competent data privacy authorities to the extent required under applicable Data Protection Laws, provided that, Decart.ai shall only be required to assist as for information which is reasonably available to Decart.ai and Developer does not have reasonable access to such information.

**3.4** Decart.ai shall ensure that the staff or any other person authorized to Process the Developer Data has committed themselves to confidentiality or are under an appropriate statutory obligation of confidentiality.

**3.5** Where US Data Protection Laws are applicable, Decart.ai will: (i) not Sell or Share Personal Data; (ii) use Personal Data for the Business Purpose(s) set forth in the Agreement, and not retain, use, or disclose Personal Data, except where permitted by applicable Data Protection Law, for any purpose other than the Business Purpose(s) or outside of the direct business relationship between Decart.ai and Developer; (iii) notify Developer if it determines it can no longer meet its obligations under applicable Data Protection Law; (iv) not combine Personal Data, except to the extent permitted by applicable Data Protection Laws, with personal information that Decart.ai receives from, or on behalf of, other persons or with personal information Decart.ai collects from its own interactions with Consumers; (v) by complying with the obligations set out in Section 8 of this DPA, permit Developer to take reasonable and appropriate steps to ensure Decart.ai Processes Personal Data in a manner consistent with Developer's obligations under applicable Data Protection Laws; and (vi) work together with Developer in good faith to remediate any allegedly unauthorized use of Personal Data, if Developer reasonably believes that Decart.ai is Processing Personal Data in an unauthorized manner and provides Decart.ai with reasonable written notice of such belief.

## 4. Data Subjects Rights and Requests

**4.1** It is agreed that where Decart.ai receives a data subject request or a request from a regulator or authority in respect to Developer Data, where applicable, Decart.ai will notify the Developer of such request and direct the Data Subject or the applicable authority to the Developer in order to enable the Developer to respond directly to the Data Subject's or the applicable authority's request, unless otherwise required under applicable laws or otherwise prohibited.

**4.2** Decart.ai will reasonably cooperate and assist Developer in responding to such request, provided that the Developer cannot reasonably fulfill such obligations independently with help of available in the documentation, the website or any other self-service feature provided by Decart.ai.

## 5. Sub-Processing

**5.1** The Developer acknowledges that Decart.ai may transfer Developer Data to and otherwise interact with third party data Processors ("Sub-Processor"). The Developer hereby authorizes Decart.ai to engage and appoint such Sub-Processors as listed in Annex III, as well as permits each Sub-Processor to appoint a Sub-Processor on its behalf. Decart.ai may continue to use those Sub-Processors already engaged by it or to engage an additional or replace an existing Sub-Processors to Process Developer Data, subject to the provision of a thirty (30) days prior notice of its intention to do so to the Developer (via email correspondence or through the Account). In case the Developer has not objected to the adding or replacing of a Sub-Processor within such notice period, such Sub-Processor shall be deemed approved by the Developer. In the event the Developer objects to the adding or replacing of a Sub-Processor, within such notice period, Decart.ai may, under Decart's sole discretion, suggest the engagement of a different Sub-Processor for the same course of services, or otherwise terminate the Agreement where the Services cannot be reasonably provided under such circumstances, without liability to Developer.

**5.2** Decart.ai shall, where it engages any Sub-Processor, impose, through a legally binding contract between Decart.ai and the Sub-Processor, data protection obligations that are no less onerous than, and provide at least the same level of protection as, those set out in this DPA. Decart.ai shall ensure that such contract will require the Sub-Processor to provide sufficient guarantees to implement appropriate technical and organizational measures in such a manner that the Processing will meet the requirements of Data Protection Laws.

**5.3** Decart.ai shall remain responsible to the Developer for the performance of the Sub-Processor's obligations in accordance with this DPA.

## 6. Technical and Organizational Measures

**6.1** Taking into account the state of the art, the costs of implementation and the nature, scope, context, and purposes of Processing as well as the risk of varying likelihood and severity for the rights and freedoms of natural persons, and without prejudice to any other security standards agreed upon by the parties, Decart.ai hereby confirms that it has implemented and will maintain appropriate physical, technical and organizational measures to protect the Developer Data as required under Data Protection Laws to ensure lawful Processing of Developer Data and safeguard Developer Data from unauthorized, unlawful or accidental processing, access, disclosure, loss, alteration or destruction.

**6.2** The parties acknowledge that security requirements are constantly changing, and that effective security requires frequent evaluation and regular improvement of outdated security measures. The security measures implemented and maintained by Decart.ai are further detailed in Annex II.

## 7. Security Incident

**7.1** Decart.ai will notify the Developer without undue delay (and no later than 48 hours) upon becoming aware of any Security Incident concerning Developer Data and will take necessary steps to remediate, minimize any effects of and investigate any Security Incident and to identify its cause. Upon Developer's request, Decart.ai will reasonably co-operate with the Developer and provide the Developer with such assistance and information as it may reasonably require in connection with the containment, investigation, or mitigation of the Security Incident. Developer is solely responsible for determining whether to notify the relevant supervisory or regulatory authorities and impacted Data Subjects in relation to any Security Incident and for providing such notice.

**7.2** Decart.ai will notify the Developer in writing and will keep the Developer informed of any material developments in connection with the Security Incident. Decart.ai's notification or compliance with its obligations under this Section shall not be construed as an acknowledgment by Decart.ai of any fault or liability with respect to the Security Incident.

## 8. Audit Rights

**8.1** Decart.ai shall maintain accurate written records of all categories of processing activities carried out on behalf of Developer under this DPA and shall make such records available to the supervisory authority as reasonably required under Data Protection Laws. In case such records are provided to Developer they shall be considered Decart.ai's confidential information and shall be subject to confidentiality obligations.

**8.2** Developer may audit Decart.ai's compliance with this DPA and Data Protection Laws by requesting a certificate issued for security verification reflecting the outcome of an audit conducted by a third party auditor (e.g., ISO27001 certificate) or a comparable certification or other security certification of an audit conducted by a third-party auditor, within twelve (12) months as of the date of Developer's request.

**8.3** Alternatively, in the event the records and documentation provided subject to Section 8.1 and 8.2 above are not sufficient for the purpose of demonstrating compliance, Decart.ai shall make available, solely upon prior reasonable written notice and no more than once per calendar year (except in case of severe data security incidents, e.g. data breaches resulting in a risk to the rights and freedoms of natural persons), to a reputable auditor nominated by the Developer, information necessary to reasonably demonstrate compliance with this DPA and Data Protection Laws, and shall allow for audits, including inspections, by such reputable auditor solely in relation to the Processing of the Developer Data ("Audit") in accordance with the terms and conditions hereunder. The auditor shall be subject to standard confidentiality obligations (including third parties). Decart.ai may object to an auditor appointed by the Developer in the event Decart.ai reasonably believes the auditor is not suitably qualified or is a competitor of Decart.ai. Developer shall bear all expenses related to the Audit and shall (and ensure that each of its auditors shall) over the course of such Audit, avoid causing any damage, injury, or disruption to Decart.ai's premises, equipment, personnel and business while its personnel are on those premises in the course of such Audit.

**8.4** Nothing in this DPA will require Decart.ai to either disclose to Developer or its third-party auditor, or to allow Developer or its third-party auditor to access: (i) data related to other customers or partners; (ii) Decart.ai's internal accounting or financial information; (iii) any trade secret of Decart.ai or its Affiliates; (iv) any information that, in Decart's reasonable opinion, could compromise the security of any Decart.ai's systems or cause any breach of its obligations under applicable law or its security or privacy obligations to any third party; or (v) any information that Developer or its third-party auditor seeks to access for any reason other than the good faith fulfillment of Developer's obligations under the Data Protection Laws.

## 9. Cross Border Personal Data Transfers

**9.1** Where European Data Protection Laws apply to the transfer of Personal Data from the EEA, UK or Switzerland, such transfers will be subject to measures as are necessary to ensure the transfer is in compliance with European Data Protection Laws, which include (without limitation) at least one of the following: (i) transferring such Personal Data to a recipient that is covered by a suitable framework or other legally adequate transfer mechanism recognized by the relevant authorities or courts as providing an adequate level of protection for Personal Data, including to an Adequate Country or data privacy and transfer frameworks such as the DPF; (ii) to a recipient that has achieved binding corporate rules authorization in accordance with applicable European Data Protection Law; or (iii) to a recipient that has executed the Standard Contractual Clauses.

**9.2** When Developer and Decart.ai rely on the SCC to facilitate a transfer to a third country the following shall apply:

**(a)** For Transfer of Personal Data from the EEA the EU SCC shall apply and completed as follows: (1) Module II (Controller to Processors) will apply; (2) In Clause 7 the optional docking clause will not apply; (3) In Clause 9, option 2 (general written authorization) shall apply for the Sub-Processors listed in the Sub-Processors list and the method for appointing Sub-Processor shall be as set forth in the Sub-Processing Section of the DPA; (4) In Clause 11, the optional language will not apply, and Data Subjects shall not be able to lodge a complaint with an independent dispute resolution body; (5) In Clause 17, option 1 shall apply, and the EU SCC shall be governed by the law of the Republic of Ireland; (6) In Clause 18(b) the parties choose the competent courts of the Republic of Ireland, as their choice of forum and jurisdiction; (7) Annex I(A) of the EU SCC is completed as follows: Developer is the Data Exporter, Decart.ai is the Data Importer, the parties' contact details Agreement Effective Date; Annex I(B) of the EU SCC is completed as set out in Annex I of this DPA; Annex I(C) of the EU SCC shall identify the competent supervisory authority/ies as the supervisory authority Republic of Ireland; (8) Annex II of the EU SCC is deemed completed with the information set out in Annex II of this DPA; (9) Annex III of the EU SCC shall be completed with the list of Sub-Processors.

**(b)** For transfer of Personal Data from the UK, the UK SCC shall apply and completed as follows: (1) Table 1 shall be completed as set forth in section (a)(7) above; (2) Table 2 shall be completed as set forth in Section (a)(1) - (a)(4) above; (3) Tables 3 shall be completed as follows: Annex 1A shall be completed with relevant information as set out in Section (a)(7) above; Annex 1B shall be completed with relevant information as set out in Annex I of this DPA; Annex II shall be completed with relevant information as set out in the trust center; Annex III shall be completed with the list of sub-processors; (4) Table 4 shall be completed with the "neither party" option; and (5) Any conflict between the terms of the EU SCC and the UK SCC will be resolved in accordance with Section 10 and Section 11 of the UK SCC.

**(c)** For transfer of Personal Data from Switzerland, the Swiss SCC shall apply in with following modifications (i) references to "Regulation (EU) 2016/679" will be interpreted as references to the Swiss DPA; (ii) references to "EU", "Union" and "Member State law" will be interpreted as references to Swiss law; and (iii) references to the "competent supervisory authority" and "competent courts" will be replaced with the "the Swiss Federal Data Protection and Information Commissioner" and the "relevant courts in Switzerland".

## 10. Term, Termination and Conflict

**10.1** This DPA shall be effective as of the Effective Date and shall remain in force until the Agreement terminates or as long as Decart.ai Processes Developer Data.

**10.2** Following the termination or expiration of this DPA, Decart.ai shall, upon Developer's written request, delete Developer Data Processed on behalf of the Developer and certify to the Developer that it has done so, or, return Developer Data to the Developer and delete existing copies, unless applicable law or regulatory requirements requires that Decart.ai continue to store Developer Data. Until the Developer Data is deleted or returned, the parties shall continue to ensure compliance with this DPA. In any case, Decart.ai reserves the right to delete any Developer Data 60-days from deletion of the Account.

**10.3** In the event of a conflict between the terms and conditions of this DPA and the Agreement, this DPA shall prevail. For the avoidance of doubt, in the event Standard Contractual Clauses have been executed between the parties, the terms of the Standard Contractual Clauses shall prevail over those of this DPA. Except as set forth herein, all of the terms and conditions of the Agreement shall remain in full force and effect as between Developer and Decart.ai.

## Annex I — Details of Processing

This Annex I includes certain details of the Processing of Personal Data as required under the Data Protection Laws.

### List of Parties

**Data exporter:**

* Name: Developer's name as identified in the Account
* Address: Developer's address as identified in the Account
* Contact person's name and contact details: Developer's contact details as specified in the Account
* Activities relevant to the data transferred under these clauses: Receipt of the Services
* Signature and date: These clauses shall be deemed executed and entered into by Developer as of the DPA Effective Date.
* Role: The data exporter's role shall be Controller or Processor specified in Section 2.1 of the DPA.

**Data importer:**

* Name: Decart.ai Inc.
* Address: 1007 N Orange St, Fl 10, Wilmington, Delaware, 19801, United States.
* Contact person's name, position and contact details: [dpo@decart.ai](mailto:dpo@decart.ai)
* Activities relevant to the data transferred under these Clauses: Provision of the Services
* Signature and date: These clauses shall be deemed executed and entered into by Decart.ai as of the DPA Effective Date.
* Role: The data importer's role shall be Processor.

### Description of Transfer

**Categories of Data Subjects:**
The Developer, Authorized User or End Users or any individual that the Developer, Authorized User or End Users uploaded personal data about such individual while using the Services, as part of the Input.

**Categories of Personal Data or Special Categories of Personal Data:**
Any content, information, text, audio, photo, images, video or otherwise submitted through the Services (including the within the Input), or behavior insights, engagement, and communication with the End User, Developer, or Authorized User (to the extent applicable).

**Nature of the processing:**
Collection, storage, organization, communication, transfer, host and other types of processing for the purpose of providing the Services as set out in the Agreement by Decart.ai.

**Purpose(s) of Processing:**
To provide the Developer (including Authorized Users) to use the Services, including API access and use of Decart.ai Models. As well as enable the Developer's End Users to generate or modify content in real time, edit content or create content.

**Retention Period:**
Personal Data shall be retained for as long as it is necessary to provide the Services or as is required by applicable law. Upon termination or expiration of the Agreement, Decart.ai will delete or destroy any Personal Data as requested by the Developer unless otherwise required by law. In any case, Decart.ai reserves the right to delete any Personal Data 60-days from deletion of the Account.

**Process Frequency:**
Continuous basis.

## Annex II — Technical and Operational Security Measures

This Technical and Operational Security Measures Annex (Security Annex) forms part of, and is incorporated by reference into, the Data Processing Agreement ("DPA") between Decart.ai Inc. (Processor) and Developer (Customer). Capitalized terms used but not defined in this Security Annex have the meanings given in the DPA and in the [API Terms of Service](/resources/api-terms) ("Agreement") executed by and between Decart.ai and the Developer. This Security Annex describes the technical and organizational measures implemented and maintained by the Processor, in its capacity as a "processor", to ensure a level of security appropriate to the risk when providing API-based inference services for decart.ai Models and related generative AI services that may Process the Customer's Personal Data on the Customer's behalf.

**Information Security Management System (ISMS).** Processor shall maintain an Information Security Management System (ISMS), including supporting policies and procedures, aligned with applicable security-related industry standards. The Processor's ISMS shall be designed to protect the confidentiality, integrity, and availability of the Services and Customer Personal Data, and to support the Processor's compliance with Applicable Laws relating to the Processing of Customer Personal Data and the provision of the Services.

**Substantial Identification and authentication mechanisms.** Processor shall ensure that access to the systems shall include substantial Identification and authentication mechanisms, including multi factor authentication mechanisms where required.

**Access Permissions.** Processor shall determine access permissions for authorized users to the Systems in accordance with each role's responsibilities. Access permissions shall be granted only to the extent required to perform the applicable role. The Processor shall keep an up-to-date record of roles, user permissions granted to such roles, and the authorized users performing such roles ("Access Registry"), and shall review the Access Registry to ensure proper management based on the role-based authorization concept. Immediately following the termination of an authorized user's role, the Processor shall revoke that user's permissions and, to the extent practicable, change passwords for any Systems to which the authorized user may have had access or knowledge of passwords.

**Access Control.** Processor shall establish and implement physical and electronic controls and safeguards to protect Systems used to manage, Process, or store Customer Personal Data against unauthorized access, disclosure, modification, destruction, interference, or downtime, in a manner consistent with industry standards. This includes ensuring that only authorized persons can access Customer Personal Data processing systems and that, during Processing, Customer Personal Data cannot be read, copied, modified, or deleted without authorization. Specific measures include:

* **Physical Access Control.** Processor utilizes third-party Sub-Processor cloud infrastructure providers to host and process Customer Personal Data. Customer acknowledges that physical access controls are maintained by such Sub-processors in accordance with their respective security certifications (e.g., SOC 2 Type II, ISO 27001). Processor shall monitor Sub-Processor's compliance through its sub-processor management program.

* **Electronic Access Control.** Processor shall monitor and record access to the systems used in connection with Customer Personal Data by implementing an appropriate automated monitoring mechanism for its systems ("Monitoring Systems"). A record of each user's access to the Systems (a "Log") shall include: (i) the user's identity; (ii) the Customer Personal Data accessed and the time of the access attempt; (iii) the system component to which access was attempted; (iv) the access type and scope; and (v) whether access was granted or denied. The Monitoring Systems shall not permit disabling or modification of their operation and shall detect such modification or disabling and send alerts to those responsible. Logs shall be retained for at least twelve (12) months from the date of creation and shall be made available to Customer upon request for audit or investigation purposes. The Processor shall notify its authorized users of the existence of the Monitoring Systems.

**Security Operations.** Processor shall maintain a documented patch management plan or patching process and shall provide it to Customer upon request. The Processor shall update and apply security patches to its systems and endpoint devices on a regular basis.

**Secure Development/Code Review.** Processor shall follow a secure development lifecycle for its applications and systems. Processor shall conduct, or have an independent security organization conduct, an application security code review.

**Security Testing.** Processor shall conduct vulnerability scanning and penetration testing of applications and devices that handle Customer Personal Data at least annually. Processor shall remediate critical and high-level risks identified by such scans.

**Timely Response to Vulnerabilities.** Processor shall remediate, within industry best-practice timelines, security vulnerabilities that may impact Customer Personal Data.

**Network Security.** Processor shall maintain the security of the Systems in accordance with practices consistent with industry standards. Such security shall include, at a minimum: (i) the use of anti-virus and anti-malware systems; (ii) the use of firewall systems; and (iii) physically and logically segregating infrastructure that Processes Customer Personal Data from infrastructure that Processes non-Customer Personal Data.

**System Mapping and Risk Assessment.** Processor shall maintain up-to-date documentation detailing, with respect to Customer Personal Data and the Systems used to Process it, the following: (i) an up-to-date inventory of digital assets, including at least each asset's owner and risk level; and (ii) network topology. Processor shall conduct an information security risk assessment at least once every eighteen (18) months and shall update its information security procedures and safeguards accordingly.

**Endpoint Security Requirements.** Endpoint devices used by Processor to access Systems or exchange Customer Personal Data must meet Processor's security standards and the provisions of this Security Annex. This includes, without limitation, ensuring that: (i) anti-virus and anti-malware software is installed, active, and up to date; (ii) endpoint devices have strong password policies enforced; and (iii) disk encryption is enabled where applicable.

**Portable Devices Restrictions.** Processor shall continuously document the connection of portable devices of any type to Systems containing Customer Personal Data. Such connections and use shall be permitted only with prior authorization. Processor shall also ensure that downloading Customer Personal Data onto portable devices is prohibited.

**Secure Customer Personal Data Destruction and Return.** Processor shall retain Customer Personal Data only for the period necessary to provide the Services. Upon termination of the Agreement, Processor shall return to Customer all Customer Personal Data and delete it (including from its archives), unless otherwise requested by Customer in writing. If Customer provides written consent for Processor to retain Customer Personal Data after termination, Processor shall retain Customer Personal Data in accordance with Processor's Customer Personal Data retention policy, subject to confidentiality obligations and applicable legal requirements.

**Backups.** Processor shall maintain a procedure for regular backups of Customer Personal Data and all relevant Systems and software. Such procedure shall ensure that: (i) Customer Personal Data is securely stored in backups using the same security protocols required for the primary environment; (ii) restoration of Customer Personal Data may be performed only with Customer's prior written permission; and (iii) Processor shall document any restoration, including the identity of the person who performed the restoration and details of the information restored.

**Sub-Processor Relationships.** Processor shall contractually flow down the material obligations of this Security Annex to each subcontractor utilized in the provision of the Services. Processor shall remain responsible for the acts and omissions of its subcontractors and shall regularly monitor, review, and audit subcontractor security controls.

**Annual Assessments, Audits, and Certifications.** Processor shall conduct annual information security assessments and audits of its systems and operations relevant to the Processing of Customer Personal Data. Processor represents and warrants that it maintains current SOC 2 Type 2, ISO 27001 and ISO 42001 certifications, and shall provide evidence of such certifications to Customer upon request and standard confidentially obligations.

**Human Resource Security.** Processor shall provide annual training to all personnel who have access to Customer Personal Data. Such training shall cover the protection of Customer Personal Data, applicable security procedures and protocols, and cyber security awareness. Processor shall ensure that such personnel are appropriately vetted and are bound by written confidentiality obligations, and that they complete such training prior to being granted access to Customer Personal Data.

**Incident Management Program.** Processor shall maintain and implement a documented information security event management process, including incident reporting, response, prioritization, escalation, and remediation.

**Business Continuity and Disaster Recovery.** Processor shall document and maintain a Business Continuity and Disaster Recovery Plan in accordance with industry best practices and consistent with industry standards and shall perform an annual disaster recovery plan exercise.

## Annex III — List of Sub-Processors

| Name | Processing Activity | Sub-Processor Location |
| - | - | - |
| Amazon Web Services, Inc. | Cloud provider | USA |
| Google LLC (Google Cloud) | Cloud provider; content moderation and processing for generation of outputs | USA |
| Castle Global, Inc. (Hive) | Content moderation | USA |
| Eleven Labs Inc. | Voice model training and audio processing (only if certain features used) | USA |
| OpenAI OpCo, LLC | Processing for generation of outputs (only if certain features used) | USA |
| Fal, inc | Model inference (only if certain features used) | USA |
| Veriff OÜ | Identity Verification | Estonia |


# FAQ
Source: https://docs.platform.decart.ai/resources/faq

Common questions about Decart APIs, SDKs, pricing, and realtime

## Getting started

<AccordionGroup>
  <Accordion title="How do I get an API key?">
    Sign up at [platform.decart.ai](https://platform.decart.ai), then create a key in [API Keys](https://platform.decart.ai/api-keys).
  </Accordion>

  <Accordion title="Which API should I start with?">
    * Use **Realtime API** for live camera/video interactions
    * Use **Queue API** for async video editing/processing
    * Use **Process API** for synchronous image editing

    See [Getting Started Overview](/getting-started/overview).
  </Accordion>

  <Accordion title="Is there a free tier?">
    Yes. New accounts receive free credits for evaluation.
  </Accordion>
</AccordionGroup>

## Realtime and authentication

<AccordionGroup>
  <Accordion title="Can I use my permanent API key in the browser?">
    No. Use short-lived client tokens for browser/mobile apps. See [Client Tokens](/getting-started/client-tokens).
  </Accordion>

  <Accordion title="My client token expired. Will it disconnect my active session?">
    No. Expiration blocks new connections. Active realtime sessions continue until disconnected. A reconnect after a network drop is a new connection, so pass `apiKeyProvider` to `createDecartClient` to keep reconnects working. See [Token lifetime](/getting-started/client-tokens#token-lifetime).
  </Accordion>

  <Accordion title="What causes common WebRTC connection failures?">
    Most issues come from camera permissions, unsupported environment (simulators), network restrictions, or incorrect model stream constraints. See [Streaming Best Practices](/models/realtime/streaming-best-practices).
  </Accordion>
</AccordionGroup>

## Models and pricing

<AccordionGroup>
  <Accordion title="Can I use Lucy 2.1 for both realtime and batch video editing?">
    Yes. `lucy-2.1` is available on both the realtime streaming API and the async queue API. See [Models](/getting-started/models).
  </Accordion>

  <Accordion title="How is billing calculated?">
    Realtime and video models are billed per second, and image models are billed per generation. See [Pricing](/getting-started/pricing).
  </Accordion>

  <Accordion title="Do you offer enterprise pricing?">
    Yes. Contact `contact@decart.ai` for volume discounts and custom plans.
  </Accordion>
</AccordionGroup>

## SDKs and integration

<AccordionGroup>
  <Accordion title="Do you provide official SDKs?">
    Yes. We provide JavaScript, Python, and Swift SDKs:

    * [JavaScript SDK](/sdks/javascript)
    * [Python SDK](/sdks/python)
    * [Swift SDK](/sdks/swift)
  </Accordion>

  <Accordion title="How do I secure client-side image/video calls?">
    Use a server-side proxy so API keys never reach the browser. See the official proxy examples in our SDK repositories.
  </Accordion>

  <Accordion title="Can I use Decart in production?">
    Yes. The platform is designed for production use with usage-based pricing, API keys, client token auth for realtime, and official SDKs.
  </Accordion>
</AccordionGroup>


# Video Queue API Migration
Source: https://docs.platform.decart.ai/resources/migrations/video-queue-api

Migrate from the synchronous generate endpoint to the asynchronous job-based Queue API for video generation.

We've updated video generation to use an asynchronous job-based Queue API. This change improves reliability, allows for better timeout handling, and provides visibility into job progress. The synchronous `/v1/generate/` endpoints for video are now deprecated in favor of the new `/v1/jobs/` endpoints.

## What Changed

| Aspect | Before (Generate API) | After (Queue API) |
| - | - | - |
| **Endpoint** | `/v1/generate/lucy-latest` | `/v1/jobs/lucy-latest` |
| **Request type** | Synchronous (blocking) | Asynchronous (non-blocking) |
| **Response** | Direct video binary | Job ID for polling |
| **Timeout handling** | HTTP timeout on long requests | Poll until completion (10 min max) |
| **Progress visibility** | None | Status updates (`pending`, `processing`, `completed`, `failed`) |

## JavaScript SDK

The JavaScript SDK now uses `client.queue` instead of `client.generate` for video generation.

### Before

```javascript theme={null}
import { createDecartClient, models } from "@decartai/sdk";
import { readFileSync, writeFileSync } from "fs";

const client = createDecartClient({ apiKey: "your-api-key" });
const videoFile = new Blob([readFileSync("input.mp4")], { type: "video/mp4" });

// Synchronous - blocks until video is ready
const video = await client.generate({
  model: models.video("lucy-latest"),
  data: videoFile,
  prompt: "Transform into anime style",
});

writeFileSync("output.mp4", Buffer.from(await video.arrayBuffer()));
```

### After

```javascript theme={null}
import { createDecartClient, models } from "@decartai/sdk";
import { readFileSync, writeFileSync } from "fs";

const client = createDecartClient({ apiKey: "your-api-key" });
const videoFile = new Blob([readFileSync("input.mp4")], { type: "video/mp4" });

// Asynchronous - submit and poll for completion
const result = await client.queue.submitAndPoll({
  model: models.video("lucy-latest"),
  data: videoFile,
  prompt: "Transform into anime style",
  onStatusChange: (job) => console.log(`Status: ${job.status}`),
});

if (result.status === "completed") {
  writeFileSync("output.mp4", Buffer.from(await result.data.arrayBuffer()));
}
```

<Accordion title="Manual polling (advanced)">
  For custom polling logic, you can manually control the submit/poll/result flow:

  ```javascript theme={null}
  // Submit job
  const job = await client.queue.submit({
    model: models.video("lucy-latest"),
    data: videoFile,
    prompt: "Transform into anime style",
  });

  console.log(`Job ID: ${job.job_id}`);

  // Poll for status
  while (true) {
    const status = await client.queue.status(job.job_id);
    console.log(`Status: ${status.status}`);

    if (status.status === "completed") {
      const result = await client.queue.result(job.job_id);
      writeFileSync("output.mp4", Buffer.from(await result.data.arrayBuffer()));
      break;
    } else if (status.status === "failed") {
      console.error("Job failed");
      break;
    }

    await new Promise(r => setTimeout(r, 2000));
  }
  ```
</Accordion>

<Card title="JavaScript Queue API Reference" icon="book" href="/sdks/javascript-queue">
  Full documentation for the JavaScript Queue API
</Card>

***

## Python SDK

The Python SDK now uses `client.queue` instead of `client.generate` for video generation.

### Before

```python theme={null}
import asyncio
from decart import DecartClient, models

async def generate():
    async with DecartClient(api_key="your-api-key") as client:
        # Synchronous - blocks until video is ready
        with open("input.mp4", "rb") as video_file:
            video = await client.generate({
                "model": models.video("lucy-latest"),
                "data": video_file,
                "prompt": "Transform into anime style",
            })

        with open("output.mp4", "wb") as f:
            f.write(video)

asyncio.run(generate())
```

### After

```python theme={null}
import asyncio
from decart import DecartClient, models

async def generate():
    async with DecartClient(api_key="your-api-key") as client:
        # Asynchronous - submit and poll for completion
        with open("input.mp4", "rb") as video_file:
            result = await client.queue.submit_and_poll({
                "model": models.video("lucy-latest"),
                "data": video_file,
                "prompt": "Transform into anime style",
                "on_status_change": lambda job: print(f"Status: {job.status}"),
            })

        if result.status == "completed":
            with open("output.mp4", "wb") as f:
                f.write(result.data)

asyncio.run(generate())
```

<Accordion title="Manual polling (advanced)">
  For custom polling logic, you can manually control the submit/poll/result flow:

  ```python theme={null}
  import asyncio

  # Submit job
  with open("input.mp4", "rb") as video_file:
      job = await client.queue.submit({
          "model": models.video("lucy-latest"),
          "data": video_file,
          "prompt": "Transform into anime style",
      })

  print(f"Job ID: {job.job_id}")

  # Poll for status
  while True:
      status = await client.queue.status(job.job_id)
      print(f"Status: {status.status}")

      if status.status == "completed":
          result = await client.queue.result(job.job_id)
          with open("output.mp4", "wb") as f:
              f.write(result.data)
          break
      elif status.status == "failed":
          print("Job failed")
          break

      await asyncio.sleep(2)
  ```
</Accordion>

<Card title="Python Queue API Reference" icon="book" href="/sdks/python-queue">
  Full documentation for the Python Queue API
</Card>

***

## HTTP / REST API

The REST API now uses a three-step flow: submit, poll, and retrieve.

### Before

```bash theme={null}
# Single request - blocks until complete (could timeout on long generations)
curl -X POST https://api.decart.ai/v1/generate/lucy-latest \
  -H "X-API-KEY: $DECART_API_KEY" \
  -F "data=@input.mp4" \
  -F "prompt=Transform into anime style" \
  --output output.mp4
```

### After

```bash theme={null}
# Step 1: Submit job
JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-latest \
  -H "X-API-KEY: $DECART_API_KEY" \
  -F "data=@input.mp4" \
  -F "prompt=Transform into anime style" | jq -r '.job_id')

echo "Job submitted: $JOB_ID"

# Step 2: Poll for status
while true; do
  STATUS=$(curl -s -H "X-API-KEY: $DECART_API_KEY" \
    https://api.decart.ai/v1/jobs/$JOB_ID | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && exit 1
  sleep 2
done

# Step 3: Download result
curl -H "X-API-KEY: $DECART_API_KEY" \
  https://api.decart.ai/v1/jobs/$JOB_ID/content --output output.mp4
```

### Endpoint mapping

| Old Endpoint | New Endpoint |
| - | - |
| `POST /v1/generate/lucy-latest` | [`POST /v1/jobs/lucy-latest`](/api-reference/lucy-latest) |

<Note>
  `lucy-latest` always resolves to the newest video editing model (currently Lucy 2.5). To pin a version, use [`POST /v1/jobs/lucy-2.5`](/api-reference/lucy-25).
</Note>

### New endpoints for job management

| Endpoint | Description |
| - | - |
| [`GET /v1/jobs/{job_id}`](/api-reference/get-job) | Get job status |
| [`GET /v1/jobs/{job_id}/content`](/api-reference/get-job-content) | Download completed video |

***

## Key Differences

### Error handling

The Queue API provides more granular error information through job status:

```javascript theme={null}
const result = await client.queue.submitAndPoll({
  model: models.video("lucy-latest"),
  data: videoFile,
  prompt: "Transform into anime style",
});

if (result.status === "failed") {
  console.error(`Generation failed: ${result.error}`);
}
```

### Progress tracking

Monitor job progress with status callbacks:

```javascript theme={null}
const result = await client.queue.submitAndPoll({
  model: models.video("lucy-latest"),
  data: videoFile,
  prompt: "Transform into anime style",
  onStatusChange: (job) => {
    // Called when status changes: pending -> processing -> completed
    updateProgressUI(job.status);
  },
});
```

***

## FAQ

<AccordionGroup>
  <Accordion title="Are the old /v1/generate/ endpoints still available?">
    The old synchronous endpoints for video generation are deprecated.
    Image generation still uses `/v1/generate/`.
  </Accordion>

  <Accordion title="Do I need to update my SDK version?">
    Yes, make sure you're using the latest version of the SDK:

    * JavaScript: `npm install @decartai/sdk@latest`
    * Python: `pip install decart --upgrade`
  </Accordion>

  <Accordion title="What about image generation?">
    Image generation continues to use the synchronous Process API (`client.process` in SDKs, `/v1/generate/` for REST). Only video generation has moved to the Queue API.
  </Accordion>
</AccordionGroup>


# Privacy Policy
Source: https://docs.platform.decart.ai/resources/privacy-policy



**Last Updated: August 20, 2026**

This privacy policy ("Privacy Policy") governs how Decart.AI Inc. ("Decart.ai", "we", "our" or "us") use, collect and store Personal Data we collect or receive from or about you ("you") in connection with the Decart's Image and Video Models accessible via [https://decart.ai/](https://decart.ai/) (together with its subdomains, Materials, Marks, features and services, the "Websites") or the respective mobile application and any other mobile software application, that we license (the "App"; collectively, the "Platform"), such as in the following use cases:

* When you browse or visit our Website;
* When you make use of, or interact with, our Platform:
  1. When you create an account and when you log in
  2. When you contact us (e.g. customer support, need help, submit a request)
  3. When you subscribe to our distribution list(s) / newsletter(s) / blog(s) / social community(s)
* When we process your Input (As defined in our Terms of Service) to create Output (As defined in our Terms of Service) and when we use your Content as permitted by these Terms of Service;
  1. When you generate videos or pictures
  2. When you interact with our video model
* When you interact with us on our social media profiles.

Please read this Privacy Policy carefully, so you can understand our practices and your rights in relation to personal data. "Personal Data" or "Personal Information" means any information that can be used, alone or together with other data, to uniquely identify any living human being and any information deemed as Personally Identifiable Information by privacy laws. Please note that this is a master privacy policy and some of its provisions only apply to individuals in certain jurisdictions. For example, the legal basis in the table below is only relevant to GDPR-protected. Important note: Nothing in this Privacy Policy is intended to limit in any way your statutory right, including your rights to a remedy or means of enforcement.

## Table of contents

1. What information we collect, why we collect it, and how it is used
2. How we protect and retain your Personal Data
3. How we share your Personal Data
4. Additional information regarding transfers of Personal Data
5. Your privacy rights
6. Use by children
7. Interaction with third-party products
8. Analytic tools
9. Specific provisions applicable under California privacy law
10. Contact us

This Privacy Policy can be updated from time to time and, therefore, we ask you to check back periodically for the latest version of this Privacy Policy. If we implement significant changes to the use of your Personal Data in a manner different from that stated at the time of collection, we will notify you by posting a notice on our Platform or by other means. The Platform is owned and operated by Decart Ai, Inc., which is the data controller.

## 1. WHAT INFORMATION WE COLLECT, WHY WE COLLECT IT, AND HOW IT IS USED

### When you browse or visit our Website

| Specific Personal Data we collect | Why is Personal Data collected and for what purposes? | Legal basis (GDPR only, if applicable) | Third parties with whom we share your Personal Data | Consequences of not providing the Personal Data |
| - | - | - | - | - |
| Cookies, analytic tools, and log files | - To review or improve the usage and operations of our Website<br />- To analyze trends<br />- To administer the Website<br />- To track users' movement around the Website<br />- To determine the effectiveness of promotional campaigns<br />- To improve the Platform and fixing faults | Consent<br /><br />Legitimate Interest (e.g., essential cookies) | 3rd party platforms such as the Analytics Tools detailed in Section 8 below | Certain non-essential Website features may not be available |

### When you make use of, or interact with, our Platform

#### When you create an account and when you log in

| Specific Personal Data we collect | Why is Personal Data collected and for what purposes? | Legal basis (GDPR only, if applicable) | Third parties with whom we share your Personal Data | Consequences of not providing the Personal Data |
| - | - | - | - | - |
| - Full name<br />- Age<br />- Gender<br />- Country<br />- Email address<br />- Phone Number<br />- Social media account<br />- IP address<br />- Password<br />- Preferred Language<br />- Government issued ID | - To be able to create an account<br />- To be able to log in<br />- To be able to enjoy features available to registered users only<br />- To verify your identity<br />- To prevent fraud | Consent<br /><br />Legitimate interest (e.g. to provide you with the Platform; prevent fraud and protect the security and integrity of the Platform)<br /><br />Processing is necessary for the performance of a contract to which the data subject is party or in order to take steps at the request of the data subject prior to entering into a contract | 3rd party platforms for the following purposes:<br />If the Platform allows and/or requires signup and/or signin via services using OAuth (or similar), then the 3rd party providing the service (for example, Google) may also have access to the data.<br />If the Platform allows and/or requires email verification, then 3rd party providers may be used in order to perform this verification.<br />If the Platform allows and/or requires government issued ID verification, then 3rd party providers may be used in order to perform this verification. | Cannot create an account<br /><br />Cannot log in<br /><br />Cannot enjoy all the features of the Platform |

#### When you contact us (e.g. customer support, need help, submit a request)

| Specific Personal Data we collect | Why is Personal Data collected and for what purposes? | Legal basis (GDPR only, if applicable) | Third parties with whom we share your Personal Data | Consequences of not providing the Personal Data |
| - | - | - | - | - |
| - Full name<br />- Email address<br />- Message<br />- Username (on the social media platform from which you reached out to us) | - To process and answer questions<br />- To provide support (e.g., to solve problems, bugs or issues) | Processing is necessary for the performance of a contract to which the data subject is party or in order to take steps at the request of the data subject prior to entering into a contract<br /><br />Legitimate interest (e.g. respond to your request) | 3rd party platforms such as "X" for answering your questions and providing support | Cannot process and answer questions<br />Cannot provide support (e.g., to solve problems, bugs or issues) |

#### When you subscribe to our distribution list(s) / newsletter(s) / blog(s) / social community(s)

| Specific Personal Data we collect | Why is Personal Data collected and for what purposes? | Legal basis (GDPR only, if applicable) | Third parties with whom we share your Personal Data | Consequences of not providing the Personal Data |
| - | - | - | - | - |
| - Full name<br />- Email address<br />- Usernames<br />- Handles on social communities | - To add you to our mailing list<br />- To send you marketing communications and surveys<br />- To enable you to take part in our social communities | Legitimate interest (e.g. to send you marketing communications)<br /><br />Consent (in some contexts) | N/A | Cannot send you marketing communications<br /><br />Cannot join our social communities |

### When we process your Input to create Outputs

#### When you generate pictures or videos

| Specific Personal Data we collect | Why is Personal Data collected and for what purposes? | Legal basis (GDPR only, if applicable) | Third parties with whom we share your Personal Data | Consequences of not providing the Personal Data |
| - | - | - | - | - |
| - Content (as defined in our Terms of Service)<br />- Image(s)<br />- Video | - To improve and develop our Platform, our products and our services and to conduct research<br />- For marketing, analytics, and statistics purposes | Processing is necessary for the performance of a contract to which the data subject is party or in order to take steps at the request of the data subject prior to entering into a contract | N/A | Cannot create your character<br /><br />Cannot provide you with the Outputs |

#### When you interact with our video model

| Specific Personal Data we collect | Why is Personal Data collected and for what purposes? | Legal basis (GDPR only, if applicable) | Third parties with whom we share your Personal Data | Consequences of not providing the Personal Data |
| - | - | - | - | - |
| - Content (as defined in our Terms of Service)<br />- Account Information<br />- Audio live recording<br />- Video live recording<br />- Other information you provide | - To interact with our Platform<br />- To improve and develop our Platform, our products and our services and to conduct research | Processing is necessary for the performance of a contract to which the data subject is party or in order to take steps at the request of the data subject prior to entering into a contract | N/A | Cannot provide you with the Outputs |

### When you interact with us on our social media profiles

| Specific Personal Data we collect | Why is Personal Data collected and for what purposes? | Legal basis (GDPR only, if applicable) | Third parties with whom we share your Personal Data | Consequences of not providing the Personal Data |
| - | - | - | - | - |
| - Social Media Account<br />- Content of interaction (text, images, etc.), including metadata (for example, timestamp) | - To process and answer questions<br />- To provide support<br />- To review our services<br />- To process your feedback | Legitimate interest | The 3rd party social media platforms may have access to the data communicated | Cannot contact with you on social media |

***

Finally, please note that some of the abovementioned Personal Data will be used for detecting, taking steps to prevent, and prosecution of fraud or other illegal activity, to identify and repair errors, to conduct audits, and for security purposes. Personal Data may also be used to comply with applicable laws, with investigations performed by the relevant authorities, law enforcement purposes, and/or to exercise or defend legal claims. In certain cases, we may or will anonymize or de-identify your Personal Data and further use it for internal and external purposes, including, without limitation, to improve the services, to further the business and for research purposes. "Anonymous Information" means information which does not enable identification of an individual user, such as aggregated information about the use of our services.

## 2. HOW WE PROTECT AND RETAIN YOUR INFORMATION

**2.1. Security.** We have implemented appropriate technical, organizational and security measures designed to protect your Personal Data. However, please note that we cannot guarantee that the information will not be compromised as a result of unauthorized penetration to our servers. As the security of information depends in part on the security of the computer, device or network you use to communicate with us and the security you use to protect your user IDs and passwords, please make sure to take appropriate measures to protect this information.

**2.2. Retention of your Personal Data.** Your Personal Data will be stored until we delete the record and we proactively delete it or you send a valid deletion request, please note that in some circumstances we may store your Personal Data for longer periods of time, for example (i) where we are required to do so in accordance with legal, regulatory, tax or accounting requirements, or (ii) for us to have an accurate record of your dealings with us in the event of any complaints or challenges, or (iii) if we reasonably believe there is a prospect of litigation relating to your Personal Data or dealings.

## 3. HOW WE SHARE YOUR PERSONAL DATA

In addition to the recipients described above, we may share your Personal Data as follows:

**3.1.** With our business partners with whom we jointly offer products or services. We may also share Personal Data with our affiliated companies.

**3.2.** To the extent necessary, with regulators, courts or competent authorities, to comply with applicable laws, regulations and rules (including, without limitation, federal, state or local laws), and requests of law enforcement, regulatory and other governmental agencies or if required to do so by court order;

**3.3.** If, in the future, we sell or transfer, or we consider selling or transferring, some or all of our business, shares or assets to a third party, we will disclose your Personal Data to such third party (whether actual or potential) in connection with the foregoing events;

**3.4.** In the event that we are acquired by, or merged with, a third party entity, or in the event of bankruptcy or a comparable event, we reserve the right to transfer, disclose or assign your Personal Data in connection with the foregoing events, including, in connection with, or during negotiations of, any merger, sale of company assets, consolidation or restructuring, financing, or acquisition of all or a portion of our business by or to another company; and/or

**3.5.** Where you have provided your consent to us sharing or transferring your Personal Data (e.g., where you opt-in to optional additional services or functionality; where you provided your consent for identity verification via our third party provider).

**3.6.** If you want to receive the list of the current recipients of your Personal Data, please make your request by contacting us to [privacy@decart.ai](mailto:privacy@decart.ai).

## 4. ADDITIONAL INFORMATION REGARDING TRANSFERS OF PERSONAL DATA

**4.1. Internal transfers:** Transfers to affiliates of Decart will be covered by an internal processing agreement entered into by the affiliates of Decart (an intra-group data processing agreement) which contractually obliges each member to ensure that Personal Data receives an adequate and consistent level of protection wherever it is transferred to.

**4.2. External transfers:** Where we transfer your Personal Data outside of EU/EEA (for example to third parties who provide us with services), we will generally obtain contractual commitments from them to protect your Personal Data.

**4.3. Transfer mechanisms:** When Decart engages transfers of personal information, it relies on Adequacy Decisions adopted by the European Commission based on Article 45 of the GDPR, Standard Contractual Clauses laid down by the European Commission, or any other approved transfer mechanism (such as the recipient's registration with the EU-US Data Privacy Framework). Decart continually monitors the circumstances surrounding such transfers to ensure that these maintain, in practice, a level of protection that is essentially equivalent to the level of protection guaranteed by the GDPR.

## 5. YOUR PRIVACY RIGHTS. HOW TO DELETE YOUR ACCOUNT

**5.1. Rights:**

**5.1.1.** The following rights (which may be subject to certain exemptions or derogations) shall apply to certain individuals (some of which only apply to individuals protected by the GDPR):

* You have a right to access Personal Data held about you. Your right of access may normally be exercised free of charge, however we reserve the right to charge an appropriate administrative fee where permitted by applicable law;
* You have the right to request that we rectify any Personal Data we hold that is inaccurate or misleading;
* You have the right to request the erasure/deletion of your Personal Data (e.g. from our records). Please note that there may be circumstances in which we are required to retain your Personal Data, for example for the establishment, exercise or defense of legal claims;
* You have the right to object, to or to request restriction, of the processing;
* You have the right to data portability. This means that you may have the right to receive your Personal Data in a structured, commonly used and machine-readable format, and that you have the right to transmit that data to another controller;
* You have the right to object to profiling;
* You have the right to withdraw your consent at any time. Please note that there may be circumstances in which we are entitled to continue processing your data, in particular if the processing is required to meet our legal and regulatory obligations. Also, please note that the withdrawal of consent shall not affect the lawfulness of processing based on consent before its withdrawal;
* You also have a right to request certain details of the basis on which your Personal Data is transferred outside the European Economic Area, but data transfer agreements and/or other details may need to be partially redacted for reasons of commercial confidentiality;
* You have a right to lodge a complaint with your local data protection supervisory authority (i.e., your place of habitual residence, place or work or place of alleged infringement) at any time or before the relevant institutions in your place of residence. We ask that you please attempt to resolve any issues with us before you contact your local supervisory authority and/or relevant institution.

**5.2.** You can exercise your rights by contacting us at [contact@decart.ai](mailto:contact@decart.ai). You may use an authorized agent to submit a request on your behalf if you provide the authorized agent written permission signed by you. Subject to legal and other permissible considerations, we will make every reasonable effort to honor your request promptly in accordance with applicable law or inform you if we require further information in order to fulfil your request. When processing your request, we may ask you for additional information to confirm or verify your identity and for security purposes, before processing and/or honoring your request. We reserve the right to charge a fee where permitted by law, for instance if your request is manifestly unfounded or excessive. In the event that your request would adversely affect the rights and freedoms of others (for example, would impact the duty of confidentiality we owe to others) or if we are legally entitled to deal with your request in a different way than initial requested, we will address your request to the maximum extent possible, all in accordance with applicable law.

**5.3. Deleting your account:** Should you ever decide to delete your account, you may do so by emailing [contact@decart.ai](mailto:contact@decart.ai). If you terminate your account, any association between your account and Personal Data we store will no longer be accessible through your account. However, given the nature of sharing on certain services, any public activity on your account prior to deletion will remain stored on our servers and will remain accessible to the public.

**5.4. Marketing emails – opt-out:** You may choose not to receive email communications from us by sending a single email with the subject "BLOCK" to [contact@decart.ai](mailto:contact@decart.ai). Please note that the email must come from the email account you wish to block OR if you receive an unwanted email from us, you can use the unsubscribe link found at the bottom of the email to opt out of receiving future emails, and we will process your request within a reasonable time after receipt.

## 6. USE BY CHILDREN

We do not offer our products or services for use by children and, therefore, we do not knowingly collect Personal Data from, and/or about children under the age of thirteen (13). If you are under the age of eighteen (18), do not provide any Personal Data to us without the involvement of a parent or a guardian. For the purposes of the GDPR, we do not intend to offer information society services directly to children. In the event that we become aware that you provide Personal Data in violation of applicable privacy laws, we reserve the right to delete it. If you believe that we might have any such information, please contact us at [contact@decart.ai](mailto:contact@decart.ai)

## 7. INTERACTION WITH THIRD PARTY PRODUCTS

We enable you to interact with third party websites, mobile software applications and products or services that are not owned or controlled by us (each a "Third Party Service"). We are not responsible for the privacy practices or the content of such Third Party Services. Please be aware that Third Party Services can collect Personal Data from you. Accordingly, we encourage you to read the terms and conditions and privacy policies of each Third Party Service.

## 8. ANALYTIC TOOLS

* **Google Analytics.** The Website may use a tool called "Google Analytics" to collect information about use of the Website. Google Analytics collects information such as how often users visit this Website, what pages they visit when they do so, and what other websites they used prior to coming to this Website. We use the information we get from Google Analytics to maintain and improve the Website and our products. We do not combine the information collected through the use of Google Analytics with Personal Information we collect. Google's ability to use and share information collected by Google Analytics about your visits to this Website is restricted by the Google Analytics Terms of Service, available at [https://marketingplatform.google.com/about/analytics/terms/us/](https://marketingplatform.google.com/about/analytics/terms/us/), and the Google Privacy Policy, available at [http://www.google.com/policies/privacy/](http://www.google.com/policies/privacy/). You may learn more about how Google collects and processes data specifically in connection with Google Analytics at [http://www.google.com/policies/privacy/partners/](http://www.google.com/policies/privacy/partners/). You may prevent your data from being used by Google Analytics by downloading and installing the Google Analytics Opt-out Browser Add-on, available at [https://tools.google.com/dlpage/gaoptout/](https://tools.google.com/dlpage/gaoptout/).

* **PostHog.** In order to better understand our users' needs and to optimize this Platform and experience, the Platform uses "PostHog". PostHog collects user experience data of your usage of our Platform and surfaces issues to engineering, product and marketing teams. PostHog uses cookies and other technologies to collect data on our users' behavior and their devices (in particular device's IP address), device screen size, device type (unique device identifiers), browser information, geographic location (country only), preferred language used to display our Platform). For further details, please see PostHog privacy policy available at: [https://posthog.com/privacy](https://posthog.com/privacy).

* We use log files. We use such information to analyze trends, administer the Website, track users' movement around the Website, and gather demographic information.

* We reserve the right to remove or add new analytic tools.

## 9. SPECIFIC PROVISIONS APPLICABLE UNDER CALIFORNIA PRIVACY LAW

**9.1. California Privacy Rights:** California Civil Code Section 1798.83 permits our customers who are California residents to request certain information regarding our disclosure of Personal Information to third parties for their direct marketing purposes. To make such a request, please send an email to [privacy@decart.ai](mailto:privacy@decart.ai). Please note that we are only required to respond to one request per customer each year.

**9.2. Deletion of Content from California Residents:** If you are a California resident under the age of 18 and a registered user, California Business and Professions Code Section 22581 permits you to remove content or Personal Information you have publicly posted. If you wish to remove such content or Personal Information and you specify which content or Personal Information you wish to be removed, we will do so in accordance with applicable law. Please be aware that after removal you may not be able to restore removed content. In addition, such removal does not ensure complete or comprehensive removal of the content or Personal Information you have posted and that there may be circumstances in which the law does not require us to enable removal of content.

## 10. CONTACT US

If you have any questions, concerns or complaints regarding our compliance with this notice and the data protection laws, or if you wish to exercise your rights, we encourage you to first contact us at [contact@decart.ai](mailto:contact@decart.ai).


# Status
Source: https://docs.platform.decart.ai/resources/status





# Terms of Service
Source: https://docs.platform.decart.ai/resources/terms-of-service



**Last updated: July 26, 2026**

Welcome to Decart's Image & Video Models accessible via [https://decart.ai/](https://decart.ai/) (together with its subdomains, Materials, Marks, features and services, the "Websites") or to the respective mobile application (the "App"; collectively, the "Platform").

Please read the following Terms of Service carefully before using this Platform so that you are aware of your legal rights and obligations with respect to Decart.ai, Inc. ("Decart.ai", "we", "our" or "us"). By accessing or using the Platform, you expressly acknowledge and agree that you are entering a legal agreement with us and have understood and agree to comply with, and be legally bound by, these Terms of Service, together with the [Privacy Policy](/resources/privacy-policy) and [Acceptable Use Policy](/resources/aup) (collectively, the "Terms"). To the maximum extent permitted by law, you hereby waive any applicable rights to require an original (non-electronic) signature or delivery or retention of non-electronic records. If you do not agree to be bound by these Terms please do not access or use the Platform. If you are accessing Decart.ai's models via our application programming interface ("API Platform") please read our [API Terms of Service](/resources/api-terms) which governs the use of the API Platform.

Please read the following carefully before using the Platform or the Content (as defined below) provided by the Platform.

**Notably, these Terms are a binding agreement and include mandatory arbitration and class action/jury trial waiver provision that requires the use of arbitration on an individual basis to resolve disputes, rather than jury trials or class actions and limits the remedies available to you in the event of certain disputes.**

By accepting these Terms, either by clicking a box indicating your acceptance, by downloading our mobile application, establishing an account, or using the platform, you agree that you: (a) have read and understood these Terms; (b) represent that you are at least 13 years old and, if you are a minor, that you have permission from your parent or legal guardian to create an account and agree to these Terms; and (c) agree that you are legally bound by these Terms.

## 1. Background

By using the Platform provided by Decart.ai, you will be able to submit or choose prompts, and/or photos, videos and other materials (collectively "Input") and generate text, images, sessions and other output based on the Input ("Output") (Input and Output are collectively called "Content").

## 2. Modification

To the maximum extent permitted by law, we reserve the right, at our discretion, to change these Terms at any time. Changes will be effective ten (10) days following posting of the revised Terms on the Platform. Your continued use of the Platform after posting a revised version of the Terms means that you accept those changes. To the maximum extent permitted by law, we also reserve the right to change any service provided on the Platform or the Platform itself at our sole discretion, at any time. Such change will be effective immediately.

## 3. Ability to Accept Terms

The Platform is only intended for individuals aged thirteen (13) years or older. If you are under 13 years please do not visit or use the Platform. We reserve the right to suspend access to the Platform to any person in breach of this Section.

## 4. Platform Access

4.1 For such time as these Terms are in effect, we hereby grant you permission to visit and use the Platform provided that you comply with these Terms and applicable law and provided that you do not violate, infringe, or misappropriate any third party right (including, without limitation, intellectual property rights or privacy rights).

4.2 You shall not use the Materials to improve any large language model or other AI or machine learning system.

## 5. Restrictions

You shall not: (i) copy, distribute or modify any part of the Platform (including without limitation, developing, supporting or using software, devices, scripts, robots or any other means or processes (such as crawlers, browser plugins and add-ons or any other technology) to scrape or copy the Platform, including content or other data thereon) without our prior written authorization; (ii) use, modify, create derivative works of, transfer (by sale, resale, license, sublicense, download or otherwise), reproduce, distribute, display or disclose Materials (defined below); (iii) disrupt servers or networks connected to the Platform; (iv) use or launch any automated system (including without limitation, "robots" and "spiders") to access the Platform; (v) reverse engineer, disassemble, decompile, decode, adapt, or otherwise attempt to derive or gain access to any Platform's source code, in whole or in part; (vi) circumvent, disable or otherwise interfere with security-related features of the Platform or features that prevent or restrict use or copying of any Materials or that enforce limitations on use of the Platform; and/or (vii) input illegal Content, as detailed in Section 8.2 below, or use the Platform or the Content in violation of these Terms, applicable law or third-party rights.

## 6. Account

In order to use some of the services of the Platform, you may have to create an account ("Account"). You agree not to create an Account for anyone else or use the account of another person without their permission. When creating your Account, you must provide lawful, accurate and complete information. You are solely responsible for the activity that occurs in your Account, and you must keep your Account password secure. You must notify Decart.ai immediately of any breach of security or unauthorized use of your Account. As between you and Decart.ai, you are solely responsible and liable for the activity that occurs in connection with your Account. If you wish to delete your Account you may send an email request to Decart.ai at [contact@decart.ai](mailto:contact@decart.ai).

## 7. Payments to Decart.ai

Decart.ai charges a fee for use of certain features as indicated on the Platform. Payment of this fee will provide you with a certain number of credits (which will be redeemable for in-Platform purchases), and must be used within 90 days of purchase, after which the credits will expire and be forfeited. Credits are non-refundable. You will not be charged for any such access or use of the Platform unless you first agree to such charges, but please be aware that any failure to pay applicable charges may result in you not having access to some or all of the Platform. We reserve the right, at our sole discretion, to revoke, cancel, or restrict the use of any credits previously issued to you at any time, including but not limited to instances of breach of these Terms, such as any violation of Section 8.2 regarding unethical use of our services. Credits may also be limited to certain services or products at our discretion. Our decisions regarding credits may be made arbitrarily and are not subject to appeal or review.

## 8. Content

### 8.1. Your Content

As between the parties and to the extent permitted by applicable law, you own your Input. Subject to your compliance with these Terms, Decart.ai hereby assigns to you all its right, title and interest in and to Output. This means you can use your Content for any purpose, including commercial purposes such as sale or publication, but only if you comply with these Terms at all times. Decart.ai may use Content to develop, improve (including to train our AI models), provide and maintain the Platform and in furthering its business, comply with applicable law, defend and enforce our rights or the rights of other users, and enforce our policies.

### 8.2. Your Responsibility

To the maximum extent permitted, you are solely responsible for the Content, including for ensuring that it does not violate any applicable law, these Terms, any third-party rights, or otherwise any unethical, offensive, insulting, harmful, or abusive behavior. You represent and warrant that you own or have all the necessary rights and permissions to provide the Input and use it in the context of the Platform. Without limiting the foregoing, you are responsible for determining and complying with any transparency or disclosure requirements applicable to AI-generated or manipulated Content, including Content constituting a "deep fake" under applicable law. You must not remove, obscure, disable or circumvent any legally required disclosure or any watermark, label, provenance information or other machine-readable marker applied by or through the Platform.

### 8.3. Processing of Personal Data

If you use the Platform to process personal data of third parties, you must provide legally adequate privacy notices, obtain all necessary consents and comply with all the necessary obligations for the processing of such data to be lawful at all times in the context of the Platform, and you represent and warrant to us that you are processing such data in full compliance with applicable laws and regulations.

### 8.4. Similarity of Output

You acknowledge and understand that, due to the nature of machine learning and generative artificial intelligence, Output may not be unique across users and the Platform may generate the same or similar output for a third party. Other users may also ask similar questions/queries and receive the same or similar responses. Responses that are requested by and generated for other users are not considered your Content. To the maximum extent permitted by law, you shall release us from any liability in relation to the foregoing.

### 8.5. Use of Content

We may use Content to help develop and improve the Platform and Decart.ai's business, including its products and services. Furthermore, you grant us the right to use the Content for marketing and/or promotional purposes including without limitation, on our Platform, and on social media. Decart.ai is not responsible and shall not be held liable for any claim arising from your use of the Content in any manner.

### 8.6. Accuracy

Artificial intelligence and machine learning are rapidly evolving fields of study. We are constantly working to improve our Platform to make it more accurate, reliable, safe, and beneficial. Given the probabilistic nature of machine learning, the use of our Platform may in some situations result in incorrect Output that does not accurately reflect real people, places, or facts or achieve the desired goal or purpose. You should evaluate the accuracy of any Output as appropriate for your use case, including by using human review of the Output. To the maximum extent permitted by law, we shall not be responsible or held liable for the Output or your reliance on the Output.

## 9. Intellectual Property Rights

### 9.1. Materials and Marks

The: (i) Platform and the content on the Platform, including without limitation, the Intellectual Property Rights (defined below), text, documents, articles, brochures, descriptions, products, software, graphics, photos, sounds, videos, interactive features and services, other than the Content (collectively, the "Materials"); and (ii) trademarks, service marks and logos contained therein ("Marks"), are the property of Decart.ai and/or its licensors and may be protected by applicable copyright or other intellectual property laws and treaties. "Decart.ai", the Decart.ai logo and other marks are Marks of Decart.ai or its affiliates. All other trademarks, service marks, and logos used on the Platform are the trademarks, service marks, or logos of their respective owners. We reserve all rights not expressly granted in and to the Platform and the Materials. "Intellectual Property Rights" means any and all rights, titles and interests, whether foreign or domestic, in and to any and all trade secrets, patents, copyrights, service marks, trademarks, know-how, or similar intellectual property rights, as well as any and all moral rights, rights of privacy, publicity and similar rights of any type under the laws or regulations of any governmental, regulatory or judicial authority, foreign or domestic.

### 9.2. Use of Materials

Materials are provided to you for your information and you may only use them for your personal non-commercial use only and may not be used, modified, copied, distributed, transmitted, broadcast, displayed, sold, licensed, de-compiled, or otherwise exploited for any other purposes whatsoever without our prior written consent. If you download or print a copy of the Materials you must retain all copyright and other proprietary notices contained therein.

### 9.3. Feedback

We appreciate feedback, comments, ideas, proposals and suggestions for improvements. If you provide any of these things, we may implement it or use it without restrictions, obligations, or any compensation to you.

### 9.4

If you institute litigation or other proceedings against Decart.ai or any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Materials or Output, or any portion of any of the foregoing, infringes the intellectual property or other rights owned or licensable by you, then any licenses granted to you under these Terms shall terminate as of the date such litigation or claim is filed or instituted. You will indemnify and hold harmless Decart.ai from and against any claim by any third party arising out of or related to your use or distribution of the Materials or Output.

## 10. Third Party Content

10.1. The Platform enables you to view, access, link to, and use content from Third Party Sources (defined below) that are not owned or controlled by us ("Third Party Content"). The Platform may also enable you to communicate and interact with Third Party Sources. "Third Party Source(s)" means: (i) third party platforms, services and technologies; and (ii) our partners and customers.

10.2. We are not affiliated with and have no control over any Third Party Sources. We do not assume any responsibility for the content, terms of use, privacy policies, actions or practices of, any Third Party Sources. Please read the terms of use and privacy policy of any Third Party Source that you interact with before you engage in any such activity.

10.3. We are not responsible for, and we expressly disclaim all warranties regarding, the accuracy, appropriateness, usefulness, safety, or Intellectual Property Rights of, or relating to, any Third Party Content.

10.4. We do not endorse any advertising, promotions, campaigns, products, services or other materials that are included in any Third Party Content or that is communicated to you from a Third Party Source.

10.5. By using the Platform you may be exposed to Third Party Content that is inaccurate, offensive, indecent or objectionable. You always have the choice of deciding whether or not to interact with a Third Party Source or to view and use Third Party Content. Your interaction with a Third Party Source and your use of, and reliance upon, any Third Party Content is at your sole discretion and risk.

10.6. You agree to waive, and hereby do waive, any legal or equitable rights or remedies you may have against Decart.ai, and release Decart.ai from any and all liability, arising from your use of and interaction on any Third Party Content and from your interaction with any Third Party Source. If you have any query or complaint regarding a Third Party Source or any Third Party Content, you agree to contact the Third Party Source directly.

## 11. Third Party Open Source Software

Portions of the Platform may include third party open source software that is subject to third party terms and conditions ("Third Party Terms"). If there is a conflict between any Third Party Terms and the terms of these Terms, then the Third Party Terms shall prevail but solely in connection with the related third party open source software. Notwithstanding anything in these Terms to the contrary, Decart.ai makes no warranty or indemnity hereunder with respect to any third party open source software.

## 12. Information Description

We attempt to be as accurate as possible. However, we cannot and do not warrant that the Materials available on the Platform are accurate, complete, reliable, current, or error-free. We reserve the right to make changes in or to the Materials, or any part thereof, in our sole judgment, without the requirement of giving any notice prior to or after making such changes to the Materials. Your use of the Materials, or any part thereof, is made solely at your own risk and responsibility.

## 13. Disclosure

We reserve the right to access, read, preserve, and disclose any information that we obtain in connection with the Platform, and your use thereof, which we reasonably believe is necessary to: (i) satisfy any applicable law, regulation, legal process, subpoena or governmental request; (ii) enforce these Terms, including to investigate potential violations of them; (iii) detect, prevent or otherwise address fraud, security or technical issues; (iv) respond to user support requests; or (v) protect the rights, property or safety of Decart.ai, its users or the public.

## 14. Links

14.1. The Platform may contain links, and may enable you to post content, to third party platforms that are not owned or controlled by Decart.ai. We are not affiliated with, have no control over, and assume no responsibility for the content, privacy policies, or practices of, any third party platforms. You: (i) are solely responsible and liable for your use of and linking to third party platforms and any content that you may send or post to a third party platform; and (ii) expressly release Decart.ai from any and all liability arising from your use of any third party platform. Accordingly, we encourage you to read the terms and conditions and privacy policy of each third party platform that you may choose to visit.

14.2. Decart.ai permits you to link to the Platform provided that: (i) you link to but do not replicate any page on this Platform; (ii) the hyperlink text shall accurately describe the Materials as it appears on the Platform; (iii) you shall not misrepresent your relationship with Decart.ai or present any false information about Decart.ai and shall not imply in any way that we are endorsing any services or products, unless we have given you our express prior consent; (iv) you shall not link from a Platform ("Third Party Platform") which prohibits linking to third parties; (v) such Third Party Platform does not contain content that (a) is offensive or controversial (both at our discretion), or (b) infringes any intellectual property, privacy rights, or other rights of any person or entity; and/or (vi) you comply with these Terms and applicable law.

## 15. Privacy

For information on how we use your Personal Data, please read our Privacy Policy available on the Platform or [here](/resources/privacy-policy).

## 16. Copyright and Content Policy

It is our policy to respect the legitimate rights of copyright and other intellectual property owners, and we will respond to clear notices of alleged copyright infringement in accordance with our Copyright and Content Policy attached hereto as Schedule B.

## 17. Warranty Disclaimers

17.1. This section applies whether or not the services provided under the Platform are for payment. Applicable law may not allow the exclusion of certain warranties, so to that extent certain exclusions set forth herein may not apply.

17.2. THE PLATFORM IS PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS, AND WITHOUT WARRANTIES OF ANY KIND EITHER EXPRESS OR IMPLIED. DECART.AI HEREBY DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, TITLE, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND THOSE ARISING BY STATUTE OR FROM A COURSE OF DEALING OR USAGE OF TRADE. DECART.AI DOES NOT GUARANTEE THAT THE PLATFORM OR THE CONTENT WILL BE FREE OF BUGS, SECURITY BREACHES, OR VIRUS ATTACKS. THE PLATFORM AND THE CONTENT MAY OCCASIONALLY BE UNAVAILABLE FOR ROUTINE MAINTENANCE, UPGRADING, OR OTHER REASONS. YOU AGREE THAT DECART.AI WILL NOT BE HELD RESPONSIBLE FOR ANY CONSEQUENCES TO YOU OR ANY THIRD PARTY THAT MAY RESULT FROM TECHNICAL PROBLEMS OF THE INTERNET, SLOW CONNECTIONS, TRAFFIC CONGESTION OR OVERLOAD OF OUR OR OTHER SERVERS. WE DO NOT WARRANT, ENDORSE OR GUARANTEE ANY CONTENT, PRODUCT, OR SERVICE THAT IS FEATURED OR ADVERTISED ON THE PLATFORM BY A THIRD PARTY.

17.3. THE PLATFORM IS DESIGNED TO PROVIDE YOU WITH ADVANCED ARTIFICIAL INTELLIGENCE PROCESSING CAPABILITIES. WHILE WE STRIVE TO ENSURE THAT THE PLATFORM OPERATES IN AN ACCURATE, FAIR AND UNBIASED MANNER, IT IS IMPORTANT TO ACKNOWLEDGE THAT NO ARTIFICIAL INTELLIGENCE SYSTEM IS PERFECT. YOU HEREBY ACKNOWLEDGE THAT YOU HAVE READ, UNDERSTOOD, AND AGREED THAT THE PLATFORM MAY INADVERTENTLY PRODUCE CONTENT THAT IS INACCURATE, BIASED, OFFENSIVE, OR OTHERWISE INAPPROPRIATE. YOU AGREE THAT DECART.AI WILL NOT BE HELD RESPONSIBLE FOR ANY CONSEQUENCES TO YOU OR ANY THIRD PARTY THAT MAY RESULT FROM CONTENT OF THE PLATFORM.

17.4. WHILE THE PLATFORM MAY PROVIDE ACCESS TO CERTAIN INFORMATION, THE PLATFORM CANNOT, AND IS NOT INTENDED TO, PROVIDE ANY PROFESSIONAL ADVICE OF ANY KIND. YOU ARE SOLELY RESPONSIBLE AND LIABLE FOR YOUR USE OF THE PLATFORM AND/OR USE OF THE CONTENT OR ANY INFORMATION PROVIDED BY THE PLATFORM.

17.5. EXCEPT AS EXPRESSLY STATED IN OUR PRIVACY POLICY, DECART.AI DOES NOT MAKE ANY REPRESENTATIONS, WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED, AS TO THE SECURITY OF ANY INFORMATION YOU MAY PROVIDE OR ACTIVITIES YOU ENGAGE IN DURING THE COURSE OF YOUR USE OF THE PLATFORM.

## 18. Limitation of Liability

18.1. TO THE FULLEST EXTENT PERMISSIBLE BY LAW, DECART.AI SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, EXEMPLARY, SPECIAL, CONSEQUENTIAL OR INCIDENTAL DAMAGES OF ANY KIND, OR FOR ANY LOSS OF DATA, REVENUE, PROFITS OR REPUTATION, ARISING UNDER THESE TERMS OR OUT OF YOUR USE OF, OR INABILITY TO USE, THE PLATFORM, EVEN IF DECART.AI HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR LOSSES. Some jurisdictions do not allow the limitation or exclusion of liability for incidental or consequential damages, so the above limitations may not apply to you.

18.2. IN NO EVENT SHALL THE AGGREGATE LIABILITY OF DECART.AI FOR ANY DAMAGES ARISING UNDER THESE TERMS OR OUT OF YOUR USE OF, OR INABILITY TO USE, THE PLATFORM EXCEED THE TOTAL AMOUNT OF FEES, IF ANY, PAID BY YOU TO DECART.AI FOR USING THE PLATFORM DURING THE THREE (3) MONTHS PRIOR TO BRINGING THE CLAIM.

## 19. Indemnity

To the maximum extent permitted by law, you agree to defend, indemnify and hold harmless Decart.ai and our affiliates, and our respective officers, directors, employees and agents, from and against any and all claims, damages, obligations, losses, liabilities, costs and expenses (including but not limited to attorney's fees) arising from: (i) your use of, or inability to use, the Platform; (ii) your Content and/or any use thereof; (iii) the Materials; (iv) your violation or any violation of proprietary rights and/or any other third party rights, including without limitation Intellectual Property Rights or privacy rights; (v) your violation of these Terms or other terms from third parties associated with Third Party Content; and/or (vi) any other violation of any other applicable law or regulation.

## 20. Term and Termination

These Terms are effective until terminated by Decart.ai or you. Decart.ai, in its sole discretion, has the right to terminate these Terms and/or your access to the Platform, or any part thereof, immediately at any time and with or without cause (including, without any limitation, for a breach of these Terms). Without derogating from any other provision of these Terms, in the event of any breach of these Terms, Decart.ai reserves the right to suspend your access to the Platform and its services temporarily until such breach is cured, or indefinitely if deemed to be permitted by Decart.ai. Suspension may occur without prior notice and is at the sole discretion of Decart.ai. Decart.ai shall not be liable to you or any third party for termination or suspension of the Platform, or any part thereof. If you object to any term or condition of these Terms, or any subsequent modifications thereto, or become dissatisfied with the Platform in any way, your only recourse is to immediately discontinue use of the Platform. Upon termination of these Terms, you shall cease all use of the Platform. This Section 20 and Sections 8 (Content), 9 (Intellectual Property Rights), 15 (Privacy) to 19 (Indemnity), and 21 (Independent Contractors) to 26 (No Waiver) shall survive termination of these Terms.

## 21. Independent Contractors

You and Decart.ai are independent contractors. Nothing in these Terms creates a partnership, joint venture, agency, or employment relationship between you and Decart.ai. You must not under any circumstances make, or undertake, any warranties, representations, commitments or obligations on behalf of Decart.ai.

## 22. Assignment

These Terms, and any rights and licenses granted hereunder, may not be transferred or assigned by you but may be assigned by Decart.ai without restriction or notification to you.

## 23. Mandatory Arbitration

23.1. In the event of any claim, controversy, or dispute under or otherwise in connection with these Terms (a "Dispute"), such Dispute shall be resolved exclusively by arbitration in accordance with Schedule A attached hereto. However, if the Dispute is not subject to arbitration (either because you opted-out of the arbitration in the manner described in Schedule A, or because a court of competent jurisdiction determined that the agreement to arbitrate does not apply to you or the Dispute) then the Dispute shall be subject to the exclusive jurisdiction and venue of the competent courts located in the State of New York, and the Parties hereby irrevocably and unconditionally submit to the personal jurisdiction of such courts and waive any jurisdictional, improper venue, inconvenient forum, or other objections to such jurisdiction and venue.

23.2. Regardless of any law to the contrary, you agree that any claim or cause of action arising under, or otherwise in connection with, these Terms must be filed within ONE (1) YEAR after such claim or cause of action arose, or else you agree that such claim or cause of action will be barred forever. Any claims or damages that you make hereunder shall only be enforceable against Decart.ai, and not any other entity (such as Decart.ai affiliates) or Decart.ai officers, directors, representatives, employees, or agents. Moreover, if you are a consumer (as defined in the laws of your jurisdiction), these Terms are not intended to, and shall not, exclude or limit any mandatory rights you may have under the consumer protection laws of your jurisdiction.

## 24. Governing Law

These Terms and the relationship between you and Decart.ai shall be governed by and construed in accordance with the laws of the State of New York, without regard to its principles of conflict of laws.

## 25. Severability

These Terms shall constitute the entire agreement between you and Decart.ai concerning the Platform. If any provision of these Terms is deemed invalid by a court of competent jurisdiction, the invalidity of such provision shall not affect the validity of the remaining provisions of these Terms, which shall remain in full force and effect.

## 26. No Waiver

No waiver of any term of these Terms shall be deemed a further or continuing waiver of such term or any other term, and a party's failure to assert any right or provision under these Terms shall not constitute a waiver of such right or provision. Nothing in these Terms is intended to cancel or limit your statutory rights that cannot be cancelled or limited by applicable law; however, these Terms will be interpreted and applied to the maximum extent permitted by law.

## 27. Distributor Requirements and Usage Rules

### 27.1. Apple

If you download the App from the Apple, Inc. ("Apple") App Store (or in any event if you download an Apple iOS App) then, without derogating from the warranty disclaimers and limitation of liability as set forth in these Terms:

27.1.1. You acknowledge and agree that:

(a) These Terms are concluded between Decart.ai and you only, and not with Apple, and Decart.ai and its licensors, and not Apple, are solely responsible for the App and the content thereof. Your use of the App is also subject to the Usage Rules established by Apple, including those set forth in the Apple App Store Terms of Service, effective as of the date that you enter into these Terms. The license granted herein is limited to a non-transferable right to use the App on an Apple iPhone, iPod Touch, iPad, or other Apple-branded product that you own or control and that runs the iOS; Decart.ai is solely responsible for providing any maintenance and support services with respect to the App, as specified in these Terms, or as required under applicable law. Apple has no obligation whatsoever to furnish any maintenance and support services with respect to the App; Decart.ai is solely responsible for any product warranties, whether express or implied by law, to the extent not effectively disclaimed. In the event of any failure of the App to conform to any applicable warranty, you may notify Apple, and Apple will, to the extent applicable, refund any purchase price paid (if any) by you for the App to you. To the maximum extent permitted by applicable law, Apple will have no other warranty obligation whatsoever with respect to the App, and, any other claims, losses, liabilities, damages, costs or expenses attributable to any failure to conform to any warranty will be Decart.ai's sole responsibility; Decart.ai, and not Apple, is responsible for addressing any product claims you, or any third party, may have relating to the App or your possession and/or use of the App, including, but not limited to: (a) product liability claims; (b) any claim that the App fails to conform to any applicable legal or regulatory requirement; and (c) claims arising under consumer protection or similar legislation.

(b) In the event of any third party claim that the App or your possession and use of the App infringes that third party's intellectual property rights, Apple shall not be responsible for the investigation, defense, settlement and discharge of any such intellectual property infringement claim;

(c) Apple, and its subsidiaries, are third party beneficiaries of these Terms, and that, upon your acceptance of the terms and conditions of these Terms, Apple will have the right (and will be deemed to have accepted the right) to enforce these Terms against you as a third party beneficiary thereof.

(d) You represent and warrant that: (a) you are not located in a country that is subject to a U.S. Government embargo, or that has been designated by the U.S. Government as a "terrorist supporting" country; and (b) you are not listed on any U.S. Government list of prohibited or restricted parties.

(e) If you have any questions, complaints, or claims regarding the App, please contact Decart.ai at:

Email: [contact@decart.ai](mailto:contact@decart.ai).\
Telephone: +1 (302) 499-2230\
Address: 1007 North Orange Street, 10th Floor; Wilmington, DE 19801, USA

(f) By entering into these Terms you, to the extent legally permitted, hereby waive any applicable law requiring that these Terms be localized to meet your language and other local requirements. To the extent that the foregoing is not permitted, you agree to be bound by the standard Apple Licensed Application End User License Agreement which is part of the Apple App Store Terms of Service, at [www.apple.com/legal/itunes/us/terms.html#SERVICE](http://www.apple.com/legal/itunes/us/terms.html#SERVICE) (as amended from time to time).

***

# SCHEDULE A

## Mandatory Arbitration

Decart.ai wants to address your concerns without the need for a formal legal dispute. Before filing a claim against Decart.ai, you agree to try to resolve the Dispute informally by contacting [contact@decart.ai](mailto:contact@decart.ai). If a Dispute is not resolved within 30 days after the email noting the Dispute is sent, you may initiate proceedings, as set forth in this Schedule A.

You and Decart.ai agree that these Terms affect interstate commerce and that the enforceability of this Schedule A shall be both substantively and procedurally governed by and construed and enforced in accordance with the Federal Arbitration Act, 9 U.S.C. § 1 et seq. (the "FAA"), to the maximum extent permitted by applicable law.

Unless the Parties expressly agree otherwise in writing, the arbitration shall take place in-person in New York, New York, except that if telephonic or other remote electronic means are available and permissible, then you may elect to conduct the arbitration via such means. You agree that: (a) any arbitration will occur in New York City, New York, (b) arbitration will be conducted confidentially by a single arbitrator in accordance with the Commercial Arbitration Rules and the Supplementary Procedures for Consumer Related Disputes (the "AAA Rules") then in effect, except as modified by this "Dispute Resolution" section, and (c) that the state or federal courts of the State of New York, have exclusive jurisdiction over any appeals and the enforcement of an arbitration award. The arbitrator must honor the terms and conditions of these Terms (including, but not limited to, all liability exclusions and limitations), and shall not make any award or decision that is contrary to, or in excess of, what these Terms provide.

The AAA Rules are available at [https://www.adr.org/Rules](https://www.adr.org/Rules) or by contacting the AAA at 800-778-7879. By agreeing to be bound by these Terms, you either (a) acknowledge and agree that you have read and understand the rules of AAA, or (b) waive your opportunity to read the rules of AAA and any claim that the rules of AAA are unfair or should not apply for any reason.

The arbitrator's decision must be in writing, and will include the essential findings and conclusions upon which the award is based. Judgment on the arbitration award may be entered in any court having jurisdiction thereof. In the event any litigation should arise between you and Decart.ai in any court in a proceeding to vacate or enforce an arbitration award, YOU AND DECART.AI HEREBY IRREVOCABLY WAIVE ALL RIGHTS TO A JURY TRIAL, instead electing that the proceeding be resolved by a judge. The arbitrator may award declaratory or injunctive relief only in favor of the plaintiff/claimant and only to the extent necessary to provide relief warranted by the plaintiff's/claimant's individual claim.

Regardless of who initiates arbitration for a Dispute, you will always remain responsible for your costs relating to counsel, experts, witnesses, and travel to the arbitration. We will not seek attorneys' fees and costs in arbitration (unless the arbitrator determines the claims are frivolous). If Decart.ai initiates an arbitration for a Dispute, Decart.ai will pay all administrative fees and costs related to the arbitration, including all professional fees for the arbitrator's services.

All aspects of the arbitration proceeding, including but not limited to the decision and award of the arbitrator and compliance therewith, shall be strictly confidential. The parties agree to maintain its confidentiality, unless (and in such cases, only to the extent) otherwise required by applicable law. This paragraph shall not prevent a party from submitting to a court any information necessary to enforce an arbitration award or to seek equitable relief.

YOU ACKNOWLEDGE AND AGREE THAT, EVEN IF ANYTHING IN THE AAA RULES PERMITS OTHERWISE AND EVEN IF YOU OPT-OUT OF THESE TERMS TO ARBITRATE:

A. YOU AND DECART.AI ARE HEREBY EACH IRREVOCABLY WAIVING THE RIGHT TO PARTICIPATE (FOR EXAMPLE, AS A CLASS REPRESENTATIVE OR CLASS MEMBER) IN A CLASS ACTION, CLASS ARBITRATION, OR OTHER CLASS-WIDE OR REPRESENTATIVE ACTION OR PROCEEDING, AND THAT YOU MAY ONLY BRING A CLAIM IN YOUR INDIVIDUAL CAPACITY; AND

B. NO ARBITRATION WILL BE JOINED TO ANY OTHER ARBITRATION, AND THE ARBITRATOR MAY NOT CONSOLIDATE ANY INDIVIDUAL PARTY'S DISPUTE WITH ANY OTHER PARTY'S DISPUTE.

OPT-OUT: You can choose to reject these Terms to arbitrate ("Opt-out") by emailing [contact@decart.ai](mailto:contact@decart.ai) within thirty (30) days after the date you agree to these Terms for the first time. The Opt-out email you send to us must state that you do not agree to these Terms to arbitrate and must include your name, address, phone number, and email address. Providing an Opt-out notice is the only way you can opt-out of these Terms to arbitrate. If you Opt-out of these Terms to arbitrate, all other provisions of these Terms will continue to apply, and you will not be permitted to invoke these Terms to arbitrate to resolve any Dispute with Decart.ai.

To the extent any provision of this Schedule A is held by a court of competent jurisdiction to be illegal, invalid or unenforceable, you and Decart.ai agree that the provisions of Section 25 (Severability) shall apply.

***

# SCHEDULE B

## Copyright and Content Policy

### 1. Removal of Content

It is the policy of Decart.Ai, Inc. and its affiliates and subsidiaries to respect the legitimate rights of copyright owners, and we will respond to clear notices of alleged copyright infringement. Pursuant to the Digital Millennium Copyright Act (the "DMCA"), we have designated a Copyright Agent (as specified below) to receive notifications of claimed copyright infringement in connection with our Website (available at: [https://www.Decart.ai](https://www.Decart.ai)) and mobile application (collectively the "Platform"). Please be advised that we enforce a policy that provides for the termination of inappropriate circumstances of users who are repeat infringers. If you believe that your work has been copied in a way that constitutes copyright infringement, please provide the Copyright Agent with the following information in accordance with the DMCA:

(i) An electronic or physical signature of the person authorized to act on behalf of the owner of the copyright;

(ii) A description of the copyrighted work you claim has been infringed;

(iii) A description of where the material that you claim is infringing is located on the Platform, with enough detail that we may find it. Providing URLs or images in the body of an email is the best way to help us locate content quickly;

(iv) Your address, telephone number, and email address;

(v) A statement by you that you have a good faith belief that the disputed use is not authorized by the copyright owner, its agent, or the law; and

(vi) A statement by you, made under penalty of perjury, that the above information in your notice is accurate and that you are the copyright owner or authorized to act on the copyright owner's behalf.

### 2. Counter-Notification

If you believe that the material you posted was removed from the Platform by mistake and that you have the right to post the material, you may elect to send us a counter-notification. To be effective the counter-notification must be a written communication provided to our Copyright Agent that includes substantially the following (please consult your legal counsel or see the DMCA to confirm these requirements):

(i) Your physical or electronic signature;

(ii) Identification of the material that has been removed or to which access has been disabled and the location at which the material appeared before it was removed or access to it was disabled. Providing URLs or images in the body of an email is the best way to help us locate content quickly;

(iii) A statement under penalty of perjury that you have a good faith belief that the material was removed or disabled as a result of a mistake or misidentification of the material to be removed or disabled; and

(iv) Your name, address, and telephone number, and a statement that you consent to the jurisdiction of the Federal District Court for the judicial district in which the address is located, or if your address is outside of the United States, for any judicial district in which the Platform may be found or accessed, and that you will accept service of process from the person who provided notification of infringement or an agent of such person.

### 3. Misrepresentations

Please note that under the DMCA (at 17 U.S.C. Section 512(f)) any person who knowingly materially misrepresents that material or activity is infringing or was removed or disabled by mistake or misidentification may be subject to liability.

### 4. Copyright Agent

Our agent for notice of claims of copyright infringement ("Copyright Agent") can be reached as follows:

Copyright Compliance Department\
Email: [contact@decart.ai](mailto:contact@decart.ai).\
Telephone: +1 (302) 499-2230\
Address: 1007 North Orange Street, Wilmington, DE 19801, USA


# Overview
Source: https://docs.platform.decart.ai/sdks/android

An Android SDK for Decart's realtime and video processing models

<Card title="GitHub" icon="github" href="https://github.com/DecartAI/decart-android">
  View source code and contribute
</Card>

## Installation

### Gradle (JitPack)

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") }
    }
}
```

Add the dependency to your app's `build.gradle.kts`:

```kotlin build.gradle.kts theme={null}
dependencies {
    implementation("com.github.DecartAI:decart-android:0.7.10")
}
```

## Quick Start

```kotlin theme={null}
import ai.decart.sdk.DecartClient
import ai.decart.sdk.DecartClientConfig
import ai.decart.sdk.realtime.ConnectOptions
import ai.decart.sdk.realtime.InitialPrompt
import ai.decart.sdk.RealtimeModels

val client = DecartClient(context, DecartClientConfig(apiKey = "your-api-key"))
val realtime = client.realtime

// Initialize WebRTC
realtime.initialize(eglBase)

// Connect with a camera track
realtime.connect(
    localVideoTrack = cameraTrack,
    localAudioTrack = null,
    options = ConnectOptions(
        model = RealtimeModels.LUCY_RESTYLE_2,
        onRemoteVideoTrack = { track ->
            // Display the transformed video
            remoteRenderer.addSink(track)
        },
        initialPrompt = InitialPrompt("a cyberpunk cityscape")
    )
)

// Change prompt during session
realtime.setPrompt("a sunny beach scene", enhance = true)

// Disconnect when done
realtime.disconnect()
client.release()
```

## What can you build?

The SDK provides two main APIs for different use cases:

| If you need to... | Use | Main method |
| - | - | - |
| Transform live camera streams over WebRTC | Realtime API | `client.realtime.connect()` |
| Generate/edit videos asynchronously | Queue API | `client.queue.submitAndPoll()` |

<CardGroup>
  <Card title="Realtime API" href="/sdks/android-realtime">
    Realtime video streams via WebRTC
  </Card>

  <Card title="Queue API" href="/sdks/android-queue">
    Batch video processing
  </Card>
</CardGroup>

## Platform Requirements

<Note>
  The Android SDK requires:

  * **Android API 24+** (Android 7.0 Nougat)
  * **Kotlin 2.1+**
  * **Java 17**
  * A **real device** for camera access (emulator does not support WebRTC camera features)
</Note>

## Client Setup

Initialize the Decart client with your API key and an Android `Context`:

```kotlin theme={null}
import ai.decart.sdk.DecartClient
import ai.decart.sdk.DecartClientConfig

val client = DecartClient(
    context = applicationContext,
    config = DecartClientConfig(
        apiKey = "your-api-key",
        baseUrl = "wss://api.decart.ai",       // optional — WebSocket URL for realtime
        httpBaseUrl = "https://api.decart.ai",  // optional — HTTP URL for queue API
        logLevel = LogLevel.WARN,               // optional — SDK log verbosity
    )
)
```

**Parameters:**

* `apiKey` (required) - Your Decart API key from the [platform](https://platform.decart.ai)
* `baseUrl` (optional) - Custom WebSocket endpoint for the Realtime API
* `httpBaseUrl` (optional) - Custom HTTP endpoint for the Queue API
* `logLevel` (optional) - Minimum log level: `VERBOSE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `NONE`

<Warning>
  Store your API key securely. Never commit API keys to version control. Use `BuildConfig` fields, encrypted shared preferences, or fetch ephemeral keys from your backend.
</Warning>

## Client Tokens

For production Android apps using the Realtime API, fetch short-lived client tokens from your backend instead of embedding your permanent API key in the APK:

```kotlin theme={null}
// Fetch ephemeral key from your backend
val ephemeralKey = fetchTokenFromBackend()

// Use it to create the client
val client = DecartClient(
    context = applicationContext,
    config = DecartClientConfig(apiKey = ephemeralKey)
)
```

<Tip>
  See [Client Tokens](/getting-started/client-tokens) for details on secure client-side authentication.
</Tip>

## Available Models

### Realtime Models

Use these with `client.realtime.connect()`:

```kotlin theme={null}
import ai.decart.sdk.RealtimeModels

RealtimeModels.LUCY_2_5               // Realtime video editing (latest)
RealtimeModels.LUCY_VTON_3_5          // Virtual try-on
RealtimeModels.LUCY_VTON_3_6          // Virtual try-on (newest)
RealtimeModels.LUCY_RESTYLE_2         // Realtime video restyling

// Latest aliases
RealtimeModels.LUCY_LATEST            // Always the latest editing model
RealtimeModels.LUCY_RESTYLE_LATEST    // Always the latest restyling model
```

<Accordion title="Previous generation realtime models">
  ```kotlin theme={null}
  RealtimeModels.LUCY_2_1               // Previous realtime video editing
  ```
</Accordion>

Each model exposes properties for optimal camera configuration:

```kotlin theme={null}
val model = RealtimeModels.LUCY_2_5
println(model.fps)     // 30
println(model.width)   // 1280
println(model.height)  // 720
```

### Batch Video Models

Use these with `client.queue.submit()` or `client.queue.submitAndPoll()`:

```kotlin theme={null}
import ai.decart.sdk.VideoModels

VideoModels.LUCY_2_5           // Video editing (latest)
VideoModels.LUCY_VTON_3_5      // Virtual try-on
VideoModels.LUCY_VTON_3_6      // Virtual try-on (newest)
VideoModels.LUCY_RESTYLE_2     // Video restyling

// Latest aliases
VideoModels.LUCY_LATEST        // Always the latest editing model
VideoModels.LUCY_VTON_LATEST   // Latest virtual try-on (currently Lucy VTON 3.6)
```

<Accordion title="Previous generation batch models">
  ```kotlin theme={null}
  VideoModels.LUCY_2_1           // Previous video editing
  ```
</Accordion>

Typed queue input helpers pick the right shape for each model:

* `VideoEditInput` — `lucy-2.1`, `lucy-2.5`, `lucy-vton-3.5`, `lucy-vton-3.6`
* `VideoRestyleInput` — `lucy-restyle-2`

## Kotlin Coroutines & Flow

The SDK uses Kotlin coroutines and Flow for reactive state management:

```kotlin theme={null}
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

// Realtime connection state as StateFlow
lifecycleScope.launch {
    client.realtime.connectionState.collect { state ->
        println("Connection: $state")
    }
}

// Errors as SharedFlow
lifecycleScope.launch {
    client.realtime.errors.collect { error ->
        println("Error: ${error.code} — ${error.message}")
    }
}

// Queue job progress as Flow
client.queue.submitAndObserve(model, input).collect { update ->
    when (update) {
        is QueueJobResult.InProgress -> println("Status: ${update.status}")
        is QueueJobResult.Completed -> saveVideo(update.data)
        is QueueJobResult.Failed -> showError(update.error)
    }
}
```

<Tip>
  All realtime state is exposed as Kotlin `StateFlow` or `SharedFlow`. Collect them in a lifecycle-aware scope (e.g., `lifecycleScope` or `viewModelScope`) to avoid leaks.
</Tip>

## Jetpack Compose Integration

The SDK works with Jetpack Compose through WebRTC's `SurfaceViewRenderer`:

```kotlin theme={null}
import androidx.compose.runtime.Composable
import androidx.compose.ui.viewinterop.AndroidView
import org.webrtc.SurfaceViewRenderer

@Composable
fun VideoRenderer(
    onSurfaceReady: (SurfaceViewRenderer) -> Unit
) {
    AndroidView(
        factory = { context ->
            SurfaceViewRenderer(context).apply {
                init(client.realtime.getEglBaseContext(), null)
                onSurfaceReady(this)
            }
        }
    )
}
```

## Android Permissions

Your app must declare camera and internet permissions. Add these to your `AndroidManifest.xml`:

```xml theme={null}
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

Request camera permission at runtime before connecting:

```kotlin theme={null}
val launcher = rememberLauncherForActivityResult(
    ActivityResultContracts.RequestPermission()
) { granted ->
    if (granted) {
        // Start camera and connect
    }
}

launcher.launch(Manifest.permission.CAMERA)
```

## Type Safety

The SDK uses typed input classes for each batch video model category, providing compile-time guarantees:

```kotlin theme={null}
import ai.decart.sdk.queue.*

// Video editing — requires prompt + video file
val edit = VideoEditInput(
    prompt = "Cinematic color grade",
    data = FileInput.fromUri(videoUri),
)
```

## Error Handling

The SDK provides two error mechanisms — one for realtime, one for queue:

**Realtime errors** are emitted via the `errors` SharedFlow:

```kotlin theme={null}
client.realtime.errors.collect { error ->
    when (error.code) {
        ErrorCodes.INVALID_API_KEY -> { /* handle auth error */ }
        ErrorCodes.WEBRTC_TIMEOUT_ERROR -> { /* handle timeout */ }
        ErrorCodes.WEBRTC_ICE_ERROR -> { /* handle ICE failure */ }
        else -> { /* handle other errors */ }
    }
}
```

**Queue errors** throw typed exceptions:

```kotlin theme={null}
try {
    val result = client.queue.submitAndPoll(model, input)
} catch (e: QueueSubmitException) {
    // Job submission failed
} catch (e: QueueStatusException) {
    // Status check failed
} catch (e: QueueResultException) {
    // Result download failed
} catch (e: InvalidInputException) {
    // Input validation failed
}
```

## Sample App

The SDK includes a [sample Jetpack Compose app](https://github.com/DecartAI/decart-android/tree/main/sample) with:

* **Realtime tab** — Camera capture + WebRTC streaming with live prompt changes
* **Video tab** — Batch job submission, status updates, and result playback

For a more complete app showcasing real-world use cases — video restyling, 90+ style presets, multiple view modes, and swipe navigation — see the [Decart Android Example App](https://github.com/DecartAI/decart-example-android-realtime).

## Ready to start building?

<CardGroup>
  <Card title="Realtime API Guide" href="/sdks/android-realtime">
    **Build realtime Android experiences**

    Complete guide with Jetpack Compose examples for camera handling, video transformation, and interactive applications.
  </Card>

  <Card title="Queue API Guide" href="/sdks/android-queue">
    **Batch video processing**

    Edit videos, control motion, and transform videos with typed input classes and Flow-based progress tracking.
  </Card>
</CardGroup>


# Queue API
Source: https://docs.platform.decart.ai/sdks/android-queue

Asynchronous job-based video processing on Android

The Queue API is the primary way to process videos with the Android SDK. Submit jobs that are processed asynchronously, then poll for status or observe progress as a Kotlin Flow.

<Note>
  All video processing (video editing, restyling, motion control) uses the Queue API. For realtime camera transformation, use the [Realtime API](/sdks/android-realtime).
</Note>

## Overview

The Queue API provides five methods:

| Method | Description |
| - | - |
| `submit()` | Submit a job and get a job ID immediately |
| `status()` | Check the status of a submitted job |
| `result()` | Download the completed video as `ByteArray` |
| `submitAndPoll()` | Submit and auto-poll until completion |
| `submitAndObserve()` | Submit and return a `Flow` of progress updates |

## Quick Start

```kotlin theme={null}
import ai.decart.sdk.DecartClient
import ai.decart.sdk.DecartClientConfig
import ai.decart.sdk.VideoModels
import ai.decart.sdk.queue.FileInput
import ai.decart.sdk.queue.QueueJobResult
import ai.decart.sdk.queue.VideoEditInput

val client = DecartClient(context, DecartClientConfig(apiKey = "your-api-key"))

val input = VideoEditInput(
    prompt = "Cinematic color grade, soft contrast",
    data = FileInput.fromUri(videoUri),
)

when (val result = client.queue.submitAndPoll(VideoModels.LUCY_2_5, input)) {
    is QueueJobResult.Completed -> {
        val output = java.io.File(context.cacheDir, "output.mp4")
        output.writeBytes(result.data)
    }
    is QueueJobResult.Failed -> {
        Log.e("Decart", "Job failed: ${result.error}")
    }
    else -> Unit
}

client.release()
```

## Submit a Job

Submit a video processing job and receive a job ID immediately:

```kotlin theme={null}
val input = VideoEditInput(
    prompt = "Transform to anime style",
    data = FileInput.fromUri(videoUri),
)

val job = client.queue.submit(VideoModels.LUCY_2_5, input)

println("Job ID: ${job.jobId}")
println("Status: ${job.status}")  // PENDING
```

**Returns:** `JobSubmitResponse`

* `jobId: String` - Unique job identifier
* `status: JobStatus` - Initial status (`PENDING`)

***

## Check Job Status

Poll the status of a submitted job:

```kotlin theme={null}
val status = client.queue.status(job.jobId)
println("Status: ${status.status}")  // PENDING, PROCESSING, COMPLETED, or FAILED
```

**Status Values:**

| Status | Description |
| - | - |
| `PENDING` | Job is queued, waiting to be processed |
| `PROCESSING` | Job is currently being processed |
| `COMPLETED` | Job finished successfully |
| `FAILED` | Job failed or timed out |

***

## Get Job Result

Download the completed video as raw bytes:

```kotlin theme={null}
val status = client.queue.status(job.jobId)

if (status.status == JobStatus.COMPLETED) {
    val videoBytes = client.queue.result(job.jobId)

    val output = java.io.File(context.cacheDir, "output.mp4")
    output.writeBytes(videoBytes)
}
```

**Returns:** `ByteArray` - The output video (MP4).

***

## Submit and Poll

The easiest way to use the Queue API. Submit a job and automatically poll until completion:

```kotlin theme={null}
val result = client.queue.submitAndPoll(
    model = VideoModels.LUCY_2_5,
    input = VideoEditInput(
        prompt = "Cinematic color grade",
        data = FileInput.fromUri(videoUri),
    ),
    onStatusChange = { status ->
        Log.d("Decart", "Status: ${status.status}")
    }
)

when (result) {
    is QueueJobResult.Completed -> {
        val output = java.io.File(context.cacheDir, "output.mp4")
        output.writeBytes(result.data)
    }
    is QueueJobResult.Failed -> {
        Log.e("Decart", "Failed: ${result.error}")
    }
    else -> Unit
}
```

**Parameters:**

* `model` (required) - Video model from `VideoModels`
* `input` (required) - Typed input (e.g., `VideoEditInput`, `TextToVideoInput`)
* `onStatusChange` (optional) - Callback invoked on each status change

<Note>
  `submitAndPoll` does not throw on job failure — it returns `QueueJobResult.Failed`. It will throw `QueueSubmitException`, `QueueStatusException`, or `QueueResultException` on network/API errors.
</Note>

***

## Submit and Observe (Flow)

Get a reactive `Flow` of progress updates, ideal for Jetpack Compose UIs:

```kotlin theme={null}
client.queue.submitAndObserve(VideoModels.LUCY_2_5, input)
    .collect { update ->
        when (update) {
            is QueueJobResult.InProgress -> {
                // Pending or processing
                Log.d("Decart", "Status: ${update.status}")
                updateProgressUI(update.status)
            }
            is QueueJobResult.Completed -> {
                Log.d("Decart", "Done: ${update.data.size} bytes")
                saveVideo(update.data)
            }
            is QueueJobResult.Failed -> {
                Log.e("Decart", "Failed: ${update.error}")
                showError(update.error)
            }
        }
    }
```

**Emits:**

1. `QueueJobResult.InProgress` - On each poll while pending/processing
2. `QueueJobResult.Completed` - Terminal: contains the video bytes
3. `QueueJobResult.Failed` - Terminal: contains the error message

<Tip>
  `submitAndObserve()` returns a cold Flow that runs on `Dispatchers.IO`. Collect it in `viewModelScope` or `lifecycleScope` for automatic cancellation.
</Tip>

***

## Input Types

Each model category has a typed input class that enforces required fields at compile time.

### VideoEditInput

For video-to-video editing models: `LUCY_2_1`, `LUCY_2_5`, `LUCY_VTON_3_5`, `LUCY_VTON_3_6`.

```kotlin theme={null}
val input = VideoEditInput(
    prompt = "Cinematic color grade, soft contrast",  // required (can be empty)
    data = FileInput.fromUri(videoUri),                // required
    referenceImage = FileInput.fromUri(refImageUri),   // optional
    seed = 42,                                         // optional (0–4294967295)
    resolution = "720p",                               // optional
    enhancePrompt = true,                              // optional
)
```

<ParamField type="String">
  Text prompt describing the desired edit. Max 1000 characters. Can be empty string.
</ParamField>

<ParamField type="FileInput">
  Video file to transform.
</ParamField>

<ParamField type="FileInput">
  Optional reference image for style guidance.
</ParamField>

<ParamField type="Int">
  Seed for reproducible output (0–4294967295).
</ParamField>

<ParamField type="String">
  Output resolution.
</ParamField>

<ParamField type="Boolean">
  Whether to AI-enhance the prompt.
</ParamField>

### VideoRestyleInput

For video restyling: `LUCY_RESTYLE_2`. Must provide exactly one of `prompt` or `referenceImage` (mutually exclusive).

```kotlin theme={null}
// Option A: Restyle with prompt
val restyle = VideoRestyleInput(
    data = FileInput.fromUri(videoUri),
    prompt = "Oil painting style with bold brushstrokes",
    enhancePrompt = true,
)

// Option B: Restyle with reference image
val restyle = VideoRestyleInput(
    data = FileInput.fromUri(videoUri),
    referenceImage = FileInput.fromUri(styleImageUri),
    seed = 7,
)

client.queue.submit(VideoModels.LUCY_RESTYLE_2, restyle)
```

<Warning>
  `prompt` and `referenceImage` are mutually exclusive. Providing both throws an `IllegalArgumentException`. When using `referenceImage`, `enhancePrompt` must not be `true`.
</Warning>

## FileInput

`FileInput` is a sealed class that wraps common Android file sources. All queue input types use it for file fields.

```kotlin theme={null}
import ai.decart.sdk.queue.FileInput

// From gallery picker or camera capture result
val fromUri = FileInput.fromUri(contentUri)

// From a file on disk
val fromFile = FileInput.fromFile(java.io.File("/path/to/video.mp4"))

// From raw bytes in memory
val fromBytes = FileInput.fromBytes(videoBytes, "video/mp4")

// From an InputStream (streaming — read once at submission)
val fromStream = FileInput.fromInputStream(inputStream, "video/mp4")
```

| Factory method | Source | Best for |
| - | - | - |
| `fromUri(uri)` | Android content `Uri` | Gallery picker, camera capture, content providers |
| `fromFile(file)` | `java.io.File` | Files on local storage |
| `fromBytes(bytes, mimeType)` | `ByteArray` | In-memory data |
| `fromInputStream(stream, mimeType)` | `InputStream` | Streaming from network or assets |

<Tip>
  `fromUri()` and `fromFile()` stream directly from disk into the HTTP body without buffering in memory, avoiding OOM errors on large video files.
</Tip>

***

## Error Handling

Queue methods throw typed exceptions on network/API errors:

```kotlin theme={null}
import ai.decart.sdk.queue.*

try {
    val result = client.queue.submitAndPoll(model, input)
    when (result) {
        is QueueJobResult.Completed -> saveVideo(result.data)
        is QueueJobResult.Failed -> showError(result.error)
        else -> Unit
    }
} catch (e: InvalidInputException) {
    Log.e("Decart", "Invalid input: ${e.message}")
} catch (e: QueueSubmitException) {
    Log.e("Decart", "Submit failed: ${e.message} (HTTP ${e.statusCode})")
} catch (e: QueueStatusException) {
    Log.e("Decart", "Status check failed: ${e.message}")
} catch (e: QueueResultException) {
    Log.e("Decart", "Download failed: ${e.message}")
}
```

**Exception hierarchy:**

| Exception | Thrown when |
| - | - |
| `QueueException` | Base class for all queue errors |
| `QueueSubmitException` | Job submission fails |
| `QueueStatusException` | Status check fails |
| `QueueResultException` | Result download fails |
| `InvalidInputException` | Input validation fails before submission |

All queue exceptions include an optional `statusCode: Int?` for HTTP errors.

***

## Manual Polling

For custom polling logic, combine `submit()`, `status()`, and `result()`:

```kotlin theme={null}
import kotlinx.coroutines.delay

// Submit job
val job = client.queue.submit(VideoModels.LUCY_2_5, input)
Log.d("Decart", "Job submitted: ${job.jobId}")

// Manual polling loop
while (true) {
    val current = client.queue.status(job.jobId)
    Log.d("Decart", "Status: ${current.status}")

    when (current.status) {
        JobStatus.COMPLETED -> {
            val videoBytes = client.queue.result(job.jobId)
            saveVideo(videoBytes)
            break
        }
        JobStatus.FAILED -> {
            Log.e("Decart", "Generation failed")
            break
        }
        else -> delay(1_500L)  // Wait before next poll
    }
}
```

***

## Supported Models

| Model | Constant | Input Type | Description |
| - | - | - | - |
| Lucy 2.5 | `VideoModels.LUCY_2_5` | `VideoEditInput` | Video editing (latest) |
| Lucy VTON 3.5 | `VideoModels.LUCY_VTON_3_5` | `VideoEditInput` | Virtual try-on |
| Lucy VTON 3.6 | `VideoModels.LUCY_VTON_3_6` | `VideoEditInput` | Virtual try-on (newest) |
| Lucy Restyle 2 | `VideoModels.LUCY_RESTYLE_2` | `VideoRestyleInput` | Video restyling (prompt or reference image) |

<Accordion title="Latest aliases">
  | Alias | Constant | Description |
  | - | - | - |
  | Lucy Latest | `VideoModels.LUCY_LATEST` | Always the latest editing model (currently Lucy 2.5) |
  | Lucy VTON Latest | `VideoModels.LUCY_VTON_LATEST` | Always the latest virtual try-on model (currently Lucy VTON 3.6) |
  | Lucy Restyle Latest | `VideoModels.LUCY_RESTYLE_LATEST` | Always the latest restyling model |
</Accordion>

<Accordion title="Previous generation models">
  | Model | Constant | Input Type | Description |
  | - | - | - | - |
  | Lucy 2.1 | `VideoModels.LUCY_2_1` | `VideoEditInput` | Previous video editing |
</Accordion>

***

## API Reference

### `client.queue.submit(model, input)`

Submit a job for processing. Suspend function.

**Parameters:**

* `model: VideoModel` - Video model from `VideoModels`
* `input: QueueJobInput` - Typed input (e.g., `VideoEditInput`)

**Returns:** `JobSubmitResponse`

* `jobId: String` - Unique job identifier
* `status: JobStatus` - Initial status (`PENDING`)

**Throws:** `InvalidInputException`, `QueueSubmitException`

***

### `client.queue.status(jobId)`

Check the status of a job. Suspend function.

**Parameters:**

* `jobId: String` - Job ID from `submit()`

**Returns:** `JobStatusResponse`

* `jobId: String` - Job identifier
* `status: JobStatus` - Current status

**Throws:** `QueueStatusException`

***

### `client.queue.result(jobId)`

Download the result of a completed job. Suspend function.

**Parameters:**

* `jobId: String` - Job ID from `submit()`

**Returns:** `ByteArray` - Output video bytes (MP4)

**Throws:** `QueueResultException`

***

### `client.queue.submitAndPoll(model, input, onStatusChange?)`

Submit a job and auto-poll until completion. Suspend function.

**Parameters:**

* `model: VideoModel` - Video model
* `input: QueueJobInput` - Typed input
* `onStatusChange: ((JobStatusResponse) -> Unit)?` - Optional status callback

**Returns:** `QueueJobResult.Completed` or `QueueJobResult.Failed`

**Throws:** `QueueSubmitException`, `QueueStatusException`, `QueueResultException` on network errors

***

### `client.queue.submitAndObserve(model, input)`

Submit a job and return a Flow of progress updates.

**Parameters:**

* `model: VideoModel` - Video model
* `input: QueueJobInput` - Typed input

**Returns:** `Flow<QueueJobResult>` - Emits `InProgress`, then `Completed` or `Failed`

***

### `client.queue.release()`

Release HTTP resources held by the queue client.

***

## Next Steps

<CardGroup>
  <Card title="Realtime API" icon="bolt" href="/sdks/android-realtime">
    Transform camera video streams in realtime with WebRTC
  </Card>

  <Card title="SDK Overview" icon="android" href="/sdks/android">
    Installation, setup, and Android SDK fundamentals
  </Card>
</CardGroup>


# Realtime API
Source: https://docs.platform.decart.ai/sdks/android-realtime

Transform video streams in realtime on Android

The Realtime API transforms live camera video with minimal latency. Signaling is a Decart-owned WebSocket; media flows through a LiveKit room that the SDK joins for you. Perfect for camera effects, video restyling apps, AR experiences, and interactive live streaming.

## Quick Start

```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.FacingMode
import ai.decart.sdk.realtime.InitialPrompt
import ai.decart.sdk.realtime.MirrorMode

val client = DecartClient(context, DecartClientConfig(apiKey = "your-api-key"))
val realtime = client.realtime

// Connect and let the SDK open the camera. The remote (transformed) stream
// is delivered via onRemoteStream.
realtime.connect(
    ConnectOptions(
        model = RealtimeModels.LUCY_RESTYLE_2,
        initialPrompt = InitialPrompt("a cyberpunk cityscape"),
        facing = FacingMode.FRONT,
        mirror = MirrorMode.AUTO,
        publishCamera = true,
        onRemoteStream = { stream ->
            // Render stream.videoTrack with a LiveKit renderer (see below).
        },
    ),
)

// Change the style mid-session — suspends until the server acks.
realtime.setPrompt("a sunny beach scene", enhance = true)

realtime.disconnect()
client.release()
```

## Client-Side Authentication

For production Android apps, use ephemeral keys instead of embedding your permanent API key in the APK. Ephemeral keys are short-lived tokens safe to include in client applications.

<Info>
  Learn more about [client tokens](/getting-started/client-tokens) and why they're important for security.
</Info>

### Fetching an Ephemeral Key

Your app should fetch an ephemeral key from your backend server before connecting:

```kotlin theme={null}
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject

suspend fun fetchEphemeralKey(): String = withContext(Dispatchers.IO) {
    val client = OkHttpClient()
    val request = Request.Builder()
        .url("https://your-backend.com/api/realtime-token")
        .post("".toRequestBody())
        // Add any auth headers your backend requires
        // .addHeader("Authorization", "Bearer $userToken")
        .build()

    val response = client.newCall(request).execute()
    if (!response.isSuccessful) {
        throw Exception("Failed to fetch token: ${response.code}")
    }

    val body = response.body?.string()
        ?: throw Exception("Empty response body")
    JSONObject(body).getString("apiKey")
}
```

### Connecting with an Ephemeral Key

```kotlin theme={null}
val ephemeralKey = fetchEphemeralKey()

val client = DecartClient(
    context = applicationContext,
    config = DecartClientConfig(apiKey = ephemeralKey)
)

// Connect as usual
client.realtime.connect(options)
```

<Warning>
  Never hardcode your permanent API key in Android apps. APKs can be decompiled, exposing embedded secrets. Always use ephemeral keys from your backend.
</Warning>

## Connecting

### Camera ownership

You have two options for the local stream:

* **SDK-owned camera (simplest).** Pass `publishCamera = true` to `ConnectOptions` and the SDK opens the camera, joins the LiveKit room, and publishes for you.
* **Caller-owned preview.** Call `realtime.createLocalVideoStream(model, facing, mirror)` ahead of time to drive a preview UI before connecting, then pass the resulting `RealtimeMediaStream` to `connect(...)`. Preview and publish share the same LiveKit `Room`. Dispose the stream when you're done.

```kotlin theme={null}
val model = RealtimeModels.LUCY_2_1

// Caller-owned preview — sized from the model's capture resolution.
val localStream = realtime.createLocalVideoStream(
    model = model,
    facing = FacingMode.FRONT,
    mirror = MirrorMode.AUTO,
)

// Later, when the user hits Connect:
realtime.connect(
    options = ConnectOptions(
        model = model,
        publishCamera = true,
        onRemoteStream = { stream -> /* render stream.videoTrack */ },
    ),
    localStream = localStream,
)
```

There's also a static `RealTimeClient.createLocalVideoStream(context, model, ...)` for building a preview before you've decided which API key to use.

<Warning>Camera capture requires a **real Android device**. The emulator does not support camera-driven realtime sessions.</Warning>

### Rendering with LiveKit

Realtime media tracks are LiveKit tracks. Use a LiveKit renderer such as `TextureViewRenderer` or `SurfaceViewRenderer` and initialize it with the Room's `EglBase` context:

```kotlin theme={null}
import io.livekit.android.renderer.SurfaceViewRenderer
import io.livekit.android.room.track.VideoTrack

// In your composable or view, given a RealtimeMediaStream `stream`:
val room = stream.room ?: return
val renderer = SurfaceViewRenderer(context)
renderer.init(room.lkObjects.eglBase.eglBaseContext, null)
stream.videoTrack?.addRenderer(renderer)
```

You can react to remote-stream changes (initial frame, auto-reconnect rebinds) via `realtime.remoteStreamUpdates`:

```kotlin theme={null}
lifecycleScope.launch {
    realtime.remoteStreamUpdates.collect { stream ->
        previousRenderer?.let { stream.videoTrack?.removeRenderer(it) }
        stream.videoTrack?.addRenderer(remoteRenderer)
    }
}
```

### Front-camera mirroring

`mirror` pre-flips the captured frames **before** they're published, so server-baked pixels (watermarks, overlays) remain readable. Render both local previews and remote streams as-is — do **not** also set renderer-level mirroring or you'll double-flip.

```kotlin theme={null}
realtime.connect(
    ConnectOptions(
        model = RealtimeModels.LUCY_2_1,
        facing = FacingMode.FRONT,
        mirror = MirrorMode.AUTO, // default: front mirrored, back as-is
    )
)
```

`MirrorMode` values:

* `OFF` — never mirror.
* `ON` — always mirror.
* `AUTO` (default) — mirror only when `facing == FacingMode.FRONT`.

The same `mirror` argument is available on `createLocalVideoStream(...)`.

### Output resolution

Opt into 1080p output from supported models; otherwise the server defaults to 720p:

```kotlin theme={null}
import ai.decart.sdk.realtime.Resolution

realtime.connect(
    ConnectOptions(
        model = RealtimeModels.LUCY_2_1,
        resolution = Resolution.P1080,
        onRemoteStream = { /* ... */ },
    )
)
```

### Fast mode

Fast mode (`speed: "fast"`) gives the session lower latency and higher throughput; output quality is unchanged. It is available for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5`, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode. See [Pricing](/getting-started/pricing#realtime-models).

```kotlin theme={null}
import ai.decart.sdk.realtime.Speed

realtime.connect(
    ConnectOptions(
        model = RealtimeModels.LUCY_2_5,
        speed = Speed.FAST,
        onRemoteStream = { /* ... */ },
    )
)
```

Requires SDK 0.8.1+.

`RealtimeModel.supportedSpeeds` contains `Speed.FAST` for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5` only. Passing `speed` for another model logs a warning and connects on the standard tier.

### Reference images

Send a reference image at connect time via `initialImage` (base64-encoded):

```kotlin theme={null}
val characterBase64 = Base64.encodeToString(characterBytes, Base64.NO_WRAP)

realtime.connect(
    ConnectOptions(
        model = RealtimeModels.LUCY_2_1,
        initialImage = characterBase64,
        initialPrompt = InitialPrompt(
            text = "Substitute the character in the video with the person in the reference image.",
            enhance = true,
        ),
        onRemoteStream = { /* ... */ },
    )
)
```

<Tip>
  Set `initialImage` and/or `initialPrompt` so the first frame is already transformed — otherwise viewers briefly see the raw camera feed.
</Tip>

### Tuning the LiveKit publisher

Override codec, bitrate, or framerate via `RealtimeConfiguration`:

```kotlin theme={null}
import ai.decart.sdk.realtime.RealtimeConfiguration

realtime.connect(
    ConnectOptions(
        model = RealtimeModels.LUCY_2_1,
        realtimeConfiguration = RealtimeConfiguration(
            media = RealtimeConfiguration.MediaConfig(
                video = RealtimeConfiguration.VideoConfig(
                    preferredCodec = "H264", // default: "VP8"
                    maxBitrate = 2_500_000,
                    maxFramerate = 30,
                )
            )
        ),
    )
)
```

Defaults: codec VP8, max bitrate 2,000,000 bps, max framerate 30 fps, simulcast on.

### Realtime audio

The Android LiveKit publisher is **video-only** in 0.7. `publishMicrophone`, `includeMicrophone`, and `RealtimeMediaStream.audioTrack` are retained for source compatibility but are deprecated and ignored — SDK-created streams always expose `audioTrack = null`. Use the JavaScript or Swift realtime SDKs if you need audio.

## Managing Prompts

`setPrompt` is a `suspend` function that waits for the server ack and throws on ack failure, timeout, or websocket disconnect. Always call it from a coroutine.

```kotlin theme={null}
lifecycleScope.launch {
    try {
        realtime.setPrompt("Anime style", enhance = true)
    } catch (e: Exception) {
        showError("Prompt rejected: ${e.message}")
    }
}
```

**Parameters:**

* `prompt: String` (required) - Style description
* `enhance: Boolean` (optional) - Auto-enhance the prompt (default: `true`)
* `timeoutMs: Long` (optional) - Ack timeout in milliseconds (default: `15_000`)

If you'd rather fire-and-forget and observe the ack later, use `setPromptAsync(...)` which returns `Deferred<Unit>`:

```kotlin theme={null}
val ack = realtime.setPromptAsync("Cyberpunk city")
// ... later
try { ack.await() } catch (e: Exception) { /* ack failed */ }
```

<Note>Prompt enhancement uses Decart's AI to expand simple prompts for better results. Disable it if you want full control over the exact prompt.</Note>

## Reference Images

Send a reference image (and optionally a prompt) for image-guided models. Also a `suspend` function with a `Deferred`-returning sibling.

```kotlin theme={null}
lifecycleScope.launch {
    // Set image with prompt
    realtime.setImage(
        imageBase64 = base64EncodedImage,
        prompt = "Transform into this character",
        enhance = true,
    )

    // Clear image
    realtime.setImage(imageBase64 = null)
}

// Or, fire-and-forget with a wait handle:
val ack = realtime.setImageAsync(imageBase64 = base64EncodedImage, prompt = "...")
ack.await()
```

**Parameters:**

* `imageBase64: String?` (required) - Base64-encoded image, or `null` to clear
* `prompt: String?` (optional) - Text prompt to send with the image
* `enhance: Boolean?` (optional) - Whether to enhance the prompt
* `timeout: Long` (optional) - Ack timeout in milliseconds (default: `30_000`)

## Connection State

Monitor connection state changes using a Kotlin `Flow`:

```kotlin theme={null}
import ai.decart.sdk.ConnectionState

lifecycleScope.launch {
    realtime.connectionState.collect { state ->
        when (state) {
            ConnectionState.DISCONNECTED -> showReconnectButton()
            ConnectionState.CONNECTING -> showLoadingIndicator()
            ConnectionState.CONNECTED -> hideLoadingIndicator()
            ConnectionState.GENERATING -> showGeneratingUI()
            ConnectionState.RECONNECTING -> showReconnectingBanner()
        }
    }
}

val isConnected = realtime.isConnected()
```

**Connection States:**

* `DISCONNECTED` - Not connected (initial state, after `disconnect()`, or after reconnect failure)
* `CONNECTING` - Initial connection in progress
* `CONNECTED` - Connected and ready to send prompts
* `GENERATING` - Actively generating transformed video (sticky until disconnected)
* `RECONNECTING` - Connection lost unexpectedly; the SDK is automatically retrying

<Info>
  The SDK automatically reconnects when an unexpected disconnection occurs (e.g., network interruption). During auto-reconnect, the state transitions to `RECONNECTING` while the SDK retries. If all retries fail, the state moves to `DISCONNECTED` and an error is emitted. A new `RealtimeMediaStream` is delivered via `remoteStreamUpdates` after each successful rebind — re-attach your renderer.
</Info>

## Error Handling

Errors are emitted via the `errors` SharedFlow:

```kotlin theme={null}
import ai.decart.sdk.DecartError
import ai.decart.sdk.ErrorCodes

lifecycleScope.launch {
    realtime.errors.collect { error ->
        when (error.code) {
            ErrorCodes.INVALID_API_KEY ->
                showError("Invalid API key. Check your credentials.")
            ErrorCodes.WEBRTC_TIMEOUT_ERROR ->
                showError("Connection timed out. Check your network.")
            ErrorCodes.WEBRTC_ICE_ERROR ->
                showError("ICE negotiation failed.")
            ErrorCodes.WEBRTC_WEBSOCKET_ERROR ->
                showError("WebSocket connection error.")
            ErrorCodes.WEBRTC_SERVER_ERROR ->
                showError("Server error. Try again later.")
            ErrorCodes.WEBRTC_SIGNALING_ERROR ->
                showError("Signaling error.")
            else ->
                showError("Error: ${error.message}")
        }
    }
}
```

**Error Codes:**

* `INVALID_API_KEY` - API key is invalid or missing
* `WEBRTC_TIMEOUT_ERROR` - Connection timed out
* `WEBRTC_ICE_ERROR` - ICE negotiation failed
* `WEBRTC_WEBSOCKET_ERROR` - WebSocket connection error
* `WEBRTC_SERVER_ERROR` - Server-side error
* `WEBRTC_SIGNALING_ERROR` - Signaling protocol error

## Publisher Stats

The `stats` SharedFlow emits outbound (publisher) video metrics roughly once per second:

```kotlin theme={null}
lifecycleScope.launch {
    realtime.stats.collect { event ->
        println("Encoded ${event.deltaFrames} frames (${event.frameWidth}x${event.frameHeight})")
        println("Sent ${event.deltaBytes} bytes")
        event.qualityLimitationReason?.let { println("Quality limited by: $it") }
    }
}
```

`PublishStatsEvent` fields:

* `bytesSent`, `deltaBytes` - Cumulative and per-sample bytes sent
* `framesEncoded`, `deltaFrames` - Cumulative and per-sample frames encoded
* `frameWidth`, `frameHeight` - Current encoded frame size
* `encoderImplementation` - Codec implementation reported by libwebrtc
* `qualityLimitationReason` - `"cpu"`, `"bandwidth"`, etc. when the encoder is throttling

## Generation Ticks

Track session duration for billing and usage display:

```kotlin theme={null}
lifecycleScope.launch {
    realtime.generationTicks.collect { tick ->
        println("Generation running for ${tick.seconds} seconds")
        updateBillingUI(tick.seconds)
    }
}
```

## Diagnostics

Monitor detailed connection diagnostics for debugging:

```kotlin theme={null}
import ai.decart.sdk.realtime.DiagnosticEvent

lifecycleScope.launch {
    realtime.diagnostics.collect { event ->
        when (event) {
            is DiagnosticEvent.PhaseTiming ->
                println("${event.data.phase}: ${event.data.durationMs}ms")
            is DiagnosticEvent.FirstFrame ->
                println("First remote frame in ${event.data.timeSinceConnectMs}ms")
            is DiagnosticEvent.Reconnect ->
                println("Reconnect attempt ${event.data.attempt}/${event.data.maxAttempts}")
            is DiagnosticEvent.VideoStall ->
                println("Video stall: ${if (event.data.stalled) "detected" else "recovered"}")
            is DiagnosticEvent.PublishStats ->
                { /* see Publisher Stats above — same payload also delivered here */ }
            else -> { /* ICE, peer connection, signaling state changes */ }
        }
    }
}
```

## Connection Quality

Two layers report network health on a shared `GOOD | FAIR | POOR | CRITICAL` scale: a **preflight** check before connecting, and an **in-session** signal while connected.

### Preflight

A fast, network-only reachability check. No session, no cost:

```kotlin theme={null}
import ai.decart.sdk.realtime.ConnectionQuality

val report = realtime.checkConnectivity() // suspend
// report.metrics: transport (UDP | RELAY | FAILED), rttMs
if (report.quality == ConnectionQuality.CRITICAL) showFallbackUi(report.reasons)
```

### In-session quality

While connected, the SDK derives a smoothed verdict from live connection stats (latency, packet loss, upstream bandwidth, frame rate) and tells you the limiting factor. Level is debounced; metrics refresh each stats sample (\~few seconds):

```kotlin theme={null}
realtime.connect(
    ConnectOptions(
        model = RealtimeModels.LUCY_2_1,
        onConnectionQuality = { report ->
            // report.limitingFactor: BANDWIDTH | LATENCY | LOSS | STALL | CPU | NONE
            // report.metrics: rttMs, fps, packetLoss, availableUpstreamKbps, ...
            updateBadge(report.quality)
        },
        onRemoteStream = { /* ... */ },
    ),
)

// also a Flow + a getter:
realtime.connectionQuality.collect { /* ConnectionQualityReport? */ }
realtime.getConnectionQuality() // latest, or null before the first sample
```

### Glass-to-glass latency (opt-in)

Network RTT alone doesn't reflect the latency users actually feel — a session can read `GOOD` while still feeling laggy. Set `debugQuality = true` to measure the real camera→display latency: the SDK stamps a pixel marker into each outgoing frame and reads it back off the rendered output, surfacing startup (`ttffMs`), steady-state (`g2gMs`), and end-to-end drops (`g2gDropRatio`). When present, glass-to-glass drives the latency verdict instead of RTT.

```kotlin theme={null}
val stream = realtime.createLocalVideoStream(
    model = RealtimeModels.LUCY_2_1,
    debugQuality = true,
)
realtime.connect(
    ConnectOptions(
        model = RealtimeModels.LUCY_2_1,
        debugQuality = true,
        onConnectionQuality = { report ->
            // report.metrics.ttffMs / g2gMs / g2gDropRatio
        },
    ),
    localStream = stream,
)
```

<Warning>Diagnostic only. The marker is visible (bottom-left of the published + rendered video) and adds per-frame pixel work — don't enable it for production / end-user sessions. With a caller-provided stream, build it via `createLocalVideoStream(..., debugQuality = true)` so the same flag is set on both the stream and `connect()`.</Warning>

### Deep preflight

For a *measured* verdict before connecting, use the deep probe — it briefly opens a real session with a synthetic source, measures glass-to-glass, then tears it down. Requires a `model` and costs a short session:

```kotlin theme={null}
import ai.decart.sdk.realtime.CheckConnectivityOptions

val probe = realtime.checkConnectivity(
    CheckConnectivityOptions(deep = true, model = RealtimeModels.LUCY_2_1),
)
// probe.metrics.g2gMs / ttffMs / g2gDropRatio
```

## Session Identifiers

Once a session is established the SDK surfaces the server-side session id and a subscribe token:

```kotlin theme={null}
val sessionId = realtime.sessionId        // for logging / analytics
val subscribeToken = realtime.subscribeToken // share with viewers for read-only watching
```

Both come from the `sessionStarted: StateFlow<SessionStarted?>` — collect it if you need to react when they appear.

## Cleanup

Always tear down the session and release native resources when you're done:

```kotlin theme={null}
// If you own the local stream, dispose it after the client teardown.
realtime.disconnect()
localStream?.dispose()
client.release()
```

`disconnect()` ends the current session but leaves the client reusable. `release()` cancels the SDK's coroutine scope and shuts down the underlying LiveKit room ownership; call it when the client is no longer needed.

<Warning>Forgetting to `dispose()` a caller-owned `RealtimeMediaStream` leaks the LiveKit Room (and its capturer + native PeerConnectionFactory). Tie disposal to your lifecycle (`onCleared`, `DisposableEffect`, etc.).</Warning>

## Complete Jetpack Compose Example

A full Jetpack Compose tab with a caller-owned preview and the LiveKit renderer, modeled on the [sample app on GitHub](https://github.com/DecartAI/decart-android/tree/main/sample):

```kotlin theme={null}
import ai.decart.sdk.*
import ai.decart.sdk.realtime.*
import android.Manifest
import android.util.Log
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.compose.ui.viewinterop.AndroidView
import io.livekit.android.renderer.TextureViewRenderer
import io.livekit.android.room.Room
import io.livekit.android.room.track.VideoTrack
import kotlinx.coroutines.flow.collectLatest
import kotlinx.coroutines.launch
import livekit.org.webrtc.RendererCommon

@Composable
fun RealtimeScreen(apiKey: String) {
    val context = LocalContext.current
    val coroutineScope = rememberCoroutineScope()

    var connectionState by remember { mutableStateOf(ConnectionState.DISCONNECTED) }
    var prompt by remember { mutableStateOf("Turn into a fantasy figure") }
    val selectedModel = RealtimeModels.LUCY_2_1

    // Caller-owned preview, created lazily and torn down on dispose.
    var localStream by remember { mutableStateOf<RealtimeMediaStream?>(null) }
    var remoteStream by remember { mutableStateOf<RealtimeMediaStream?>(null) }
    var client by remember { mutableStateOf<DecartClient?>(null) }

    LaunchedEffect(selectedModel) {
        localStream?.dispose()
        localStream = null
        val tmp = DecartClient(context, DecartClientConfig(apiKey = apiKey))
        localStream = tmp.realtime.createLocalVideoStream(
            model = selectedModel,
            facing = FacingMode.FRONT,
            mirror = MirrorMode.AUTO,
        )
        tmp.release() // we only used it to build the preview
    }

    LaunchedEffect(client) {
        val c = client ?: return@LaunchedEffect
        launch { c.realtime.connectionState.collect { connectionState = it } }
        launch {
            c.realtime.remoteStreamUpdates.collectLatest { remoteStream = it }
        }
        launch {
            c.realtime.errors.collect { Log.e("Decart", it.message ?: "error") }
        }
    }

    DisposableEffect(Unit) {
        onDispose {
            client?.release()
            client = null
            localStream?.dispose()
            localStream = null
        }
    }

    val isConnected = connectionState == ConnectionState.CONNECTED ||
        connectionState == ConnectionState.GENERATING

    val permissionLauncher = rememberLauncherForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        if (!granted) return@rememberLauncherForActivityResult
        val preview = localStream ?: return@rememberLauncherForActivityResult
        val newClient = DecartClient(context, DecartClientConfig(apiKey = apiKey))
        client = newClient
        coroutineScope.launch {
            try {
                newClient.realtime.connect(
                    options = ConnectOptions(
                        model = selectedModel,
                        initialPrompt = InitialPrompt(prompt, enhance = true),
                        facing = FacingMode.FRONT,
                        publishCamera = true,
                    ),
                    localStream = preview,
                )
            } catch (e: Exception) {
                Log.e("Decart", "connect failed", e)
            }
        }
    }

    Column(
        modifier = Modifier.fillMaxSize().padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(12.dp),
    ) {
        // Remote video
        Box(modifier = Modifier.weight(1f).fillMaxWidth()) {
            LiveKitVideoView(
                track = remoteStream?.videoTrack,
                room = remoteStream?.room ?: localStream?.room,
                modifier = Modifier.fillMaxSize(),
            )
        }

        Text("Status: $connectionState")

        Row(modifier = Modifier.fillMaxWidth()) {
            OutlinedTextField(
                value = prompt,
                onValueChange = { prompt = it },
                label = { Text("Style prompt") },
                modifier = Modifier.weight(1f),
            )
            Spacer(modifier = Modifier.width(8.dp))
            Button(
                onClick = {
                    coroutineScope.launch {
                        try {
                            client?.realtime?.setPrompt(prompt, enhance = true)
                        } catch (e: Exception) {
                            Log.e("Decart", "setPrompt failed", e)
                        }
                    }
                },
                enabled = isConnected,
            ) { Text("Send") }
        }

        Button(
            onClick = {
                if (isConnected) {
                    client?.realtime?.disconnect()
                    client?.release()
                    client = null
                } else {
                    permissionLauncher.launch(Manifest.permission.CAMERA)
                }
            },
            modifier = Modifier.fillMaxWidth(),
        ) { Text(if (isConnected) "Disconnect" else "Connect") }
    }
}

@Composable
fun LiveKitVideoView(
    track: VideoTrack?,
    room: Room?,
    modifier: Modifier = Modifier,
) {
    if (room == null) return
    val rendererRef = remember { mutableStateOf<TextureViewRenderer?>(null) }
    val boundTrack = remember { mutableStateOf<VideoTrack?>(null) }

    AndroidView(
        modifier = modifier,
        factory = { ctx ->
            TextureViewRenderer(ctx).also { r ->
                r.init(room.lkObjects.eglBase.eglBaseContext, null)
                r.setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FILL)
                rendererRef.value = r
                track?.addRenderer(r)
                boundTrack.value = track
            }
        },
        update = { r ->
            if (boundTrack.value !== track) {
                boundTrack.value?.removeRenderer(r)
                track?.addRenderer(r)
                boundTrack.value = track
            }
        },
    )

    DisposableEffect(Unit) {
        onDispose {
            boundTrack.value?.removeRenderer(rendererRef.value ?: return@onDispose)
            try { rendererRef.value?.release() } catch (_: Exception) {}
        }
    }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Let the model registry size the camera">
    Use `realtime.createLocalVideoStream(model, ...)` (or the static factory) so capture dimensions match the model exactly. Lucy 2.x and VTON models capture at `1280x720`; Lucy Restyle 2 at `1280x704`.
  </Accordion>

  <Accordion title="Use suspend `setPrompt` from a coroutine">
    `setPrompt` and `setImage` are `suspend` functions that wait for the server ack and throw on ack failure, timeout, or disconnect. Always call them from a coroutine (`lifecycleScope`, `viewModelScope`, `rememberCoroutineScope()`) and handle exceptions. Reach for `setPromptAsync` / `setImageAsync` only when you need a `Deferred` handle.
  </Accordion>

  <Accordion title="Enable prompt enrichment">
    Keep `enhance = true` (default) so Decart's AI expands simple prompts. Disable it only when you need exact prompt control.
  </Accordion>

  <Accordion title="Re-attach the renderer on auto-reconnect">
    `remoteStreamUpdates` emits a fresh `RealtimeMediaStream` after each reconnect. Remove the previous track from your renderer and add the new one — failing to do so leaves the renderer bound to a dead track.
  </Accordion>

  <Accordion title="Dispose caller-owned streams">
    If you call `createLocalVideoStream` yourself, dispose the returned `RealtimeMediaStream` from your lifecycle hook (`onCleared`, `DisposableEffect.onDispose`). The Room owns native resources that don't get freed otherwise.
  </Accordion>

  <Accordion title="Test on real devices">
    Always test camera features on real Android devices. The emulator does not support camera capture for realtime sessions.
  </Accordion>

  <Accordion title="Request permissions properly">
    Request `CAMERA` permission at runtime before attempting to connect. (Realtime audio is not currently supported, so `RECORD_AUDIO` isn't required.) Handle permission denials gracefully in your UI.
  </Accordion>
</AccordionGroup>

## API Reference

### `DecartClient(context, config)`

Top-level entry point. Exposes `realtime: RealTimeClient` and `queue: QueueClient`. Use `DecartClientConfig(apiKey, baseUrl?, httpBaseUrl?, logLevel?)`. Call `client.release()` to tear down both sub-clients.

### `realtime.createLocalVideoStream(model, facing, mirror, configuration?, includeMicrophone?)`

Build a caller-owned preview `RealtimeMediaStream` sized to `model.width` × `model.height`. Pass it to `connect(..., localStream = ...)` so preview and publish share a LiveKit `Room`. Caller must `dispose()` the stream.

**Parameters:**

* `model: RealtimeModel` - Model to size the capture for
* `facing: FacingMode` - `FRONT` (default) or `BACK`
* `mirror: MirrorMode` - `AUTO` (default), `OFF`, or `ON`
* `configuration: RealtimeConfiguration` (optional) - Codec / bitrate / framerate overrides
* `includeMicrophone: Boolean` - Ignored; audio is not yet supported

Overload: `createLocalVideoStream(width, height, facing, ...)` takes explicit dimensions instead of a model. Static `RealTimeClient.createLocalVideoStream(context, model, ...)` lets you build a preview before instantiating a client.

### `realtime.connect(options, localStream?)`

Suspend. Join the model's LiveKit room and (by default) publish the local camera. Returns the remote `RealtimeMediaStream` and also emits it via `onRemoteStream` / `remoteStreamUpdates`.

**`ConnectOptions` parameters:**

* `model: RealtimeModel` (required) - Realtime model from `RealtimeModels`
* `initialPrompt: InitialPrompt?` - Starting prompt (text + enhance)
* `initialImage: String?` - Base64-encoded reference image
* `resolution: Resolution?` - `P720` or `P1080`. Omit for the server's 720p default; pass `P1080` to request 1080p from supported models.
* `speed: Speed?` - `Speed.FAST` opts into [fast mode](#fast-mode) (2x rate) on supported models. Omit for standard mode. Requires 0.8.1+.
* `realtimeConfiguration: RealtimeConfiguration` - Codec / bitrate / framerate tuning
* `publishCamera: Boolean` - Open the camera and publish (default `true`)
* `publishMicrophone: Boolean` - Ignored in 0.7; audio is not supported
* `facing: FacingMode` - `FRONT` (default) or `BACK`. Only used when the SDK opens its own camera.
* `mirror: MirrorMode` - `AUTO` (default), `OFF`, or `ON`
* `onRemoteStream: ((RealtimeMediaStream) -> Unit)?` - Callback when a (re)connected remote stream is available

**Throws** on signaling, ICE, or LiveKit room failures.

### `realtime.setPrompt(prompt, enhance, timeoutMs)`

Suspend. Update the prompt and wait for the server ack.

**Parameters:**

* `prompt: String` - Style description
* `enhance: Boolean` - Auto-enhance the prompt (default: `true`)
* `timeoutMs: Long` - Ack timeout in ms (default: `15_000`)

**Throws** `IllegalStateException` if not connected, or a `DecartError` on ack failure, timeout, or websocket disconnect.

### `realtime.setPromptAsync(prompt, enhance, timeoutMs)`

Same parameters as `setPrompt` but returns `Deferred<Unit>`. Call `await()` to observe ack failure / timeout / disconnect.

### `realtime.setImage(imageBase64, prompt, enhance, timeout)`

Suspend. Send (or clear, with `null`) a reference image.

**Parameters:**

* `imageBase64: String?` - Base64-encoded image, or `null` to clear
* `prompt: String?` - Optional text prompt
* `enhance: Boolean?` - Whether to enhance the prompt
* `timeout: Long` - Ack timeout in ms (default: `30_000`)

**Throws** `IllegalStateException` if not connected.

### `realtime.setImageAsync(imageBase64, prompt, enhance, timeout)`

Same parameters as `setImage` but returns `Deferred<Unit>`.

### `realtime.disconnect()` / `realtime.release()`

`disconnect()` ends the current session. `release()` cancels the SDK's coroutine scope; call it when the client is no longer needed (and prefer `client.release()` to also clean up the queue client).

### `realtime.isConnected()`

**Returns:** `Boolean` - Whether the current connection state is `CONNECTED` or `GENERATING`.

### `RealtimeMediaStream`

* `videoTrack: VideoTrack?` - LiveKit video track; pass to your renderer via `addRenderer(...)` / `removeRenderer(...)`.
* `audioTrack: AudioTrack?` - Deprecated; always `null` in 0.7.
* `id: String` - Stream identifier (`stream-local` or `stream-remote`).
* `room: Room?` - LiveKit room that owns the tracks. Use `room.lkObjects.eglBase.eglBaseContext` when initializing renderers.
* `dispose()` - Tear down tracks and the room. Safe to call multiple times.

### Observable State

| Property | Type | Description |
| - | - | - |
| `connectionState` | `StateFlow<ConnectionState>` | Current connection state |
| `connectionChange` | `StateFlow<ConnectionState>` | JS-aligned alias for `connectionState` |
| `errors` | `SharedFlow<DecartError>` | Error events |
| `generationTicks` | `SharedFlow<GenerationTickMessage>` | Per-second tick during generation |
| `generationEnded` | `SharedFlow<GenerationEndedMessage>` | Generation lifecycle end events |
| `queuePositionUpdates` | `SharedFlow<QueuePositionMessage>` | Queue position updates while waiting for a server slot |
| `localStreamUpdates` | `SharedFlow<RealtimeMediaStream>` | Local LiveKit stream updates |
| `remoteStreamUpdates` | `SharedFlow<RealtimeMediaStream>` | Remote LiveKit stream updates (including auto-reconnect rebinds) |
| `sessionStarted` | `StateFlow<SessionStarted?>` | `(sessionId, subscribeToken)` once the LiveKit room info arrives |
| `subscribeToken` | `String?` | Token to hand to viewer / subscribe clients |
| `sessionId` | `String?` | Current session id |
| `diagnostics` | `SharedFlow<DiagnosticEvent>` | Connection diagnostic events |
| `stats` | `SharedFlow<PublishStatsEvent>` | Publisher outbound video stats |

## Next Steps

<CardGroup>
  <Card title="Queue API" icon="layer-group" href="/sdks/android-queue">
    Generate and transform videos with batch processing and Flow-based progress
  </Card>

  <Card title="SDK Overview" icon="android" href="/sdks/android">
    Installation, setup, and Android SDK fundamentals
  </Card>
</CardGroup>


# Overview
Source: https://docs.platform.decart.ai/sdks/javascript

A JavaScript SDK for Decart's models

<Card title="GitHub" icon="github" href="https://github.com/DecartAI/sdk">
  View source code and contribute
</Card>

## Installation

```bash theme={null}
npm install @decartai/sdk
# or
pnpm add @decartai/sdk
# or
yarn add @decartai/sdk
```

## Quick Start

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";
import { writeFileSync } from "fs";

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

// Edit a video using the Queue API
const result = await client.queue.submitAndPoll({
  model: models.video("lucy-2.1"),
  data: videoFile,
  prompt: "Transform into anime style",
  resolution: "720p",
  onStatusChange: (job) => {
    console.log(`Status: ${job.status}`);
  },
});

if (result.status === "completed") {
  const buffer = Buffer.from(await result.data.arrayBuffer());
  writeFileSync("output.mp4", buffer);
  console.log("Video saved!");
}
```

## What can you build?

The SDK provides three main APIs for different use cases:

| If you need to... | Use | Main method |
| - | - | - |
| Transform live streams over WebRTC | Realtime API | `client.realtime.connect()` |
| Generate/edit videos asynchronously | Queue API | `client.queue.submitAndPoll()` |
| Generate/edit images synchronously | Process API | `client.process()` |

<CardGroup>
  <Card title="Realtime API" href="/sdks/javascript-realtime">
    Realtime video streams
  </Card>

  <Card title="Queue API" href="/sdks/javascript-queue">
    Video processing
  </Card>

  <Card title="Process API" href="/sdks/javascript-process">
    Image editing
  </Card>
</CardGroup>

<Tip>
  If you're building a browser app and want to avoid exposing API keys, route SDK calls through your backend proxy. See the proxy examples in `sdks/sdk/examples/nextjs-proxy` and `sdks/sdk/examples/express-proxy`.
</Tip>

## Client Setup

All APIs share the same client initialization:

```typescript theme={null}
import { createDecartClient } from "@decartai/sdk";

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

**Parameters:**

* `apiKey` - Your Decart API key from the [platform](https://platform.decart.ai), or a short-lived client token in the browser. Required unless `apiKeyProvider` or `proxy` is set
* `apiKeyProvider` (optional) - `() => string | Promise<string>`, called right before every realtime connect, reconnect and subscribe so each dial carries a fresh client token. Wins over `apiKey` for realtime; the HTTP APIs still use `apiKey` or `proxy`. See [Token lifetime](/getting-started/client-tokens#token-lifetime)
* `baseUrl` (optional) - Custom API endpoint (defaults to Decart's production API)
* `telemetry` (optional) - Enable SDK telemetry for realtime observability (default: `true`)

<Note>
  Store your API key in environment variables. Never commit API keys to version control.
</Note>

## Client Tokens

For client-side applications (browsers, mobile apps) using the Realtime API, create short-lived client tokens instead of exposing your permanent API key:

```typescript theme={null}
// On your backend — basic (60s TTL, unrestricted)
const { apiKey, expiresAt } = await client.tokens.create();

// Or scoped to specific models and origins with a longer TTL
const token = await client.tokens.create({
  expiresIn: 300,
  allowedModels: ["lucy-2.1"],
  allowedOrigins: ["https://app.example.com"], // browser-enforced; canonical origin
});
// Send token.apiKey to your frontend; it's a signed client token the gateway verifies offline.
```

Client tokens expire **60 seconds** after minting by default (`expiresIn`, 1–3600 s). In the browser, mint right before `connect()` or pass `apiKeyProvider` so the SDK fetches a fresh token for every connect and reconnect; an expired token is rejected with `TOKEN_EXPIRED` before any socket is opened.

<Tip>
  See [Client Tokens](/getting-started/client-tokens) for details on secure realtime auth and [Token lifetime](/getting-started/client-tokens#token-lifetime) for the expiry rules.
</Tip>

## Reusable File Uploads

`client.files.upload(file)` uploads a reference image once and returns a `file_…` id that you can pass to realtime `connect({ initialState: { image } })`, `set({ image })`, or `setImage(...)` — handy when the same asset is reused across many updates or across reconnects. `client.files.getByMd5(md5)` finds an upload again by the MD5 of its bytes when you no longer have the id. See [Reference Image Uploads](/sdks/javascript-realtime#reference-image-uploads) on the realtime page.

## Available Models

Import models from the SDK to use with either API:

```typescript theme={null}
import { models } from "@decartai/sdk";

// Realtime models
models.realtime("lucy-2.5");              // Realtime video editing (latest)
models.realtime("lucy-vton-3.5");         // Virtual try-on
models.realtime("lucy-vton-3.6");         // Virtual try-on (newest)
models.realtime("lucy-restyle-2");        // Realtime video restyling

// Video models
models.video("lucy-2.5");                // Video editing (latest)
models.video("lucy-vton-3.5");           // Virtual try-on
models.video("lucy-vton-3.6");           // Virtual try-on (newest)
models.video("lucy-restyle-2");          // Video restyling

// Image models
models.image("lucy-image-2");            // Image editing

// Latest aliases — always point to the newest version
models.realtime("lucy-latest");           // Latest realtime editing model
models.video("lucy-latest");              // Latest video editing model
models.video("lucy-vton-latest");         // Latest virtual try-on model
models.video("lucy-restyle-latest");      // Latest video restyling model
models.image("lucy-image-latest");        // Latest image editing model
```

<Accordion title="Previous generation models">
  ```typescript theme={null}
  // Realtime models
  models.realtime("lucy-2.1");              // Previous realtime video editing

  // Video models
  models.video("lucy-2.1");                // Previous video editing
  ```
</Accordion>

## TypeScript Support

The SDK is written in TypeScript with full type definitions. Each model enforces its own required inputs, so you'll get autocomplete and helpful errors if something is missing.

```typescript theme={null}
// Video editing requires 'data' field
await client.queue.submitAndPoll({
  model: models.video("lucy-2.1"),
  prompt: "Transform into anime style",
  data: videoFile, // ✅ Required
});

// Image editing requires 'data' field
await client.process({
  model: models.image("lucy-image-2"),
  prompt: "Change the background to a beach",
  data: imageFile, // ✅ Required
});
```

## Ready to start building?

<CardGroup>
  <Card title="Realtime API Guide" href="/sdks/javascript-realtime">
    **Build realtime experiences**

    Learn WebRTC integration, camera handling, and how to create interactive video applications.
  </Card>

  <Card title="Queue API Guide" href="/sdks/javascript-queue">
    **Video processing**

    Edit videos, control motion, and transform videos with style transfer.
  </Card>

  <Card title="Process API Guide" href="/sdks/javascript-process">
    **Image editing**

    Edit and transform images on-demand with synchronous processing.
  </Card>
</CardGroup>


# Process API
Source: https://docs.platform.decart.ai/sdks/javascript-process

Transform images on-demand

The Process API enables you to transform existing images with style transfer and edits. Perfect for building content creation tools, media processing pipelines, batch transformations, and creative applications.

<Note>
  For video processing (video editing, motion control), use the [Queue API](/sdks/javascript-queue) which provides asynchronous job-based processing.
</Note>

## Image

### Image Editing

Transform and restyle existing images:

```typescript theme={null}
const imageFile = document.querySelector('input[type="file"]').files[0];

const result = await client.process({
  model: models.image("lucy-image-2"),
  prompt: "Oil painting style with impressionist brushstrokes",
  data: imageFile,
  enhance_prompt: true,
  seed: 123,
});
```

You can also provide a reference image to guide the edit — for example, to add a specific item:

```typescript theme={null}
const imageFile = document.querySelector('input[type="file"]').files[0];
const referenceImage = document.querySelector('#reference-input').files[0];

const result = await client.process({
  model: models.image("lucy-image-2"),
  prompt: "Add these sunglasses to the person's face",
  data: imageFile,
  reference_image: referenceImage,
});
```

**Parameters:**

* `prompt` (required) - Text description of the style transformation
* `data` (required) - Input image (File, Blob, URL, or ReadableStream)
* `reference_image` (optional) - Reference image to guide the edit (File, Blob, URL, or ReadableStream)
* `seed` (optional) - Random seed for reproducible results
* `resolution` (optional) - Output resolution
* `enhance_prompt` (optional) - Auto-enhance the prompt for better results

**Model:** `lucy-image-2`

***

## Input Types

The `data`, `reference_image`, `start`, and `end` parameters accept flexible input types:

```typescript theme={null}
type FileInput = File | Blob | ReadableStream | URL | string;
```

**Examples:**

```typescript theme={null}
// Browser file input
const file = document.querySelector('input[type="file"]').files[0];

// Blob
const blob = new Blob([arrayBuffer], { type: 'image/jpeg' });

// URL string
const url = "https://example.com/image.jpg";

// URL object
const urlObj = new URL("https://example.com/video.mp4");

// ReadableStream (advanced)
const stream = response.body;
```

## Cancellation

Cancel long-running operations using AbortController:

```typescript theme={null}
const controller = new AbortController();

try {
  const result = await client.process({
    model: models.image("lucy-image-2"),
    prompt: "Transform into epic fantasy landscape with dragons",
    data: imageFile,
    signal: controller.signal,
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Generation cancelled');
  }
}

// Cancel the request
controller.abort();
```

You can use this to implement cancel buttons in your UI:

```typescript theme={null}
let currentController: AbortController | null = null;

async function editImage(prompt: string) {
  // Cancel previous request if any
  currentController?.abort();

  currentController = new AbortController();

  const result = await client.process({
    model: models.image("lucy-image-2"),
    prompt,
    data: imageFile,
    signal: currentController.signal,
  });

  return result;
}

function cancelGeneration() {
  currentController?.abort();
}
```

## Error Handling

The SDK throws specific errors for different failure scenarios:

```typescript theme={null}
import { createDecartClient, type DecartSDKError } from "@decartai/sdk";

try {
  const result = await client.process({
    model: models.image("lucy-image-2"),
    prompt: "Oil painting style with impressionist brushstrokes",
    data: imageFile,
  });
} catch (error) {
  const sdkError = error as DecartSDKError;

  switch (sdkError.code) {
    case "INVALID_INPUT":
      console.error("Invalid input:", sdkError.message);
      break;
    case "INVALID_API_KEY":
      console.error("Invalid API key");
      break;
    case "PROCESSING_ERROR":
      console.error("Processing failed:", sdkError.message);
      break;
    default:
      console.error("Unknown error:", sdkError.message);
  }
}
```

If you provide invalid inputs, you'll get clear error messages:

```typescript theme={null}
// Missing required field
await client.process({
  model: models.image("lucy-image-2"),
  prompt: "test",
  // Missing 'data' field
});
// Error: Invalid inputs for lucy-image-2: data is required
```

## API Reference

### `client.process(options)`

Generate or transform images.

**Parameters:**

* `options` - Configuration object with model and inputs:
  * `model` - Model from `models.image()`
  * `signal?` - Optional AbortSignal for cancellation
  * Additional fields depend on the model (see below)

**Returns:** `Promise<Blob>` - The generated/transformed image

**Inputs by Model:**

<Accordion title="Image Editing (lucy-image-2)">
  * `prompt: string` - Style description (required)
  * `data: FileInput` - Input image (required)
  * `reference_image?: FileInput` - Reference image to guide the edit
  * `seed?: number` - Random seed
  * `resolution?: string` - Output resolution
  * `enhance_prompt?: boolean` - Auto-enhance prompt
</Accordion>

## Next Steps

<CardGroup>
  <Card title="Queue API" icon="video" href="/sdks/javascript-queue">
    Asynchronous video processing with job-based queue
  </Card>

  <Card title="Realtime API" icon="bolt" href="/sdks/javascript-realtime">
    Transform video streams in realtime with WebRTC
  </Card>
</CardGroup>


# Queue API
Source: https://docs.platform.decart.ai/sdks/javascript-queue

Asynchronous job-based video processing

The Queue API is the primary way to process videos with the JavaScript SDK. Submit jobs that are processed asynchronously in the background, then poll for status and retrieve results when complete.

<Note>
  All video processing (video editing, restyling, motion control) uses the Queue API. For image editing, use the [Process API](/sdks/javascript-process).
</Note>

## Overview

The Queue API provides four main methods:

* `submit()` - Submit a job and get a job ID immediately
* `status()` - Check the status of a submitted job
* `result()` - Retrieve the completed video
* `submitAndPoll()` - Submit and automatically poll until completion

## Submit a Job

Submit a video editing job and receive a job ID immediately:

```typescript theme={null}
const job = await client.queue.submit({
  model: models.video("lucy-2.1"),
  data: videoFile,
  prompt: "Transform into anime style",
});

console.log(`Job ID: ${job.job_id}`);
console.log(`Status: ${job.status}`); // "pending"
```

**Returns:**

* `job_id` - Unique identifier for the job
* `status` - Initial status (`"pending"`)

***

## Check Job Status

Poll the status of a submitted job:

```typescript theme={null}
const status = await client.queue.status(job.job_id);

console.log(`Status: ${status.status}`); // "pending", "processing", "completed", or "failed"
```

**Status Values:**

| Status | Description |
| - | - |
| `pending` | Job is queued, waiting to be processed |
| `processing` | Job is currently being processed |
| `completed` | Job finished successfully |
| `failed` | Job failed or timed out (timeout after 10 minutes) |

***

## Get Job Result

Retrieve the video once the job is completed:

```typescript theme={null}
import { writeFileSync } from "fs";

// First check status
const status = await client.queue.status(job.job_id);

if (status.status === "completed") {
  const result = await client.queue.result(job.job_id);

  if (result.status === "completed") {
    // result.data is a Blob
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("output.mp4", buffer);
    console.log("Video saved!");
  } else {
    console.error(`Error: ${result.error}`);
  }
}
```

**Returns:**

* `status` - Either `"completed"` or `"failed"`
* `data` - Video Blob (when completed)
* `error` - Error message (when failed)

***

## Submit and Poll

The easiest way to use the Queue API - submit a job and automatically poll until completion:

```typescript theme={null}
import { writeFileSync } from "fs";

const result = await client.queue.submitAndPoll({
  model: models.video("lucy-2.1"),
  prompt: "A serene lake at sunset with mountains in the background",
  resolution: "720p",
  onStatusChange: (job) => {
    console.log(`Status: ${job.status}`);
  },
});

if (result.status === "completed") {
  const buffer = Buffer.from(await result.data.arrayBuffer());
  writeFileSync("output.mp4", buffer);
  console.log("Video saved!");
} else {
  console.error(`Generation failed: ${result.error}`);
}
```

**Parameters:**

* All standard model parameters (prompt, resolution, etc.)
* `onStatusChange` (optional) - Callback function called on each status change

***

## TypeScript Types

```typescript theme={null}
import type {
  JobStatus,
  JobSubmitResponse,
  JobStatusResponse,
  QueueJobResult,
} from "@decartai/sdk";

// Job status values
type JobStatus = "pending" | "processing" | "completed" | "failed";

// Submit response
interface JobSubmitResponse {
  job_id: string;
  status: JobStatus;
}

// Status response
interface JobStatusResponse {
  job_id: string;
  status: JobStatus;
}

// Result (discriminated union)
type QueueJobResult =
  | { status: "completed"; data: Blob }
  | { status: "failed"; error: string };
```

***

## Complete Example

### Node.js

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";
import { writeFileSync } from "fs";

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

async function editVideo() {
  console.log("Submitting video editing job...");

  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-2.1"),
    data: videoFile,
    prompt: "Transform into anime style",
    onStatusChange: (job) => {
      console.log(`  Status: ${job.status}`);
    },
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("cityscape.mp4", buffer);
    console.log("Video saved to cityscape.mp4");
  } else {
    console.error(`Editing failed: ${result.error}`);
  }
}

editVideo();
```

***

## Video Editing with Queue

Transform videos with style transfer:

```typescript theme={null}
import { readFileSync, writeFileSync } from "fs";

const videoBuffer = readFileSync("input-video.mp4");
const videoBlob = new Blob([videoBuffer], { type: "video/mp4" });

const result = await client.queue.submitAndPoll({
  model: models.video("lucy-2.1"),
  prompt: "Convert to anime style with vibrant colors",
  data: videoBlob,
  onStatusChange: (job) => {
    console.log(`Status: ${job.status}`);
  },
});

if (result.status === "completed") {
  const buffer = Buffer.from(await result.data.arrayBuffer());
  writeFileSync("styled-video.mp4", buffer);
}
```

***

## Cancellation with AbortSignal

Cancel queue operations using AbortController:

```typescript theme={null}
const controller = new AbortController();

// Start generation
const resultPromise = client.queue.submitAndPoll({
  model: models.video("lucy-2.1"),
  prompt: "A beautiful sunset",
  signal: controller.signal,
  onStatusChange: (job) => {
    console.log(`Status: ${job.status}`);
  },
});

// Cancel after 30 seconds (example)
setTimeout(() => {
  controller.abort();
  console.log("Cancellation requested");
}, 30000);

try {
  const result = await resultPromise;
  // Handle result...
} catch (error) {
  if (error.name === "AbortError") {
    console.log("Generation cancelled");
  }
}
```

***

## Manual Polling

For custom polling logic, you can manually poll for status:

```typescript theme={null}
import { writeFileSync } from "fs";

// Submit job
const job = await client.queue.submit({
  model: models.video("lucy-2.1"),
  prompt: "A serene lake at sunset",
});

console.log(`Job submitted: ${job.job_id}`);

// Manual polling loop
while (true) {
  const status = await client.queue.status(job.job_id);
  console.log(`Status: ${status.status}`);

  if (status.status === "completed") {
    const result = await client.queue.result(job.job_id);
    if (result.status === "completed") {
      const buffer = Buffer.from(await result.data.arrayBuffer());
      writeFileSync("output.mp4", buffer);
      console.log("Video saved!");
    }
    break;
  } else if (status.status === "failed") {
    console.error("Generation failed");
    break;
  }

  // Wait before next poll
  await new Promise((r) => setTimeout(r, 2000));
}
```

***

## Error Handling

```typescript theme={null}
import {
  createDecartClient,
  models,
  QueueSubmitError,
  QueueStatusError,
  QueueResultError,
  DecartSDKError,
} from "@decartai/sdk";

try {
  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-2.1"),
    prompt: "A beautiful sunset",
  });
} catch (error) {
  if (error instanceof QueueSubmitError) {
    console.error(`Failed to submit job: ${error.message}`);
  } else if (error instanceof QueueStatusError) {
    console.error(`Failed to check status: ${error.message}`);
  } else if (error instanceof QueueResultError) {
    console.error(`Failed to get result: ${error.message}`);
  } else if (error instanceof DecartSDKError) {
    console.error(`SDK error: ${error.message}`);
  }
}
```

***

## Supported Models

All non-realtime video models support queue processing:

| Model | Type | Description |
| - | - | - |
| `lucy-2.5` | Video-to-Video | Video editing (latest) |
| `lucy-vton-3.5` | Video-to-Video | Virtual try-on |
| `lucy-vton-3.6` | Video-to-Video | Virtual try-on (newest) |
| `lucy-restyle-2` | Video-to-Video | Video restyling |

<Accordion title="Latest aliases">
  | Alias | Description |
  | - | - |
  | `lucy-latest` | Always the latest editing model |
  | `lucy-vton-latest` | Always the latest virtual try-on model |
  | `lucy-restyle-latest` | Always the latest restyling model |
</Accordion>

<Accordion title="Previous generation models">
  | Model | Type | Description |
  | - | - | - |
  | `lucy-2.1` | Video-to-Video | Previous video editing |
</Accordion>

***

## API Reference

### `client.queue.submit(options)`

Submit a job for processing.

**Parameters:**

* `options: QueueSubmitOptions` - Model and input parameters
  * `model` - Model from `models.video()`
  * `signal?: AbortSignal` - Optional abort signal
  * Additional model-specific parameters

**Returns:** `Promise<JobSubmitResponse>`

* `job_id: string` - Unique job identifier
* `status: JobStatus` - Initial status ("pending")

***

### `client.queue.status(jobId)`

Check the status of a job.

**Parameters:**

* `jobId: string` - The job identifier

**Returns:** `Promise<JobStatusResponse>`

* `job_id: string` - Job identifier
* `status: JobStatus` - Current status

***

### `client.queue.result(jobId)`

Get the result of a completed job.

**Parameters:**

* `jobId: string` - The job identifier

**Returns:** `Promise<QueueJobResult>`

* When completed: `{ status: "completed", data: Blob }`
* When failed: `{ status: "failed", error: string }`

***

### `client.queue.submitAndPoll(options)`

Submit a job and poll until completion.

**Parameters:**

* `options: QueueSubmitAndPollOptions` - Model and input parameters
  * `onStatusChange?: (job: JobStatusResponse) => void` - Status change callback
  * `signal?: AbortSignal` - Optional abort signal
  * Additional model-specific parameters

**Returns:** `Promise<QueueJobResult>`

***

## Next Steps

<CardGroup>
  <Card title="Process API" icon="image" href="/sdks/javascript-process">
    Synchronous image editing
  </Card>

  <Card title="Realtime API" icon="bolt" href="/sdks/javascript-realtime">
    Transform video streams in realtime with WebRTC
  </Card>
</CardGroup>


# Realtime API
Source: https://docs.platform.decart.ai/sdks/javascript-realtime

Transform video streams in realtime with WebRTC

The Realtime API enables you to transform live video streams with minimal latency using WebRTC. Perfect for building camera effects, video conferencing filters, VR/AR applications, and interactive live streaming.

## Quick Start

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

const model = models.realtime("lucy-2.1");

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

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

const characterPhoto = document.querySelector("input[type=file]").files[0];

const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (transformedStream) => {
    videoElement.srcObject = transformedStream;
  },
  initialState: {
    prompt: {
      text: "Transform into this character",
      enhance: true,
    },
    image: characterPhoto,
  },
});

// Update prompt or reference image later in one atomic call
await realtimeClient.set({
  prompt: "Add silver futuristic sunglasses",
  image: characterPhoto,
  enhance: true,
});

// Disconnect when done
realtimeClient.disconnect();
```

## Client-Side Authentication

For browser applications, use client tokens instead of your permanent API key. Client tokens are short-lived tokens safe to expose in client-side code.

<Info>
  Learn more about [client tokens](/getting-started/client-tokens) and why they're important for security.
</Info>

### Step 1: Create a backend endpoint

Your server creates client tokens using the SDK:

<CodeGroup>
  ```javascript Express.js theme={null}
  import express from "express";
  import { createDecartClient } from "@decartai/sdk";

  const app = express();

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

  // Endpoint to generate client tokens for authenticated users
  app.post("/api/realtime-token", async (req, res) => {
    try {
      const token = await client.tokens.create({
        expiresIn: 300,              // 5 minutes
        allowedModels: ["lucy-2.1"], // restrict to this model
      });
      res.json(token);
    } catch (error) {
      console.error("Token generation error:", error);
      res.status(500).json({ error: "Failed to generate token" });
    }
  });

  app.listen(3000);
  ```

  ```javascript Next.js API Route theme={null}
  // app/api/realtime-token/route.ts
  import { createDecartClient } from "@decartai/sdk";
  import { NextResponse } from "next/server";

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

  export async function POST() {
    try {
      const token = await client.tokens.create({
        expiresIn: 300,
        allowedModels: ["lucy-2.1"],
      });
      return NextResponse.json(token);
    } catch (error) {
      return NextResponse.json(
        { error: "Failed to generate token" },
        { status: 500 }
      );
    }
  }
  ```
</CodeGroup>

### Step 2: Use the client token in your frontend

Client tokens expire **60 seconds** after minting by default, so a token fetched on page load is usually dead by the time the user has granted the camera and pressed start. Hand the SDK a function that fetches one instead; it is called right before every `connect()`, connect retry and reconnect:

```typescript theme={null}
import { createDecartClient, models } from "@decartai/sdk";

// One client for the page. It holds no credential of its own: the provider
// supplies one per dial.
const client = createDecartClient({
  apiKeyProvider: async () => {
    const res = await fetch("/api/realtime-token", { method: "POST" }); // your server: client.tokens.create(...)
    const { apiKey } = await res.json(); // the client token, never your permanent key
    return apiKey;
  },
});

async function connectToRealtime() {
  // 1. Get user's camera stream
  const model = models.realtime("lucy-restyle-2");
  const stream = await navigator.mediaDevices.getUserMedia({
    video: {
      frameRate: model.fps,
      width: model.width,
      height: model.height,
    },
  });

  // 2. Connect. The SDK fetches a fresh token first, and again on every reconnect.
  const realtimeClient = await client.realtime.connect(stream, {
    model,
    onRemoteStream: (transformedStream) => {
      document.getElementById("output-video").srcObject = transformedStream;
    },
    initialState: {
      prompt: { text: "Anime style" },
    },
  });

  return realtimeClient;
}
```

If you pass a static `apiKey` instead, mint it right before `connect()` and size `expiresIn` to your connect window. The SDK reads the token's `exp` before every dial and rejects an expired one with `TOKEN_EXPIRED` instead of opening a socket: `connect()` rejects, and a reconnect emits an `error` event and moves to `disconnected`. See [Token lifetime](/getting-started/client-tokens#token-lifetime).

<Warning>
  Client tokens only prevent **new** connections after expiry. Active WebRTC sessions continue working even after the token expires.
</Warning>

## Connecting

### Getting Camera Access

Request access to the user's camera using the WebRTC getUserMedia API:

```typescript theme={null}
const stream = await navigator.mediaDevices.getUserMedia({
  audio: true,
  video: {
    frameRate: 25,
    width: 1280,
    height: 704,
  },
});
```

<Tip>Use the model's `fps`, `width`, and `height` properties to ensure optimal performance.</Tip>

### Establishing Connection

Connect to the Realtime API with your media stream:

```typescript theme={null}
const realtimeClient = await client.realtime.connect(stream, {
  model: models.realtime("lucy-2"),
  onRemoteStream: (transformedStream: MediaStream) => {
    // Display the transformed video
    const videoElement = document.getElementById("output-video");
    videoElement.srcObject = transformedStream;
  },
  initialState: {
    prompt: {
      text: "Lego World",
      enhance: true, // Let Decart enhance the prompt (recommended)
    },
    image: characterPhoto,
  },
});
```

**Parameters:**

* `stream` (required) - MediaStream from getUserMedia
* `model` (required) - Realtime model from `models.realtime()`
* `onRemoteStream` (required) - Callback that receives the transformed video stream
* `mirror` (optional) - Pre-flip the input video before it's sent. `false` (default), `"auto"`, or `true`. See [Front-camera mirroring](#front-camera-mirroring).
* `resolution` (optional) - `"720p"` (default) or `"1080p"`. Requests a 1080p remote stream from supported models.
* `speed` (optional) - `"fast"` opts into [fast mode](#fast-mode) on supported models. Omit for standard mode. Requires v0.2.2+ (earlier versions: `queryParams: { speed: "fast" }`).
* `initialState` (optional) - Pre-configure the session before the first frame
  * `prompt.text` - Style description
  * `prompt.enhance` - Whether to auto-enhance the prompt (default: true)
  * `image` - Reference image (`Blob`, `File`, or URL string)

<Tip>
  Set `initialState.image` and/or `initialState.prompt` so the first frame is already transformed — otherwise viewers briefly see the raw camera feed.
</Tip>

### Front-camera mirroring

Selfie streams should be pre-flipped on the input so server-baked pixels (watermarks, overlays) come out in display orientation. Pass `mirror`:

```typescript theme={null}
const realtimeClient = await client.realtime.connect(stream, {
  model,
  mirror: "auto",
  onRemoteStream: (s) => { videoElement.srcObject = s; },
});
```

* `false` (default) — never mirror.
* `"auto"` — mirror when the input track reports `facingMode: "user"`.
* `true` — always mirror. Use this on desktop webcams (they usually don't report `facingMode`) or when your app already knows the camera is front-facing.

### Fast mode

Fast mode (`speed: "fast"`) gives the session lower latency and higher throughput; output quality is unchanged. It is available for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5`, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode. See [Pricing](/getting-started/pricing#realtime-models).

```typescript theme={null}
const realtimeClient = await client.realtime.connect(stream, {
  model: models.realtime("lucy-2.5"),
  speed: "fast",
  onRemoteStream: (s) => { videoElement.srcObject = s; },
});
```

The option lands on the signaling URL as `?speed=fast`, and the SDK keeps it across auto-reconnects. It requires v0.2.2; on earlier versions pass `queryParams: { speed: "fast" }` instead, which reaches the same query parameter.

Models expose the tier as a capability: `model.supportedSpeeds` lists `"fast"` for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5` only. Passing `speed` for another model logs a warning and connects on the standard tier.

## Managing Prompts

Change the transformation style dynamically without reconnecting:

```typescript theme={null}
// Simple prompt with automatic enhancement
realtimeClient.setPrompt("Anime style");

// Custom detailed prompt without enhancement
realtimeClient.setPrompt(
  "A detailed artistic style with vibrant colors and dramatic lighting",
  { enhance: false }
);
```

**Parameters:**

* `prompt` (required) - Text description of desired style
* `options.enhance` (optional) - Whether to enhance the prompt (default: true)

<Note>Prompt enhancement uses Decart's AI to expand simple prompts for better results. Disable it if you want full control over the exact prompt.</Note>

## Unified State Update

The `set()` method replaces the entire session state in a single atomic call. The new state contains only the fields you provide — any previously set values not included in the call are cleared.

```typescript theme={null}
import type { SetInput } from "@decartai/sdk";

// Set prompt only (clears any previously set image)
await realtimeClient.set({ prompt: "Anime style", enhance: true });

// Set image only (clears any previously set prompt)
const file = document.querySelector("input[type=file]").files[0];
await realtimeClient.set({ image: file });

// Set both prompt and image together
await realtimeClient.set({
  prompt: "Transform into this character",
  image: "https://example.com/character.jpg",
  enhance: true,
});
```

**Parameters (`SetInput`):**

* `prompt` (optional) - Text description of desired style (at least one of `prompt` or `image` is required)
* `enhance` (optional) - Whether to enhance the prompt (default: true)
* `image` (optional) - Reference image as a `Blob`, `File`, URL string, or `null` to clear

<Tip>`set()` replaces the entire state — fields you omit are cleared. Always include every field you want to keep. Use `set()` instead of separate `setPrompt()` and `setImage()` calls to avoid intermediate states.</Tip>

## Reference Image Uploads

If the same reference image is shared across multiple `set()` / `setImage()` calls — or you want it to survive auto-reconnects — upload it once with `client.files.upload(...)` and pass the resulting `file_…` id by reference instead of re-encoding the bytes on every call.

```typescript theme={null}
const ref = await client.files.upload(file);
// ref: { id: "file_...", filename, mime_type, size_bytes, md5, created_at, expires_at }

await realtimeClient.set({ image: ref.id, prompt: "make it cinematic" });
await realtimeClient.set({ image: ref.id, prompt: "now in noir" }); // reused, no re-upload
```

`ref.id` works anywhere a `File` / `Blob` / URL string would — pass it to `connect({ initialState: { image } })`, `realtimeClient.set({ image })`, or `realtimeClient.setImage(image)`. The SDK sends it as an `image_ref` on the wire instead of re-uploading the bytes.

Uploads expire after 24 hours by default. Pass `ttlSeconds` (60 seconds up to 30 days) or `"persistent"` to override:

```typescript theme={null}
const ref = await client.files.upload(file, { ttlSeconds: "persistent" });
```

Cancel an in-flight upload with an `AbortSignal`:

```typescript theme={null}
const controller = new AbortController();
const ref = await client.files.upload(file, { signal: controller.signal });
```

You can also fetch metadata for a previously uploaded file or delete one early:

```typescript theme={null}
const ref = await client.files.get(fileId);
await client.files.delete(fileId);
```

Lost the id? Look the file up by the MD5 of the bytes you uploaded. It resolves to the newest non-expired upload with that hash and rejects when there is none:

```typescript theme={null}
const ref = await client.files.getByMd5("9e107d9d372bb6826bd81d3542a419d6");
await realtimeClient.set({ image: ref.id, prompt: "make it cinematic" });
```

<Tip>For a one-shot use where the same image isn't reused, sticking with a plain `File` / `Blob` is fine — the SDK base64-encodes the bytes inline.</Tip>

## Connection Quality

Two layers report network health on a shared `"good" | "fair" | "poor" | "critical"` scale: a **preflight** check before connecting, and an **in-session** signal while connected. The SDK reports — you decide what to do (gate the UI, warn, fall back).

### Preflight

A fast, network-only reachability check. No session, no cost:

```typescript theme={null}
const { quality, metrics, reasons } = await client.realtime.checkConnectivity();
// metrics: { transport: "udp" | "relay" | "failed", rttMs }
if (quality === "critical") showFallbackUI(reasons);
```

### In-session quality

While connected, the SDK derives a smoothed verdict from live connection stats (latency, packet loss, bandwidth headroom, frame rate) and tells you which dimension is the bottleneck:

```typescript theme={null}
const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (s) => { videoElement.srcObject = s; },
  onConnectionQuality: ({ quality, limitingFactor, metrics }) => {
    // limitingFactor: "bandwidth" | "latency" | "loss" | "stall" | "cpu" | "none"
    // metrics: { rttMs, fps, packetLoss, upstreamJitterMs, availableUpstreamKbps, ... }
    updateSignalBars(quality);
  },
});

realtimeClient.on("connectionQuality", (report) => { /* ... */ });
realtimeClient.getConnectionQuality(); // latest report, or null before the first sample
```

### Glass-to-glass latency

Network RTT alone doesn't reflect the latency users actually feel — a session can read `"good"` while still feeling laggy. In browser sessions, the SDK automatically attaches a capture timestamp using LiveKit frame metadata; the server propagates it through inference and matches it to output playout, surfacing startup (`ttffMs`) and steady-state (`medianMs`) latency. When present, glass-to-glass drives the latency verdict instead of RTT.

```typescript theme={null}
const realtimeClient = await client.realtime.connect(stream, {
  model,
});

// g2g updates every stats tick — read it off the `stats` event (the
// `connectionQuality` verdict is debounced and would go stale between changes).
realtimeClient.on("stats", ({ glassToGlass }) => {
  console.log(glassToGlass?.ttffMs, glassToGlass?.medianMs);
});
```

<Warning>Upgrade viewers before publishers. A browser publisher advertises frame timing by default, so the server appends a packet trailer to every frame. Viewers on `@decartai/sdk` older than v0.1.21 connect successfully but decode nothing — the video element stays black with no error raised. React Native viewers cannot strip the trailer and are rejected with `UNSUPPORTED_PLATFORM_FEATURE`.</Warning>

### Deep preflight

For a *measured* verdict before connecting, use the deep probe — it briefly opens a real session with a synthetic source, measures glass-to-glass, then tears it down. Requires a `model` and costs a short session:

```typescript theme={null}
const probe = await client.realtime.checkConnectivity({ deep: true, model });
console.log(probe.quality, probe.metrics.g2gMs, probe.metrics.ttffMs);
```

## Connection State

Monitor and react to connection state changes:

```typescript theme={null}
// Check state synchronously
const isConnected = realtimeClient.isConnected(); // boolean
const state = realtimeClient.getConnectionState(); // "connected" | "connecting" | "generating" | "reconnecting" | "disconnected"

// Listen to state changes
realtimeClient.on("connectionChange", (state) => {
  console.log(`Connection state: ${state}`);
  
  if (state === "disconnected") {
    // Handle disconnection
    showReconnectButton();
  } else if (state === "connected") {
    // Handle successful connection
    hideReconnectButton();
  }
});
```

**Connection States:**

* `"connecting"` — Initial connection in progress
* `"connected"` — Connected and ready to send prompts
* `"generating"` — Actively generating transformed video (sticky until disconnected)
* `"reconnecting"` — Connection was lost unexpectedly; the SDK is automatically retrying
* `"disconnected"` — Not connected (initial state, after `disconnect()`, or after reconnect failure)

<Info>
  The SDK automatically reconnects when an unexpected disconnection occurs (e.g., network interruption). During auto-reconnect, the state transitions to `"reconnecting"` while the SDK retries with exponential backoff (up to 5 attempts). If all retries fail, the state moves to `"disconnected"` and an `error` event is emitted.
</Info>

## Error Handling

Handle errors with the error event:

```typescript theme={null}
import type { DecartSDKError } from "@decartai/sdk";

realtimeClient.on("error", (error: DecartSDKError) => {
  console.error("SDK error:", error.code, error.message);

  switch (error.code) {
    case "INVALID_API_KEY":
      showError("Invalid API key. Please check your credentials.");
      break;
    case "TOKEN_EXPIRED":
      // The client token expired before a reconnect; the session is now disconnected.
      showError("Session token expired. Please start again.");
      break;
    case "WEB_RTC_ERROR":
      showError("Connection error. Please check your network.");
      break;
    case "MODEL_NOT_FOUND":
      showError("Model not found. Please check the model name.");
      break;
    default:
      showError(`Error: ${error.message}`);
  }
});
```

**Error Codes:**

* `INVALID_API_KEY` - API key is invalid or missing
* `TOKEN_EXPIRED` - The client token has already expired. Checked before every dial, so no socket is opened: `connect()` and `subscribe()` reject with it, and a reconnect emits `error` and moves to `disconnected`. Mint a fresh token right before connecting, or pass `apiKeyProvider`
* `WEB_RTC_ERROR` - WebRTC connection failed
* `MODEL_NOT_FOUND` - Specified model doesn't exist
* `INVALID_INPUT` - Invalid input parameters

## Telemetry and Observability

The JavaScript SDK provides realtime observability in two ways:

1. **SDK telemetry forwarding** (enabled by default) sends stats and diagnostics to Decart's telemetry ingestion pipeline.
2. **Local event stream** lets you consume observability events in your app via `on("stats")` and `on("diagnostic")`.

### Telemetry forwarding

Telemetry is enabled by default. You can disable it when creating the client:

```typescript theme={null}
const client = createDecartClient({
  apiKey: process.env.DECART_API_KEY,
  telemetry: false,
});
```

### Local observability events

```typescript theme={null}
realtimeClient.on("stats", (stats) => {
  // WebRTCStats snapshot (fps, bitrate, packet loss, RTT, etc.)
  console.log("stats", stats);
});

realtimeClient.on("diagnostic", (event) => {
  // Typed diagnostic events from the connection lifecycle
  console.log(event.name, event.data);
});
```

Available diagnostic event names:

* `phaseTiming`
* `iceCandidate`
* `iceStateChange`
* `peerConnectionStateChange`
* `signalingStateChange`
* `selectedCandidatePair`
* `reconnect`
* `videoStall`

<Note>
  `diagnostic` events are emitted by the connection lifecycle. `stats` events are collected automatically while telemetry is enabled.
</Note>

## Session Management

Access the current session ID:

```typescript theme={null}
const sessionId = realtimeClient.sessionId;
console.log(`Current session: ${sessionId}`);
```

This can be useful for logging, analytics, or debugging.

## Session Viewing (Subscribe)

You can let other clients watch an active realtime session as read-only viewers using the subscribe feature. The producer session exposes a `subscribeToken` that viewers use to connect.

### Getting a Subscribe Token

After connecting, the producer's `subscribeToken` is automatically populated:

```typescript theme={null}
const realtimeClient = await client.realtime.connect(stream, {
  model,
  onRemoteStream: (transformedStream) => {
    videoElement.srcObject = transformedStream;
  },
  initialState: {
    prompt: { text: "Anime style" },
  },
});

// Share this token with viewers (e.g., via your backend)
const token = realtimeClient.subscribeToken;
console.log(`Subscribe token: ${token}`);
```

### Subscribing to a Session

Viewers use the subscribe token to receive the transformed video stream in read-only mode:

```typescript theme={null}
import { createDecartClient } from "@decartai/sdk";

const client = createDecartClient({ apiKey: "viewer-api-key" });

const subscriber = await client.realtime.subscribe({
  token: subscribeToken, // Token from the producer
  onRemoteStream: (stream) => {
    viewerVideoElement.srcObject = stream;
  },
});

// Monitor connection state
subscriber.on("connectionChange", (state) => {
  console.log(`Viewer connection: ${state}`);
});

// Handle errors
subscriber.on("error", (error) => {
  console.error("Viewer error:", error.message);
});

// Disconnect when done
subscriber.disconnect();
```

<Note>Subscribe clients are receive-only — they cannot send prompts or modify the session. The subscriber sees exactly what the producer's `onRemoteStream` receives.</Note>

`subscribe()` follows the same credential rules as `connect()`: with `apiKeyProvider` set, the SDK fetches a fresh client token right before subscribing.

## Cleanup

Always disconnect when done to free up resources:

```typescript theme={null}
// Disconnect from the service
realtimeClient.disconnect();

// Remove event listeners
realtimeClient.off("connectionChange", onConnectionChange);
realtimeClient.off("error", onError);

// Stop the local media stream
stream.getTracks().forEach(track => track.stop());
```

<Warning>Failing to disconnect can leave WebRTC connections open and waste resources.</Warning>

## Complete Example

Here's a full application with all features:

```typescript theme={null}
import { createDecartClient, models, type DecartSDKError } from "@decartai/sdk";

async function setupRealtimeVideo() {
  try {
    // Get camera stream with optimal settings
    const model = models.realtime("lucy-restyle-2");
    const stream = await navigator.mediaDevices.getUserMedia({
      audio: true,
      video: {
        frameRate: model.fps,
        width: model.width,
        height: model.height,
      },
    });

    // Display input video
    const inputVideo = document.getElementById("input-video") as HTMLVideoElement;
    inputVideo.srcObject = stream;

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

    // Connect to Realtime API
    const realtimeClient = await client.realtime.connect(stream, {
      model,
      onRemoteStream: (transformedStream) => {
        const outputVideo = document.getElementById("output-video") as HTMLVideoElement;
        outputVideo.srcObject = transformedStream;
      },
      initialState: {
        prompt: {
          text: "Studio Ghibli animation style",
          enhance: true,
        },
      },
    });

    // Handle connection state changes
    realtimeClient.on("connectionChange", (state) => {
      const statusElement = document.getElementById("status");
      statusElement.textContent = `Status: ${state}`;
      statusElement.className = `status-${state}`;
    });

    // Handle errors
    realtimeClient.on("error", (error: DecartSDKError) => {
      console.error("Realtime error:", error);
      const errorElement = document.getElementById("error");
      errorElement.textContent = error.message;
      errorElement.style.display = "block";
    });

    // Allow user to change styles
    const styleInput = document.getElementById("style-input") as HTMLInputElement;
    styleInput.addEventListener("change", (e) => {
      const prompt = (e.target as HTMLInputElement).value;
      realtimeClient.setPrompt(prompt, { enhance: true });
    });

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

    return realtimeClient;
  } catch (error) {
    console.error("Failed to setup realtime video:", error);
    throw error;
  }
}

// Initialize
setupRealtimeVideo();
```

## React Native / Expo

Realtime works in React Native and Expo through [LiveKit's React Native packages](https://github.com/livekit/client-sdk-react-native). Plain `react-native-webrtc` is **not** supported. SDK imports and `createDecartClient(...)` usage are identical to the web.

Install the LiveKit stack alongside the SDK:

```bash theme={null}
npm install @decartai/sdk livekit-client@2.20.1 \
  @livekit/react-native@2.11.1 \
  @livekit/react-native-webrtc@144.1.1
```

Register LiveKit's native globals from a side-effect module that runs before your router or root component:

```typescript theme={null}
// livekit-bootstrap.ts
import { registerGlobals } from "@livekit/react-native";

registerGlobals();
```

```typescript theme={null}
// index.ts
import "./livekit-bootstrap";
import "expo-router/entry"; // or your root App component
```

Capture the camera with LiveKit's `mediaDevices`, size it from the model, and select VP8:

```typescript theme={null}
import { createDecartClient, models, resolveFpsNumber } from "@decartai/sdk";
import { mediaDevices } from "@livekit/react-native-webrtc";

const client = createDecartClient({ apiKey: "your-api-key-here" });
const model = models.realtime("lucy-2.5");

const stream = await mediaDevices.getUserMedia({
  audio: false,
  video: {
    facingMode: "user",
    frameRate: resolveFpsNumber(model.fps),
    width: model.width,
    height: model.height,
  },
});

const realtimeClient = await client.realtime.connect<MediaStream>(stream, {
  model,
  preferredVideoCodec: "vp8",
  onRemoteStream,
});
```

For Expo, add the config plugins to `app.json` and run `npx expo prebuild` (LiveKit does not run in Expo Go):

```json theme={null}
{
  "expo": {
    "plugins": [
      "@livekit/react-native-expo-plugin",
      "@config-plugins/react-native-webrtc"
    ]
  }
}
```

### React Native CLI (bare projects)

Expo's Metro config resolves the SDK's ESM dependencies for you. On a **bare React Native (CLI)** project you must add two small config changes, or the SDK won't bundle. Because LiveKit is imported lazily, the failure often surfaces at `client.realtime.connect(...)` as `realtime connect: exhausted all retries` / `signaling: websocket closed` — which looks like a network issue but is a **bundler** issue.

**1. Add a Babel plugin** so Metro can transform the `export * as ns from "..."` syntax used by some SDK dependencies (e.g. `zod`). Without it the bundle fails with `Export namespace should be first transformed by @babel/plugin-transform-export-namespace-from`:

```bash theme={null}
npm install --save-dev @babel/plugin-transform-export-namespace-from
```

```js theme={null}
// babel.config.js
module.exports = {
  presets: ["module:@react-native/babel-preset"],
  plugins: ["@babel/plugin-transform-export-namespace-from"],
};
```

**2. Do not hard-code the `livekit-client` path in `metro.config.js`.** `livekit-client@2.x` ships its ESM build as `dist/livekit-client.esm.mjs`. A stale alias to the old `dist/livekit-client.esm` (from a copy-pasted workaround) causes `Unable to resolve module .../livekit-client/dist/livekit-client.esm`. Remove any `resolver.extraNodeModules` / `resolver.resolveRequest` entry for `livekit-client`, let Metro resolve it via package `exports`, and add `mjs`/`cjs` to `sourceExts` defensively:

```js theme={null}
// metro.config.js
const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");

const defaultConfig = getDefaultConfig(__dirname);

module.exports = mergeConfig(defaultConfig, {
  resolver: {
    sourceExts: [...defaultConfig.resolver.sourceExts, "mjs", "cjs"],
  },
});
```

<Note>
  `mirror` and the deep connectivity preflight are browser-only and fail with `UNSUPPORTED_PLATFORM_FEATURE` on React Native. Mirror the local preview with LiveKit's `<RTCView mirror>` instead.
</Note>

<Tip>
  See the [Realtime Mobile App](/examples/real-time-mobile-app) walkthrough for a full Expo integration, and [Streaming best practices → React Native / Expo](/models/realtime/streaming-best-practices#react-native--expo) for mobile-specific tuning.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Use model properties for video constraints">
    Always use the model's `fps`, `width`, and `height` properties when calling getUserMedia to ensure optimal performance and compatibility.

    ```typescript theme={null}
    const model = models.realtime("lucy-restyle-2");
    const stream = await navigator.mediaDevices.getUserMedia({
      video: {
        frameRate: model.fps,
        width: model.width,
        height: model.height,
      },
    });
    ```
  </Accordion>

  <Accordion title="Enable prompt enhancement">
    For best results, keep `enhance: true` (default) to let Decart's AI enhance your prompts. Only disable it if you need exact prompt control.
  </Accordion>

  <Accordion title="Handle connection state changes">
    Always listen to `connectionChange` events to update your UI and handle reconnection logic gracefully.
  </Accordion>

  <Accordion title="Clean up properly">
    Always call `disconnect()` and stop media tracks when done to avoid memory leaks and unnecessary resource usage.
  </Accordion>
</AccordionGroup>

## API Reference

### `client.realtime.connect(stream, options)`

Connects to the realtime transformation service.

**Parameters:**

* `stream: MediaStream` - MediaStream from getUserMedia
* `options.model: ModelDefinition` - Realtime model from `models.realtime()`
* `options.onRemoteStream: (stream: MediaStream) => void` - Callback for transformed video stream
* `options.mirror?: "auto" | boolean` - Pre-flip the input video before sending. `false` (default), `"auto"` to mirror when the track reports `facingMode: "user"`, or `true` to always mirror.
* `options.resolution?: "720p" | "1080p"` - Output resolution. Defaults to `"720p"`.
* `options.speed?: "fast"` - [Fast mode](#fast-mode): lower latency and higher throughput on `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5`. Billed at 2x the standard realtime rate. Omit for standard mode. Requires v0.2.2+ (`queryParams: { speed: "fast" }` on earlier versions).
* `options.preferredVideoCodec?: "h264" | "vp8" | "vp9"` - Preferred local publish codec. Desktop Safari is always pinned to `vp8`. On React Native, use `"vp8"`.
* `options.initialState.prompt: { text: string; enhance?: boolean }` - Initial transformation prompt
* `options.initialState.image: Blob | File | string` - Reference image. A `Blob`/`File`, a `data:` / `http(s):` URL, or a base64 string sends the bytes inline; a `"file_…"` id from [`client.files.upload(...)`](#reference-image-uploads) sends a server-side reference instead.

**Returns:** `Promise<RealtimeClient>` - Connected realtime client instance

**Rejects with:** `TOKEN_EXPIRED` when the client token has already expired (checked before dialling; no socket is opened).

### `realtimeClient.setPrompt(prompt, options?)`

Changes the transformation style.

**Parameters:**

* `prompt: string` - Text description of desired style
* `options.enhance?: boolean` - Whether to enhance the prompt (default: true)

### `realtimeClient.set(input)`

Replaces the entire session state atomically. Fields not included in the input are cleared.

**Parameters:**

* `input: SetInput` - Object with at least one of:
  * `prompt?: string` - Text description of desired style
  * `enhance?: boolean` - Whether to enhance the prompt (default: true)
  * `image?: Blob | File | string | null` - Reference image, or `null` to clear. Pass a `"file_…"` id from [`client.files.upload(...)`](#reference-image-uploads) to reuse a previously uploaded asset.

**Returns:** `Promise<void>`

### `realtimeClient.setImage(image)`

Sets a reference image to guide the transformation. For Lucy Restyle Live, this guides style transformation. For Lucy, this sets a character reference for identity transformation, allowing you to transform yourself into a different character.

**Parameters:**

* `image: Blob | File | string` - Image as a Blob, File object, or URL string. Pass a `"file_…"` id from [`client.files.upload(...)`](#reference-image-uploads) to reuse a previously uploaded asset.

**Returns:** `Promise<void>`

### `realtimeClient.isConnected()`

Check if currently connected.

**Returns:** `boolean`

### `realtimeClient.getConnectionState()`

Get current connection state.

**Returns:** `"connected" | "connecting" | "generating" | "reconnecting" | "disconnected"`

### `realtimeClient.sessionId`

The ID of the current realtime inference session.

**Type:** `string | null`

### `realtimeClient.subscribeToken`

An opaque token that can be shared with other clients to let them watch this session in read-only mode via `client.realtime.subscribe()`.

**Type:** `string | null`

### `realtimeClient.disconnect()`

Closes the connection and cleans up resources.

### `client.realtime.subscribe(options)`

Connects to an existing realtime session as a read-only viewer.

**Parameters:**

* `options.token: string` - Subscribe token from the producer's `realtimeClient.subscribeToken`
* `options.onRemoteStream: (stream: MediaStream) => void` - Callback for the video stream

**Returns:** `Promise<RealTimeSubscribeClient>` - Connected subscribe client

The subscribe client exposes:

* `isConnected()` - Check connection status
* `getConnectionState()` - Get current state
* `disconnect()` - Close the connection
* `on(event, listener)` / `off(event, listener)` - Listen to `connectionChange` and `error` events

### Events

#### `connectionChange`

Fired when connection state changes.

**Callback:** `(state: "connected" | "connecting" | "generating" | "reconnecting" | "disconnected") => void`

#### `error`

Fired when an error occurs.

**Callback:** `(error: DecartSDKError) => void`

#### `generationTick`

Fired periodically during generation with billing information. Use this to track session duration and display usage to users.

**Callback:** `(data: { seconds: number }) => void`

```typescript theme={null}
realtimeClient.on("generationTick", ({ seconds }) => {
  console.log(`Generation running for ${seconds} seconds`);
  updateBillingUI(seconds);
});
```

#### `stats`

Fired continuously with parsed WebRTC transport/media metrics.

**Callback:** `(stats: WebRTCStats) => void`

#### `diagnostic`

Fired for typed connection lifecycle diagnostics.

**Callback:** `(event: DiagnosticEvent) => void`

## Next Steps

<CardGroup>
  <Card title="Process API" icon="wand-magic-sparkles" href="/sdks/javascript-process">
    Learn how to generate and transform media with the Process API
  </Card>

  <Card title="Examples" icon="code" href="/examples/real-time-mobile-app">
    See complete example applications
  </Card>
</CardGroup>


# Overview
Source: https://docs.platform.decart.ai/sdks/python

A Python SDK for Decart's models

<Card title="GitHub" icon="github" href="https://github.com/DecartAI/decart-python">
  View source code and contribute
</Card>

## Installation

```bash theme={null}
pip install decart
```

## Quick Start

The SDK is fully async and uses standard Python async/await patterns:

```python theme={null}
import asyncio
from decart import DecartClient, models
import os

async def main():
    # Using context manager (recommended for automatic cleanup)
    async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
        # Edit a video using the Queue API
        result = await client.queue.submit_and_poll({
            "model": models.video("lucy-2.1"),
            "data": video_file,
            "prompt": "Transform into anime style",
            "resolution": "720p",
            "on_status_change": lambda job: print(f"Status: {job.status}"),
        })

        if result.status == "completed":
            with open("output.mp4", "wb") as f:
                f.write(result.data)
            print("Video saved!")

asyncio.run(main())
```

## What can you build?

The SDK provides three main APIs for different use cases:

| If you need to... | Use | Main method |
| - | - | - |
| Transform live streams over WebRTC | Realtime API | `RealtimeClient.connect()` |
| Generate/edit videos asynchronously | Queue API | `client.queue.submit_and_poll()` |
| Generate/edit images synchronously | Process API | `client.process()` |

<CardGroup>
  <Card title="Realtime API" href="/sdks/python-realtime">
    Realtime video streams
  </Card>

  <Card title="Queue API" href="/sdks/python-queue">
    Video processing
  </Card>

  <Card title="Process API" href="/sdks/python-process">
    Image editing
  </Card>
</CardGroup>

<Tip>
  Use `async with DecartClient(...)` for automatic connection cleanup in production services.
</Tip>

## Client Setup

All APIs share the same client initialization:

```python theme={null}
import os
from decart import DecartClient

# Option 1: Context manager (recommended - automatic cleanup)
async with DecartClient(
    api_key=os.getenv("DECART_API_KEY"),
    base_url="https://custom-endpoint.com",  # optional
) as client:
    result = await client.process({...})
    # Session automatically closed when done

# Option 2: Manual initialization
client = DecartClient(
    api_key=os.getenv("DECART_API_KEY"),
    base_url="https://custom-endpoint.com",  # optional
)
# Remember to call await client.close() when done
```

**Parameters:**

* `api_key` (required) - Your Decart API key from the [platform](https://platform.decart.ai)
* `base_url` (optional) - Custom API endpoint (defaults to Decart's production API)

<Tip>Use the context manager (`async with`) for automatic cleanup of HTTP connections.</Tip>

## Client Tokens

For client-side applications (browsers, mobile apps) using the Realtime API, create short-lived client tokens instead of exposing your permanent API key:

```python theme={null}
# On your backend — basic (60s TTL, unrestricted)
async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
    token = await client.tokens.create()
    # token.api_key - the client token; send it to your frontend
    # token.expires_at - expiration timestamp

    # Or scoped to specific models and origins with a longer TTL
    token = await client.tokens.create(
        expires_in=300,
        allowed_models=["lucy-2.1"],
        allowed_origins=["https://app.example.com"],  # browser-enforced; canonical origin
    )
```

<Tip>
  See [Client Tokens](/getting-started/client-tokens) for details on secure realtime auth.
</Tip>

## Available Models

Import models from the SDK to use with either API:

```python theme={null}
from decart import models

# Realtime models
models.realtime("lucy-2.5")              # Realtime video editing (latest)
models.realtime("lucy-vton-3.5")         # Virtual try-on
models.realtime("lucy-vton-3.6")         # Virtual try-on (newest)
models.realtime("lucy-restyle-2")        # Realtime video restyling

# Video models
models.video("lucy-2.5")                # Video editing (latest)
models.video("lucy-vton-3.5")           # Virtual try-on
models.video("lucy-vton-3.6")           # Virtual try-on (newest)
models.video("lucy-restyle-2")          # Video restyling

# Image models
models.image("lucy-image-2")            # Image editing

# Latest aliases — always point to the newest version
models.realtime("lucy-latest")           # Latest realtime editing model
models.video("lucy-latest")              # Latest video editing model
models.video("lucy-vton-latest")         # Latest virtual try-on model
models.video("lucy-restyle-latest")      # Latest video restyling model
models.image("lucy-image-latest")        # Latest image editing model
```

<Accordion title="Previous generation models">
  ```python theme={null}
  # Realtime models
  models.realtime("lucy-2.1")              # Previous realtime video editing

  # Video models
  models.video("lucy-2.1")                # Previous video editing
  ```
</Accordion>

## Async/Await

All SDK methods are asynchronous and must be called with `await`. If you're new to async Python:

* Use `async def` for functions that call SDK methods
* Call async functions with `await`
* Run async code with `asyncio.run(main())`
* For scripts or notebooks, you can use the sync wrapper pattern shown above

## Type Hints Support

The SDK includes full type hints for better IDE support and type checking. Each model enforces its own required inputs, so you'll get autocomplete and helpful errors if something is missing.

```python theme={null}
# Video editing requires 'data' field
await client.queue.submit_and_poll({
    "model": models.video("lucy-2.1"),
    "prompt": "Transform into anime style",
    "data": video_file,  # ✅ Required
})

# Image editing requires 'data' field
await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "Change the background to a beach",
    "data": image_file,  # ✅ Required
})
```

## Ready to start building?

<CardGroup>
  <Card title="Realtime API Guide" href="/sdks/python-realtime">
    **Build realtime experiences**

    Learn WebRTC integration, camera handling, and how to create interactive video applications.
  </Card>

  <Card title="Queue API Guide" href="/sdks/python-queue">
    **Video processing**

    Edit videos, control motion, and transform videos with style transfer.
  </Card>

  <Card title="Process API Guide" href="/sdks/python-process">
    **Image editing**

    Edit and transform images on-demand with synchronous processing.
  </Card>
</CardGroup>


# Process API
Source: https://docs.platform.decart.ai/sdks/python-process

Transform images on-demand

The Process API enables you to transform existing images with style transfer and edits. Perfect for building content creation tools, media processing pipelines, batch transformations, and creative applications.

<Note>
  For video processing (video editing, motion control), use the [Queue API](/sdks/python-queue) which provides asynchronous job-based processing.
</Note>

## Image

### Image Editing

Transform and restyle existing images:

```python theme={null}
with open("image.jpg", "rb") as image_file:
    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": "Oil painting style with impressionist brushstrokes",
        "data": image_file,
        "enhance_prompt": True,
        "seed": 123,
    })
```

You can also provide a reference image to guide the edit — for example, to add a specific item:

```python theme={null}
with open("image.jpg", "rb") as image_file:
    with open("sunglasses.jpg", "rb") as reference_image:
        result = await client.process({
            "model": models.image("lucy-image-2"),
            "prompt": "Add these sunglasses to the person's face",
            "data": image_file,
            "reference_image": reference_image,
        })
```

**Parameters:**

* `prompt` (required) - Text description of the style transformation
* `data` (required) - Input image (file object, bytes, or URL)
* `reference_image` (optional) - Reference image to guide the edit (file object, bytes, or URL)
* `seed` (optional) - Random seed for reproducible results
* `resolution` (optional) - Output resolution
* `enhance_prompt` (optional) - Auto-enhance the prompt for better results

**Model:** `lucy-image-2`

***

## Input Types

The `data` and `reference_image` parameters accept flexible input types:

```python theme={null}
from typing import Union, Protocol, runtime_checkable
from pathlib import Path

@runtime_checkable
class HasRead(Protocol):
    def read(self) -> Union[bytes, str]: ...

FileInput = Union[HasRead, bytes, str, Path]
```

**Examples:**

```python theme={null}
# Path object (recommended for files)
from pathlib import Path

result = await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "Transform to watercolor style",
    "data": Path("./image.jpg"),
})

# File object from open()
with open("image.jpg", "rb") as file:
    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": "Transform to watercolor style",
        "data": file,
    })

# Bytes
with open("image.jpg", "rb") as f:
    image_bytes = f.read()

result = await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "Transform to watercolor style",
    "data": image_bytes,
})

# URL string
result = await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "Transform this image",
    "data": "https://example.com/image.jpg",
})
```

<Note>The SDK automatically detects whether a string is a file path or URL. Use `Path` objects for explicit file paths.</Note>

## Cancellation

Cancel long-running operations using asyncio.Event:

```python theme={null}
import asyncio

cancel_token = asyncio.Event()

try:
    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": "Epic fantasy landscape with dragons",
        "cancel_token": cancel_token,
    })
except asyncio.CancelledError:
    print("Generation cancelled")

# Cancel the request from another coroutine
cancel_token.set()
```

You can use this to implement cancel buttons in your UI:

```python theme={null}
import asyncio

current_cancel_token: asyncio.Event | None = None

async def edit_image(prompt: str):
    global current_cancel_token

    # Cancel previous request if any
    if current_cancel_token:
        current_cancel_token.set()

    current_cancel_token = asyncio.Event()

    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": prompt,
        "data": image_file,
        "cancel_token": current_cancel_token,
    })

    return result

def cancel_generation():
    if current_cancel_token:
        current_cancel_token.set()
```

## Error Handling

The SDK raises specific exception classes for different failure scenarios:

```python theme={null}
from decart import (
    DecartClient,
    InvalidInputError,
    InvalidAPIKeyError,
    ProcessingError,
    DecartSDKError,
)

try:
    with open("image.jpg", "rb") as image_file:
        result = await client.process({
            "model": models.image("lucy-image-2"),
            "prompt": "Transform this image",
            "data": image_file,
        })
except InvalidInputError as error:
    print(f"Invalid input: {error.message}")
except InvalidAPIKeyError as error:
    print("Invalid API key - check your credentials")
except ProcessingError as error:
    print(f"Processing failed: {error.message}")
except DecartSDKError as error:
    # Catch-all for any other SDK errors
    print(f"SDK error: {error.message}")
```

**Exception Types:**

* `InvalidAPIKeyError` - API key is invalid or missing
* `InvalidBaseURLError` - Base URL is malformed
* `InvalidInputError` - Invalid input parameters or validation failed
* `ProcessingError` - Server-side processing error
* `ModelNotFoundError` - Specified model doesn't exist
* `DecartSDKError` - Base class for all SDK errors

If you provide invalid inputs, you'll get clear error messages:

```python theme={null}
# Missing required field
await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "test",
    # Missing 'data' field
})
# Raises InvalidInputError: Invalid inputs for lucy-image-2: data is required
```

<Tip>Import specific exception types for better error handling and type safety.</Tip>

## API Reference

### `client.process(options)`

Generate or transform images.

**Parameters:**

* `options: dict` - Configuration dictionary with model and inputs:
  * `model` - Model from `models.image()`
  * `cancel_token: asyncio.Event` - Optional event for cancellation
  * Additional fields depend on the model (see below)

**Returns:** `bytes` - The generated/transformed image

**Inputs by Model:**

<Accordion title="Image Editing (lucy-image-2)">
  * `prompt: str` - Style description (required)
  * `data: FileInput` - Input image (required)
  * `reference_image: FileInput` - Reference image to guide the edit
  * `seed: int` - Random seed
  * `resolution: str` - Output resolution
  * `enhance_prompt: bool` - Auto-enhance prompt
</Accordion>

## Next Steps

<CardGroup>
  <Card title="Queue API" icon="video" href="/sdks/python-queue">
    Asynchronous video processing with job-based queue
  </Card>

  <Card title="Realtime API" icon="bolt" href="/sdks/python-realtime">
    Transform video streams in realtime with WebRTC
  </Card>
</CardGroup>


# Queue API
Source: https://docs.platform.decart.ai/sdks/python-queue

Asynchronous job-based video processing

The Queue API is the primary way to process videos with the Python SDK. Submit jobs that are processed asynchronously in the background, then poll for status and retrieve results when complete.

<Note>
  All video processing (video editing, restyling, motion control) uses the Queue API. For image editing, use the [Process API](/sdks/python-process).
</Note>

## Overview

The Queue API provides four main methods:

* `submit()` - Submit a job and get a job ID immediately
* `status()` - Check the status of a submitted job
* `result()` - Retrieve the completed video
* `submit_and_poll()` - Submit and automatically poll until completion

## Submit a Job

Submit a video editing job and receive a job ID immediately:

```python theme={null}
job = await client.queue.submit({
    "model": models.video("lucy-2.1"),
    "data": video_file,
    "prompt": "Transform into anime style",
})

print(f"Job ID: {job.job_id}")
print(f"Status: {job.status}")  # "pending"
```

**Returns:**

* `job_id` - Unique identifier for the job
* `status` - Initial status (`"pending"`)

***

## Check Job Status

Poll the status of a submitted job:

```python theme={null}
status = await client.queue.status(job.job_id)

print(f"Status: {status.status}")  # "pending", "processing", "completed", or "failed"
```

**Status Values:**

| Status | Description |
| - | - |
| `pending` | Job is queued, waiting to be processed |
| `processing` | Job is currently being processed |
| `completed` | Job finished successfully |
| `failed` | Job failed or timed out (timeout after 10 minutes) |

***

## Get Job Result

Retrieve the video once the job is completed:

```python theme={null}
# First check status
status = await client.queue.status(job.job_id)

if status.status == "completed":
    result = await client.queue.result(job.job_id)

    if result.status == "completed":
        with open("output.mp4", "wb") as f:
            f.write(result.data)
    else:
        print(f"Error: {result.error}")
```

**Returns:**

* `status` - Either `"completed"` or `"failed"`
* `data` - Video bytes (when completed)
* `error` - Error message (when failed)

***

## Submit and Poll

The easiest way to use the Queue API - submit a job and automatically poll until completion:

```python theme={null}
with open("input.mp4", "rb") as video_file:
    result = await client.queue.submit_and_poll({
        "model": models.video("lucy-2.1"),
        "data": video_file,
        "prompt": "Transform into anime style",
        "on_status_change": lambda job: print(f"Status: {job.status}"),
    })

if result.status == "completed":
    with open("output.mp4", "wb") as f:
        f.write(result.data)
else:
    print(f"Editing failed: {result.error}")
```

**Parameters:**

* All standard model parameters (prompt, resolution, etc.)
* `on_status_change` (optional) - Callback function called on each status change

***

## Complete Example

```python theme={null}
import asyncio
from decart import DecartClient, models

async def edit_video():
    async with DecartClient(api_key="your-api-key") as client:
        print("Submitting video editing job...")

        with open("input.mp4", "rb") as video_file:
            result = await client.queue.submit_and_poll({
                "model": models.video("lucy-2.1"),
                "data": video_file,
                "prompt": "Transform into anime style",
                "on_status_change": lambda job: print(f"  Status: {job.status}"),
            })

        if result.status == "completed":
            with open("output.mp4", "wb") as f:
                f.write(result.data)
            print("Video saved to output.mp4")
        else:
            print(f"Editing failed: {result.error}")

asyncio.run(edit_video())
```

**Output:**

```
Submitting video editing job...
  Status: pending
  Status: processing
  Status: completed
Video saved to output.mp4
```

***

## Video Editing with Queue

Transform videos with style transfer:

```python theme={null}
with open("input.mp4", "rb") as video_file:
    result = await client.queue.submit_and_poll({
        "model": models.video("lucy-2.1"),
        "prompt": "Convert to anime style with vibrant colors",
        "data": video_file,
        "on_status_change": lambda job: print(f"Status: {job.status}"),
    })
```

***

## Manual Polling

For custom polling logic, you can manually poll for status:

```python theme={null}
import asyncio

# Submit job
job = await client.queue.submit({
    "model": models.video("lucy-2.1"),
    "prompt": "A serene lake at sunset",
})

print(f"Job submitted: {job.job_id}")

# Manual polling loop
while True:
    status = await client.queue.status(job.job_id)
    print(f"Status: {status.status}")

    if status.status == "completed":
        result = await client.queue.result(job.job_id)
        with open("output.mp4", "wb") as f:
            f.write(result.data)
        print("Video saved!")
        break
    elif status.status == "failed":
        print("Generation failed")
        break

    # Wait before next poll
    await asyncio.sleep(2)
```

***

## Error Handling

```python theme={null}
from decart import (
    DecartClient,
    QueueSubmitError,
    QueueStatusError,
    QueueResultError,
    DecartSDKError,
)

try:
    result = await client.queue.submit_and_poll({
        "model": models.video("lucy-2.1"),
        "prompt": "A beautiful sunset",
    })
except QueueSubmitError as error:
    print(f"Failed to submit job: {error.message}")
except QueueStatusError as error:
    print(f"Failed to check status: {error.message}")
except QueueResultError as error:
    print(f"Failed to get result: {error.message}")
except DecartSDKError as error:
    print(f"SDK error: {error.message}")
```

***

## Supported Models

All non-realtime video models support queue processing:

| Model | Type | Description |
| - | - | - |
| `lucy-2.5` | Video-to-Video | Video editing (latest) |
| `lucy-vton-3.5` | Video-to-Video | Virtual try-on |
| `lucy-vton-3.6` | Video-to-Video | Virtual try-on (newest) |
| `lucy-restyle-2` | Video-to-Video | Video restyling |

<Accordion title="Latest aliases">
  | Alias | Description |
  | - | - |
  | `lucy-latest` | Always the latest editing model |
  | `lucy-vton-latest` | Always the latest virtual try-on model |
  | `lucy-restyle-latest` | Always the latest restyling model |
</Accordion>

<Accordion title="Previous generation models">
  | Model | Type | Description |
  | - | - | - |
  | `lucy-2.1` | Video-to-Video | Previous video editing |
</Accordion>

***

## API Reference

### `client.queue.submit(options)`

Submit a job for processing.

**Parameters:**

* `options: dict` - Model and input parameters

**Returns:** `JobSubmitResponse`

* `job_id: str` - Unique job identifier
* `status: str` - Initial status ("pending")

***

### `client.queue.status(job_id)`

Check the status of a job.

**Parameters:**

* `job_id: str` - The job identifier

**Returns:** `JobStatusResponse`

* `job_id: str` - Job identifier
* `status: str` - Current status

***

### `client.queue.result(job_id)`

Get the result of a completed job.

**Parameters:**

* `job_id: str` - The job identifier

**Returns:** `QueueJobResult`

* `status: str` - "completed" or "failed"
* `data: bytes` - Video data (when completed)
* `error: str` - Error message (when failed)

***

### `client.queue.submit_and_poll(options)`

Submit a job and poll until completion.

**Parameters:**

* `options: dict` - Model and input parameters
  * `on_status_change: Callable` (optional) - Status change callback

**Returns:** `QueueJobResult`

***

## Next Steps

<CardGroup>
  <Card title="Process API" icon="image" href="/sdks/python-process">
    Synchronous image editing
  </Card>

  <Card title="Realtime API" icon="bolt" href="/sdks/python-realtime">
    Transform video streams in realtime with WebRTC
  </Card>
</CardGroup>


# Realtime API
Source: https://docs.platform.decart.ai/sdks/python-realtime

Transform video streams in realtime from Python

The Realtime API transforms a live video track with minimal latency. Signaling is a Decart-owned WebSocket; media flows through a LiveKit room that the SDK joins for you. Pair it with any source that can produce LiveKit video frames — a camera, a file, or synthetic frames.

## Installation

The realtime client lives behind an optional extra:

```bash theme={null}
pip install decart[realtime]
```

This pulls in `livekit` (LiveKit's Python client) alongside the core SDK. The `decart.realtime` module won't import without it.

## Quick Start

```python theme={null}
import asyncio
import os
from decart import DecartClient, SetInput, models
from decart.realtime import RealtimeClient, RealtimeConnectOptions
from decart.types import ModelState, Prompt
from livekit import rtc

async def main():
    async with DecartClient(api_key=os.environ["DECART_API_KEY"]) as client:
        model = models.realtime("lucy-2.1")

        # Build a LiveKit local video track from your own source (camera, file,
        # synthetic frames, ...). See "Creating a video track" below.
        source = rtc.VideoSource(model.width, model.height)
        local_track = rtc.LocalVideoTrack.create_video_track("input", source)

        def on_remote_stream(track: rtc.RemoteVideoTrack):
            async def consume():
                async for event in rtc.VideoStream(track):
                    handle_frame(event.frame)
            asyncio.create_task(consume())

        realtime = await RealtimeClient.connect(
            base_url=client.realtime_base_url,
            api_key=client.api_key,
            local_track=local_track,
            options=RealtimeConnectOptions(
                model=model,
                on_remote_stream=on_remote_stream,
                initial_state=ModelState(
                    prompt=Prompt(text="A cyberpunk cityscape", enhance=True),
                ),
            ),
        )

        # Update the style mid-session — replaces the entire session state.
        await realtime.set(SetInput(prompt="A sunny beach", enhance=True))

        # ... feed frames into `source.capture_frame(...)` from your own loop ...

        await realtime.disconnect()

asyncio.run(main())
```

## Creating Client Tokens

When your Python backend serves browser or mobile clients, mint short-lived [client tokens](/getting-started/client-tokens) instead of shipping your permanent API key.

### Backend Examples

<CodeGroup>
  ```python FastAPI theme={null}
  from fastapi import FastAPI, HTTPException
  from decart import DecartClient
  import os

  app = FastAPI()
  decart_client = DecartClient(api_key=os.environ["DECART_API_KEY"])

  @app.post("/api/realtime-token")
  async def create_realtime_token():
      try:
          token = await decart_client.tokens.create(
              expires_in=300,                # 5 minutes
              allowed_models=["lucy-2.1"],   # restrict to this model
          )
          return {"apiKey": token.api_key, "expiresAt": token.expires_at}
      except Exception:
          raise HTTPException(status_code=500, detail="Failed to create client token")

  @app.on_event("shutdown")
  async def shutdown():
      await decart_client.close()
  ```

  ```python Flask theme={null}
  from flask import Flask, jsonify
  from decart import DecartClient
  import asyncio
  import os

  app = Flask(__name__)
  decart_client = DecartClient(api_key=os.environ["DECART_API_KEY"])

  @app.route("/api/realtime-token", methods=["POST"])
  def create_realtime_token():
      try:
          token = asyncio.run(decart_client.tokens.create(
              expires_in=300,
              allowed_models=["lucy-2.1"],
          ))
          return jsonify({"apiKey": token.api_key, "expiresAt": token.expires_at})
      except Exception:
          return jsonify({"error": "Failed to create client token"}), 500
  ```
</CodeGroup>

<Tip>Authenticate the token endpoint before issuing — anyone who can call it can spend credits against your account.</Tip>

## Connecting

### Creating a video track

The SDK consumes a LiveKit `LocalVideoTrack`. Build one from any source that can produce RGB frames at the model's `width` × `height` × `fps`:

```python theme={null}
from livekit import rtc

source = rtc.VideoSource(model.width, model.height)
local_track = rtc.LocalVideoTrack.create_video_track("input", source)

# Push frames at the model's fps from your own loop. RGB24 example:
source.capture_frame(rtc.VideoFrame(
    width=model.width,
    height=model.height,
    type=rtc.VideoBufferType.RGB24,
    data=rgb_bytes,
))
```

The `examples/` folder in the SDK shows two common shapes:

* [`realtime_synthetic.py`](https://github.com/DecartAI/decart-python/blob/main/examples/realtime_synthetic.py) — push generated frames at the model's `fps`.
* [`realtime_file.py`](https://github.com/DecartAI/decart-python/blob/main/examples/realtime_file.py) — read frames from a video file via OpenCV.

For a real camera, use any LiveKit-compatible capturer or feed frames yourself.

<Tip>Use the model's `fps`, `width`, and `height` for the source so capture matches what the server expects.</Tip>

### Establishing the connection

```python theme={null}
realtime = await RealtimeClient.connect(
    base_url=client.realtime_base_url,
    api_key=client.api_key,
    local_track=local_track,
    options=RealtimeConnectOptions(
        model=models.realtime("lucy-2.1"),
        on_remote_stream=on_remote_stream,
        initial_state=ModelState(
            prompt=Prompt(text="Studio Ghibli style", enhance=True),
            image=character_image_bytes,  # optional reference image
        ),
    ),
)
```

**Parameters:**

* `base_url` (required) — `client.realtime_base_url` (`wss://api.decart.ai` by default)
* `api_key` (required) — your Decart API key or a client token
* `local_track` (required) — a LiveKit `LocalVideoTrack`. Pass `None` only when subscribing to an existing session.
* `options: RealtimeConnectOptions`:
  * `model` (required) — from `models.realtime(...)`
  * `on_remote_stream` (required) — callback receiving the LiveKit `RemoteVideoTrack` for the transformed output
  * `initial_state` (optional) — `ModelState` with `prompt` and/or `image`
  * `resolution` (optional) — `"720p"` (default) or `"1080p"` on supported models
  * `speed` (optional) — `"fast"` opts into [fast mode](#fast-mode) on supported models. Omit for standard mode. Requires v0.2.1+.
  * `preferred_video_codec` (optional) — `"h264"` (default) or `"vp9"`. Picks the codec offered to the LiveKit publisher.

<Tip>Set `initial_state.prompt` and/or `image` so the very first frame is already transformed — otherwise viewers briefly see the raw camera feed.</Tip>

### Consuming the remote track

`on_remote_stream` hands you a LiveKit `RemoteVideoTrack`. Wrap it with `rtc.VideoStream` to receive decoded frames:

```python theme={null}
def on_remote_stream(track: rtc.RemoteVideoTrack):
    async def consume():
        async for event in rtc.VideoStream(track):
            frame = event.frame  # rtc.VideoFrame
            # ... render, encode, or relay frame.data ...
    asyncio.create_task(consume())
```

### Output resolution

Opt into 1080p output from supported models; otherwise the server returns 720p:

```python theme={null}
options = RealtimeConnectOptions(
    model=models.realtime("lucy-2.1"),
    on_remote_stream=on_remote_stream,
    resolution="1080p",
)
```

### Fast mode

Fast mode (`speed: "fast"`) gives the session lower latency and higher throughput; output quality is unchanged. It is available for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5`, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode. See [Pricing](/getting-started/pricing#realtime-models).

```python theme={null}
options = RealtimeConnectOptions(
    model=models.realtime("lucy-2.5"),
    on_remote_stream=on_remote_stream,
    speed="fast",
)
```

Requires `decart` v0.2.1+.

`ModelDefinition.supported_speeds` lists `("fast",)` for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5` only. Passing `speed` for another model logs a warning and connects on the standard tier.

### Codec preference

`preferred_video_codec` controls the codec the SDK offers to the LiveKit publisher:

```python theme={null}
options = RealtimeConnectOptions(
    model=models.realtime("lucy-2.1"),
    on_remote_stream=on_remote_stream,
    preferred_video_codec="vp9",  # default: "h264"
)
```

## Managing Prompts

Change the transformation style mid-session. `set_prompt` is async and waits for the server ack — it raises on ack failure or timeout.

```python theme={null}
await realtime.set_prompt("Anime style")

# Skip prompt enhancement for full control over the exact wording.
await realtime.set_prompt(
    "A detailed artistic style with vibrant colors and dramatic lighting",
    enhance=False,
)
```

**Parameters:**

* `prompt: str` — style description
* `enhance: bool` — auto-enhance the prompt (default: `True`)

<Note>Prompt enhancement uses Decart's AI to expand simple prompts for better results. Disable it when you need exact prompt control.</Note>

## Unified State Update

`set()` replaces the entire session state in a single atomic call. Fields you omit are cleared.

```python theme={null}
from decart import SetInput

# Prompt only (clears any previously set image)
await realtime.set(SetInput(prompt="Anime style", enhance=True))

# Image only (clears any previously set prompt)
await realtime.set(SetInput(image=image_bytes))

# Both together
await realtime.set(SetInput(
    prompt="Transform into this character",
    image="https://example.com/character.jpg",
    enhance=True,
))
```

**`SetInput` fields:**

* `prompt: Optional[str]` — at least one of `prompt` or `image` is required
* `enhance: bool` — auto-enhance the prompt (default: `True`)
* `image: Optional[Union[bytes, str]]` — reference image as raw bytes, a URL, a data URL, a file path, or raw base64. `None` clears it.

<Tip>Prefer `set()` over separate `set_prompt()` and `set_image()` calls when you're changing both — it avoids intermediate states the model briefly renders.</Tip>

## Connection State

```python theme={null}
state = realtime.get_connection_state()
is_connected = realtime.is_connected()

def on_connection_change(state):
    if state == "disconnected":
        show_reconnect_button()
    elif state == "connected":
        hide_reconnect_button()

realtime.on("connection_change", on_connection_change)
```

**Connection States:**

* `"connecting"` — initial connection in progress
* `"connected"` — connected and ready to send prompts
* `"generating"` — actively generating transformed video (sticky until disconnected)
* `"reconnecting"` — connection lost; the SDK is automatically retrying
* `"disconnected"` — initial state, after `disconnect()`, or after reconnect failure

<Info>The SDK retries with exponential backoff on unexpected disconnects (up to 5 attempts). If every retry fails, the state transitions to `"disconnected"` and an `error` event fires.</Info>

## Error Handling

```python theme={null}
from decart import (
    DecartSDKError,
    InvalidAPIKeyError,
    InvalidInputError,
    ModelNotFoundError,
    WebRTCError,
)

def on_error(error: DecartSDKError):
    if isinstance(error, InvalidAPIKeyError):
        show_error("Invalid API key.")
    elif isinstance(error, WebRTCError):
        show_error("Connection error. Check your network.")
    elif isinstance(error, ModelNotFoundError):
        show_error("Model not found.")
    elif isinstance(error, InvalidInputError):
        show_error(f"Invalid input: {error.message}")
    else:
        show_error(f"Error: {error.message}")

realtime.on("error", on_error)
```

**Exception Types:**

* `InvalidAPIKeyError` — API key invalid or missing
* `WebRTCError` — LiveKit / signaling / ICE failure
* `ModelNotFoundError` — model not found
* `InvalidInputError` — invalid input parameter
* `DecartSDKError` — base class for all SDK errors

## Generation Ticks

Track session duration for billing or usage display:

```python theme={null}
from decart.realtime import GenerationTickMessage

def on_generation_tick(message: GenerationTickMessage):
    update_billing_ui(message.seconds)

realtime.on("generation_tick", on_generation_tick)
```

## Session Identifiers

Once the LiveKit room info arrives, the SDK populates a session id and a subscribe token:

```python theme={null}
session_id = realtime.session_id          # for logging / analytics
subscribe_token = realtime.subscribe_token # share with viewers for read-only watching
```

## Session Viewing (Subscribe)

Other clients can watch an active session as read-only viewers. The producer's `subscribe_token` is the handle viewers connect with.

```python theme={null}
from decart import DecartClient
from decart.realtime import RealtimeClient, SubscribeOptions

async with DecartClient(api_key=viewer_api_key) as client:
    subscriber = await RealtimeClient.subscribe(
        base_url=client.realtime_base_url,
        api_key=client.api_key,
        options=SubscribeOptions(
            token=subscribe_token,           # from the producer
            on_remote_stream=on_remote_stream,
        ),
    )

    subscriber.on("connection_change", lambda s: print(f"Viewer: {s}"))
    subscriber.on("error", lambda e: print(f"Viewer error: {e}"))

    # ... later
    await subscriber.disconnect()
```

<Note>Subscribers are receive-only — they cannot send prompts or images. They see exactly what the producer's `on_remote_stream` receives.</Note>

## Cleanup

```python theme={null}
await realtime.disconnect()

realtime.off("connection_change", on_connection_change)
realtime.off("error", on_error)
```

<Warning>Forgetting to `disconnect()` leaves the LiveKit room open and continues to consume credits.</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Match the source to the model">
    Build `rtc.VideoSource(model.width, model.height)` and push frames at `model.fps`. Mismatched dimensions get rescaled server-side and waste bandwidth.
  </Accordion>

  <Accordion title="Seed the first frame">
    Pass `initial_state.prompt` and/or `initial_state.image` to `connect()` so the very first generated frame is already transformed. Without it, viewers briefly see the raw input.
  </Accordion>

  <Accordion title="Use `set()` for combined changes">
    When changing prompt and image together, prefer `set(SetInput(prompt=..., image=...))` over separate `set_prompt` / `set_image` calls — it avoids the intermediate state the model would otherwise render.
  </Accordion>

  <Accordion title="Always disconnect">
    `await realtime.disconnect()` from a `finally` block or async-context exit. The LiveKit room and HTTP session aren't reclaimed until you do.
  </Accordion>

  <Accordion title="Run on Python 3.10+">
    The SDK targets Python ≥ 3.10. The `decart[realtime]` extra adds `livekit` and `tenacity` on top of the core dependencies.
  </Accordion>
</AccordionGroup>

## API Reference

### `await RealtimeClient.connect(base_url, api_key, local_track, options)`

Connects to the realtime transformation service. Returns a connected `RealtimeClient`.

**Parameters:**

* `base_url: str` — `client.realtime_base_url`
* `api_key: str` — your Decart API key or a client token
* `local_track: Optional[rtc.LocalVideoTrack]` — input video track
* `options: RealtimeConnectOptions`:
  * `model: ModelDefinition` — from `models.realtime(...)`
  * `on_remote_stream: Callable[[rtc.RemoteVideoTrack], None]` — callback for the transformed track
  * `initial_state: Optional[ModelState]` — initial prompt / image
  * `resolution: Optional[Literal["720p", "1080p"]]` — output resolution
  * `speed: Optional[RealtimeSpeed]` — `"fast"` for [fast mode](#fast-mode) (2x rate) on supported models; `None` (default) for standard. Requires v0.2.1+.
  * `preferred_video_codec: Literal["h264", "vp9"]` — codec preference (default `"h264"`)

**Raises** `WebRTCError` on signaling, ICE, or LiveKit room failures.

### `await realtime.set(input)`

Replaces the entire session state atomically. Fields not included are cleared.

**Parameters:**

* `input: SetInput` — at least one of:
  * `prompt: Optional[str]`
  * `enhance: bool` (default `True`)
  * `image: Optional[Union[bytes, str]]` — bytes, URL, data URL, file path, or raw base64

### `await realtime.set_prompt(prompt, enhance=True)`

Changes the prompt and waits for the server ack.

**Raises** `DecartSDKError` on ack failure or timeout, `InvalidInputError` on empty prompt.

### `await realtime.set_image(image, prompt=None, enhance=True, timeout=30.0)`

Sends (or clears, with `image=None`) a reference image. Optionally bundles a prompt.

### `realtime.is_connected()` / `realtime.get_connection_state()`

Synchronous accessors for the current state (`"connected" | "connecting" | "generating" | "reconnecting" | "disconnected"`).

### `realtime.session_id` / `realtime.subscribe_token`

`Optional[str]` properties populated once the LiveKit room info arrives.

### `await realtime.disconnect()`

Closes the LiveKit room and the internal HTTP session.

### `await RealtimeClient.subscribe(base_url, api_key, options)`

Classmethod that connects to an existing session as a read-only viewer. Returns a `SubscribeClient` exposing `is_connected()`, `get_connection_state()`, `disconnect()`, and the same `on(...)` / `off(...)` event API.

**`SubscribeOptions`:**

* `token: str` — subscribe token from the producer
* `on_remote_stream: Callable[[rtc.RemoteVideoTrack], None]`

### Events

#### `connection_change`

Fires when the connection state changes. Callback signature: `(state: ConnectionState) -> None`.

#### `error`

Fires when an error occurs. Callback signature: `(error: DecartSDKError) -> None`.

#### `generation_tick`

Fires periodically during generation with billing info. Callback signature: `(message: GenerationTickMessage) -> None`. `message.seconds` is the running session duration.

## Next Steps

<CardGroup>
  <Card title="Process API" icon="wand-magic-sparkles" href="/sdks/python-process">
    Generate and transform media synchronously with the Process API
  </Card>

  <Card title="Examples" icon="code" href="/examples/real-time-mobile-app">
    See complete example applications
  </Card>
</CardGroup>


# Overview
Source: https://docs.platform.decart.ai/sdks/swift

A Swift SDK for Decart's models on iOS and macOS

<Card title="GitHub" icon="github" href="https://github.com/DecartAI/decart-ios">
  View source code and contribute
</Card>

## Installation

### Swift Package Manager

Add the package dependency in Xcode:

1. File → Add Package Dependencies
2. Enter: `https://github.com/decartai/decart-ios`
3. Select version and add to your target

Or add to your `Package.swift`:

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/decartai/decart-ios.git", from: "0.6.10")
]
```

## Quick Start

```swift theme={null}
import Foundation
import DecartSDK

let config = DecartConfiguration(apiKey: "your-api-key-here")
let client = DecartClient(decartConfiguration: config)

// Edit a video using the Queue API
let videoData = try Data(contentsOf: videoURL)
let input = try VideoEditInput(
    prompt: "Transform into anime style",
    data: .video(data: videoData)
)

let result = try await client.queue.submitAndPoll(
    model: .lucy2_5,
    input: input
) { status in
    print("Status: \(status.status)")
}

switch result {
case .completed(_, let data):
    try data.write(to: outputURL)
    print("Video saved!")
case .failed(_, let error):
    print("Failed: \(error)")
}
```

## What can you build?

The SDK provides three main APIs for different use cases:

| If you need to... | Use | Main class |
| - | - | - |
| Transform live camera streams over WebRTC | Realtime API | `DecartRealtimeManager` |
| Generate/edit videos asynchronously | Queue API | `QueueClient` |
| Edit images synchronously | Process API | `ProcessClient` |

<CardGroup>
  <Card title="Realtime API" href="/sdks/swift-realtime">
    Realtime video streams
  </Card>

  <Card title="Queue API" href="/sdks/swift-queue">
    Video processing
  </Card>

  <Card title="Process API" href="/sdks/swift-process">
    Image editing
  </Card>
</CardGroup>

## Client Setup

Initialize the Decart client with your API key:

```swift theme={null}
import DecartSDK

let config = DecartConfiguration(
    baseURL: "https://api.decart.ai",  // optional, this is the default
    apiKey: "your-api-key-here"
)

let client = DecartClient(decartConfiguration: config)
```

**Parameters:**

* `baseURL` (optional) - Custom API endpoint (defaults to `https://api.decart.ai`)
* `apiKey` (required) - Your Decart API key from the [platform](https://platform.decart.ai)

<Warning>
  Store your API key securely. Never commit API keys to version control. Use environment variables or secure storage like Keychain.
</Warning>

## Client Tokens

For production iOS and macOS apps using the Realtime API, fetch short-lived client tokens from your backend instead of embedding your permanent API key in the app bundle:

```swift theme={null}
// Fetch ephemeral key from your backend
let ephemeralKey = try await fetchTokenFromBackend()

// Use it to create the client
let config = DecartConfiguration(apiKey: ephemeralKey)
let client = DecartClient(decartConfiguration: config)
```

<Tip>
  See [Client Tokens](/getting-started/client-tokens) for details on secure client-side authentication.
</Tip>

## Available Models

Import models from the SDK to use with any API:

```swift theme={null}
import DecartSDK

// Realtime models
Models.realtime(.lucy2_5)                 // Realtime video editing (latest)
Models.realtime(.lucyVton3_5)             // Virtual try-on
Models.realtime(.lucyVton3_6)             // Virtual try-on (newest)
Models.realtime(.lucyRestyle2)            // Realtime video restyling

// Video models (Queue API)
Models.video(.lucy2_5)                    // Video editing (latest)
Models.video(.lucyVton3_5)                // Virtual try-on
Models.video(.lucyVton3_6)                // Virtual try-on (newest)
Models.video(.lucyRestyle2)               // Video restyling

// Image models (Process API)
Models.image(.lucyImage2)                 // Image editing

// Latest aliases — always point to the newest version
Models.realtime(.lucyLatest)              // Latest realtime editing model (currently Lucy 2.5)
Models.video(.lucyLatest)                 // Latest video editing model (currently Lucy 2.5)
Models.video(.lucyVtonLatest)             // Latest virtual try-on (currently Lucy VTON 3.6)
Models.image(.lucyImageLatest)            // Latest image editing model
```

<Accordion title="Previous generation models">
  ```swift theme={null}
  // Realtime models
  Models.realtime(.lucy2_1)                 // Previous realtime video editing

  // Video models
  Models.video(.lucy2_1)                    // Previous video editing
  ```
</Accordion>

Each model exposes properties for optimal configuration:

```swift theme={null}
let model = Models.realtime(.lucy2_5)
print(model.fps)     // 30
print(model.width)   // 1280
print(model.height)  // 720
```

## Platform Requirements

<Note>
  The Swift SDK requires:

  * **iOS 17.0+** or **macOS 12.0+**
  * **Swift 6.2+**
  * **Xcode 16.0+**
  * A **real device** for camera access (simulator not supported for WebRTC camera features)
</Note>

## Swift Concurrency

The SDK uses modern Swift concurrency with async/await and `AsyncStream` for reactive state:

```swift theme={null}
// All connection methods are async
let remoteStream = try await manager.connect(localStream: localStream)

// Monitor state changes with AsyncStream
for await state in manager.events {
    print("Connection: \(state.connectionState)")
    print("Service: \(state.serviceStatus)")
}
```

## Type Safety

The SDK uses typed input classes for each model, providing compile-time guarantees:

```swift theme={null}
// Video editing — requires prompt + video data
let videoEditInput = try VideoEditInput(
    prompt: "Transform into anime style",
    data: .video(data: videoData)
)

// Image editing — requires prompt + image data
let imageInput = try ImageToImageInput(
    prompt: "Change the background to a beach",
    data: .image(data: imageData)
)

// Video restyling — requires prompt OR reference image (not both)
let restyleInput = try VideoRestyleInput(
    prompt: "Studio Ghibli style",
    data: .video(data: videoData)
)
```

## Ready to start building?

<CardGroup>
  <Card title="Realtime API Guide" href="/sdks/swift-realtime">
    **Build realtime iOS experiences**

    Camera handling, video transformation, and interactive applications with WebRTC.
  </Card>

  <Card title="Queue API Guide" href="/sdks/swift-queue">
    **Video processing**

    Edit videos, control motion, and transform videos with style transfer.
  </Card>

  <Card title="Process API Guide" href="/sdks/swift-process">
    **Image editing**

    Edit and transform images on-demand with synchronous processing.
  </Card>
</CardGroup>


# Process API
Source: https://docs.platform.decart.ai/sdks/swift-process

Transform images on-demand

The Process API enables you to transform existing images with style transfer and edits. Perfect for building content creation tools, media processing pipelines, batch transformations, and creative applications.

<Note>
  For video processing (video editing, motion control), use the [Queue API](/sdks/swift-queue) which provides asynchronous job-based processing.
</Note>

## Image Editing

Transform and restyle existing images:

```swift theme={null}
import Foundation
import DecartSDK

let imageData = try Data(contentsOf: imageURL)
let input = try ImageToImageInput(
    prompt: "Oil painting style with impressionist brushstrokes",
    data: .image(data: imageData),
    enhancePrompt: true,
    seed: 123
)

let processClient = try client.createProcessClient(
    model: .lucy_image_2,
    input: input
)

let result = try await processClient.process()
// result is Data containing the transformed image
```

**`ImageToImageInput` parameters:**

* `prompt` (required) - Text description of the style transformation
* `data` (required) - Input image as `FileInput`
* `seed` (optional) - Random seed for reproducible results
* `resolution` (optional) - Output resolution (`.res720p` or `.res480p`)
* `enhancePrompt` (optional) - Auto-enhance the prompt for better results

**Model:** `lucy_image_2`

***

## Input Types

The `FileInput` type provides static factory methods for creating inputs:

```swift theme={null}
// From image data
let imageInput = try FileInput.image(data: imageData, filename: "image.jpg")

// From video data
let videoInput = try FileInput.video(data: videoData, filename: "video.mp4")

// Auto-detect from UTType
let input = try FileInput.from(data: fileData, uniformType: .jpeg)
```

***

## Error Handling

```swift theme={null}
do {
    let processClient = try client.createProcessClient(
        model: .lucy_image_2,
        input: input
    )
    let result = try await processClient.process()
} catch let error as DecartError {
    switch error {
    case .invalidAPIKey:
        print("Invalid API key - check your credentials")
    case .invalidInput(let message):
        print("Invalid input: \(message)")
    case .processingError(let message):
        print("Processing failed: \(message)")
    case .networkError(let underlying):
        print("Network error: \(underlying)")
    default:
        print("Error: \(error.localizedDescription)")
    }
}
```

**Error Cases:**

* `.invalidAPIKey` - API key is invalid or missing
* `.invalidInput(String)` - Invalid input parameters or validation failed
* `.processingError(String)` - Server-side processing error
* `.modelNotFound(String)` - Specified model doesn't exist
* `.networkError(Error)` - Network request failed

***

## Complete Example

```swift theme={null}
import DecartSDK
import UIKit

func editImage() async throws {
    let config = DecartConfiguration(apiKey: "your-api-key-here")
    let client = DecartClient(decartConfiguration: config)

    // Load image
    guard let image = UIImage(named: "input"),
          let imageData = image.jpegData(compressionQuality: 0.9) else {
        return
    }

    // Create input
    let input = try ImageToImageInput(
        prompt: "Transform to watercolor style",
        data: .image(data: imageData),
        resolution: .res720p,
        enhancePrompt: true
    )

    // Process
    let processClient = try client.createProcessClient(
        model: .lucy_image_2,
        input: input
    )
    let resultData = try await processClient.process()

    // Use the result
    if let resultImage = UIImage(data: resultData) {
        // Display or save the transformed image
        print("Image transformed successfully")
    }
}
```

***

## API Reference

### `client.createProcessClient(model:input:)`

Creates a process client for image editing.

**Parameters:**

* `model: ImageModel` - Image model (`.lucy_image_2`)
* `input: ImageToImageInput` - Image editing input

**Returns:** `ProcessClient`

**Throws:** `DecartError` if the model URL cannot be constructed

***

### `processClient.process()`

Sends the image for processing and returns the result.

**Returns:** `Data` - The transformed image bytes

**Throws:** `DecartError` on network or processing failure

***

## Next Steps

<CardGroup>
  <Card title="Queue API" icon="video" href="/sdks/swift-queue">
    Asynchronous video processing with job-based queue
  </Card>

  <Card title="Realtime API" icon="bolt" href="/sdks/swift-realtime">
    Transform video streams in realtime with WebRTC
  </Card>
</CardGroup>


# Queue API
Source: https://docs.platform.decart.ai/sdks/swift-queue

Asynchronous job-based video processing

The Queue API is the primary way to process videos with the Swift SDK. Submit jobs that are processed asynchronously in the background, then poll for status and retrieve results when complete.

<Note>
  All video processing (video editing, restyling, motion control) uses the Queue API. For image editing, use the [Process API](/sdks/swift-process).
</Note>

## Overview

The Queue API is accessed via `client.queue` and provides four main methods:

* `submit()` - Submit a job and get a job ID immediately
* `status()` - Check the status of a submitted job
* `result()` - Retrieve the completed video
* `submitAndPoll()` - Submit and automatically poll until completion

## Submit a Job

Submit a video editing job and receive a job ID immediately:

```swift theme={null}
import Foundation
import DecartSDK

let videoData = try Data(contentsOf: videoURL)
let input = try VideoEditInput(
    prompt: "Transform into anime style",
    data: .video(data: videoData)
)

let job = try await client.queue.submit(model: .lucy2_5, input: input)

print("Job ID: \(job.jobId)")
print("Status: \(job.status)")  // .pending
```

**Returns:**

* `jobId` - Unique identifier for the job
* `status` - Initial status (`.pending`)

***

## Check Job Status

Poll the status of a submitted job:

```swift theme={null}
let status = try await client.queue.status(jobId: job.jobId)

print("Status: \(status.status)")  // .pending, .processing, .completed, or .failed
```

**Status Values:**

| Status | Description |
| - | - |
| `.pending` | Job is queued, waiting to be processed |
| `.processing` | Job is currently being processed |
| `.completed` | Job finished successfully |
| `.failed` | Job failed or timed out |

***

## Get Job Result

Retrieve the video data once the job is completed:

```swift theme={null}
let status = try await client.queue.status(jobId: job.jobId)

if status.status == .completed {
    let videoData = try await client.queue.result(jobId: job.jobId)
    try videoData.write(to: outputURL)
}
```

**Returns:** `Data` — the raw video bytes

***

## Submit and Poll

The easiest way to use the Queue API — submit a job and automatically poll until completion:

```swift theme={null}
let videoData = try Data(contentsOf: videoURL)
let input = try VideoEditInput(
    prompt: "Transform into anime style",
    data: .video(data: videoData)
)

let result = try await client.queue.submitAndPoll(
    model: .lucy2_5,
    input: input
) { status in
    print("Status: \(status.status)")
}

switch result {
case .completed(let jobId, let data):
    try data.write(to: outputURL)
    print("Video saved!")
case .failed(let jobId, let error):
    print("Failed: \(error)")
}
```

**Parameters:**

* `model` (required) - Video model from `Models.video()`
* `input` (required) - Typed input for the model
* `onStatusChange` (optional) - Closure called on each status change

**Returns:** `QueueJobResult`

* `.completed(jobId: String, data: Data)` - Video data on success
* `.failed(jobId: String, error: String)` - Error message on failure

***

## Video Editing

Transform videos with prompt and optional reference image using `lucy2_5`:

```swift theme={null}
let input = try VideoEditInput(
    prompt: "Convert to anime style with vibrant colors",
    data: .video(data: videoData),
    referenceImage: .image(data: refImageData),  // optional
    resolution: .res720p
)

let result = try await client.queue.submitAndPoll(
    model: .lucy2_5,
    input: input
)
```

**`VideoEditInput` parameters:**

* `prompt` (required) - Text description of the transformation
* `data` (required) - Input video as `FileInput`
* `referenceImage` (optional) - Reference image as `FileInput`
* `seed` (optional) - Random seed for reproducible results
* `resolution` (optional) - Output resolution (`.res720p` or `.res480p`)
* `enhancePrompt` (optional) - Auto-enhance the prompt

***

## Video Restyling

Restyle videos using either a text prompt or a reference image (but not both) with `lucyRestyle2`:

```swift theme={null}
// Option A: With text prompt
let promptInput = try VideoRestyleInput(
    prompt: "Studio Ghibli style",
    data: .video(data: videoData)
)

// Option B: With reference image
let imageInput = try VideoRestyleInput(
    data: .video(data: videoData),
    referenceImage: .image(data: refImageData)
)

let result = try await client.queue.submitAndPoll(
    model: .lucyRestyle2,
    input: promptInput  // or imageInput
)
```

**`VideoRestyleInput` parameters:**

* `prompt` (optional) - Text description of style (required if no `referenceImage`)
* `data` (required) - Input video as `FileInput`
* `referenceImage` (optional) - Reference image (required if no `prompt`)
* `seed` (optional) - Random seed
* `resolution` (optional) - Output resolution
* `enhancePrompt` (optional) - Auto-enhance the prompt

<Note>You must provide either `prompt` or `referenceImage`, but not both. The SDK validates this at initialization.</Note>

***

## Manual Polling

For custom polling logic, use `submit()`, `status()`, and `result()` separately:

```swift theme={null}
import Foundation

// Submit job
let job = try await client.queue.submit(model: .lucy2_5, input: input)
print("Job submitted: \(job.jobId)")

// Manual polling loop
while true {
    let status = try await client.queue.status(jobId: job.jobId)
    print("Status: \(status.status)")

    switch status.status {
    case .completed:
        let data = try await client.queue.result(jobId: job.jobId)
        try data.write(to: outputURL)
        print("Video saved!")
        return
    case .failed:
        print("Processing failed")
        return
    default:
        try await Task.sleep(for: .seconds(2))
    }
}
```

***

## Error Handling

```swift theme={null}
do {
    let result = try await client.queue.submitAndPoll(
        model: .lucy2_5,
        input: input
    )
} catch let error as DecartError {
    switch error {
    case .invalidAPIKey:
        print("Invalid API key")
    case .invalidInput(let message):
        print("Invalid input: \(message)")
    case .queueError(let message):
        print("Queue error: \(message)")
    case .networkError(let underlying):
        print("Network error: \(underlying)")
    case .serverError(let message):
        print("Server error: \(message)")
    default:
        print("Error: \(error.localizedDescription)")
    }
}
```

***

## Supported Models

All video models support queue processing:

| Model | Type | Description |
| - | - | - |
| `lucy2_5` | Video-to-Video | Video editing (latest) |
| `lucyVton3_5` | Video-to-Video | Virtual try-on |
| `lucyVton3_6` | Video-to-Video | Virtual try-on (newest) |
| `lucyRestyle2` | Video-to-Video | Video restyling with prompt or reference image |

<Accordion title="Previous generation models">
  | Model | Type | Description |
  | - | - | - |
  | `lucy2_1` | Video-to-Video | Previous video editing |
</Accordion>

***

## API Reference

### `client.queue.submit(model:input:)`

Submit a job for processing.

**Parameters:**

* `model: VideoModel` - Video model
* `input` - Typed input (`VideoEditInput`, `VideoRestyleInput`, or `VideoToVideoInput`)

**Returns:** `JobSubmitResponse`

* `jobId: String` - Unique job identifier
* `status: JobStatus` - Initial status (`.pending`)

***

### `client.queue.status(jobId:)`

Check the status of a job.

**Parameters:**

* `jobId: String` - The job identifier

**Returns:** `JobStatusResponse`

* `jobId: String` - Job identifier
* `status: JobStatus` - Current status

***

### `client.queue.result(jobId:)`

Get the result of a completed job.

**Parameters:**

* `jobId: String` - The job identifier

**Returns:** `Data` - Video bytes

***

### `client.queue.submitAndPoll(model:input:onStatusChange:)`

Submit a job and poll until completion.

**Parameters:**

* `model: VideoModel` - Video model
* `input` - Typed input
* `onStatusChange: ((JobStatusResponse) -> Void)?` - Optional status callback

**Returns:** `QueueJobResult`

***

## Next Steps

<CardGroup>
  <Card title="Process API" icon="image" href="/sdks/swift-process">
    Synchronous image editing
  </Card>

  <Card title="Realtime API" icon="bolt" href="/sdks/swift-realtime">
    Transform video streams in realtime with WebRTC
  </Card>
</CardGroup>


# Realtime API
Source: https://docs.platform.decart.ai/sdks/swift-realtime

Transform video streams in realtime with WebRTC on iOS and macOS

The Realtime API enables you to transform live video streams with minimal latency using WebRTC. Perfect for building iOS camera effects, video conferencing filters, AR applications, and interactive live streaming.

## Quick Start

```swift theme={null}
import DecartSDK
import LiveKit

let model = Models.realtime(.lucy-restyle-2)

// Create client
let config = DecartConfiguration(apiKey: "your-api-key-here")
let client = DecartClient(decartConfiguration: config)

// Create realtime manager
let manager = try client.createRealtimeManager(
    options: RealtimeConfiguration(
        model: model,
        initialPrompt: DecartPrompt(text: "Anime style", enrich: true)
    )
)

// Build a LiveKit camera track sized to the model
let captureOptions = CameraCaptureOptions(
    position: .front,
    dimensions: Dimensions(width: Int32(model.height), height: Int32(model.width)),
    fps: model.fps
)
let mirror = MirroringVideoProcessor(mode: .auto)
let videoTrack = LocalVideoTrack.createCameraTrack(name: "video0", options: captureOptions, processor: mirror)

// Connect and get transformed stream
let localStream = RealtimeMediaStream(videoTrack: videoTrack, id: .localStream)
let remoteStream = try await manager.connect(localStream: localStream)

// Change style on the fly (suspends until the server acks)
try await manager.setPrompt(DecartPrompt(text: "Cyberpunk city", enrich: true))

// Disconnect when done
try? await videoTrack.stop()
await manager.disconnect()
```

## Client-Side Authentication

For iOS and macOS applications, use ephemeral keys instead of embedding your permanent API key in the app bundle. Ephemeral keys are short-lived tokens safe to include in client applications.

<Info>
  Learn more about [client tokens](/getting-started/client-tokens) and why they're important for security.
</Info>

### Fetching an Ephemeral Key

Your app should fetch an ephemeral key from your backend server before connecting:

```swift theme={null}
import Foundation

struct EphemeralKeyResponse: Codable {
    let apiKey: String
    let expiresAt: String
}

func fetchEphemeralKey() async throws -> String {
    // Replace with your backend URL
    let url = URL(string: "https://your-backend.com/api/realtime-token")!

    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    // Add any auth headers your backend requires
    // request.setValue("Bearer \(userToken)", forHTTPHeaderField: "Authorization")

    let (data, response) = try await URLSession.shared.data(for: request)

    guard let httpResponse = response as? HTTPURLResponse,
          httpResponse.statusCode == 200 else {
        throw DecartError.invalidAPIKey
    }

    let keyResponse = try JSONDecoder().decode(EphemeralKeyResponse.self, from: data)
    return keyResponse.apiKey
}
```

### Connecting with an Ephemeral Key

```swift theme={null}
import DecartSDK

func connectToRealtime() async throws -> DecartRealtimeManager {
    // 1. Fetch ephemeral key from your backend
    let ephemeralKey = try await fetchEphemeralKey()

    // 2. Create client with ephemeral key
    let config = DecartConfiguration(apiKey: ephemeralKey)
    let client = DecartClient(decartConfiguration: config)

    // 3. Set up manager and camera, then connect
    let model = Models.realtime(.lucy-restyle-2)

    let manager = try client.createRealtimeManager(
        options: RealtimeConfiguration(
            model: model,
            initialPrompt: DecartPrompt(text: "Anime style", enrich: true)
        )
    )

    let captureOptions = CameraCaptureOptions(
        position: .front,
        dimensions: Dimensions(width: Int32(model.height), height: Int32(model.width)),
        fps: model.fps
    )
    let mirror = MirroringVideoProcessor(mode: .auto)
    let videoTrack = LocalVideoTrack.createCameraTrack(name: "video0", options: captureOptions, processor: mirror)

    let localStream = RealtimeMediaStream(videoTrack: videoTrack, id: .localStream)
    _ = try await manager.connect(localStream: localStream)

    return manager
}
```

<Warning>
  Never hardcode your permanent API key in iOS apps. App bundles can be decompiled, exposing embedded secrets.
</Warning>

## Camera Capture

Realtime media uses LiveKit tracks. Build a `LocalVideoTrack` from LiveKit's camera-track factory, size it from the model registry, and attach a `MirroringVideoProcessor` to pre-flip the front camera.

### Setting Up Capture

```swift theme={null}
import DecartSDK
import LiveKit

let model = Models.realtime(.lucy-restyle-2)

let captureOptions = CameraCaptureOptions(
    position: .front,                                                                  // .front or .back
    dimensions: Dimensions(width: Int32(model.height), height: Int32(model.width)),    // portrait — swap for landscape
    fps: model.fps
)

let mirror = MirroringVideoProcessor(mode: .auto)
let videoTrack = LocalVideoTrack.createCameraTrack(
    name: "video0",
    options: captureOptions,
    processor: mirror
)
```

**`CameraCaptureOptions` parameters:**

* `position` — `.front` or `.back` (LiveKit's `AVCaptureDevice.Position`)
* `dimensions` — `Dimensions(width:height:)`. For portrait output, pass `model.height` as width and `model.width` as height (swap for landscape).
* `fps` — target framerate; use `model.fps`

`LocalVideoTrack.createCameraTrack(name:options:processor:)` starts capture immediately. There's no separate `startCapture()` call.

### Switching Cameras

LiveKit's `CameraCapturer` toggles between front and back. Keep the `MirroringVideoProcessor` in sync so `.auto` mirroring follows the active camera:

```swift theme={null}
guard let cameraCapturer = videoTrack.capturer as? CameraCapturer else { return }
try await cameraCapturer.switchCameraPosition()
mirror.cameraPosition = cameraCapturer.position
```

### Stopping Capture

```swift theme={null}
try? await videoTrack.stop()
```

<Tip>Use `model.fps`, `model.width`, and `model.height` to size the capture so the encoder doesn't have to rescale.</Tip>

<Warning>Camera capture requires a **real iOS device**. The simulator does not support camera access.</Warning>

### Front-camera mirroring

Pre-flipping the selfie input keeps server-baked pixels (watermarks, overlays) correctly oriented when you render the remote stream as-is.

`MirrorMode` values:

* `.off` (default) — never mirror.
* `.auto` — mirror only when the active camera is `.front`. Update `mirror.cameraPosition = cameraCapturer.position` on camera switch.
* `.on` — always mirror.

With mirroring enabled, render both the local preview and the remote stream with `RTCMLVideoViewWrapper(track:)` — no `mirror:` argument.

## Connecting

Create a `DecartRealtimeManager` and connect with your local media stream:

```swift theme={null}
let manager = try client.createRealtimeManager(
    options: RealtimeConfiguration(
        model: Models.realtime(.lucy-restyle-2),
        initialPrompt: DecartPrompt(
            text: "Lego World",
            enrich: true  // Let Decart enhance the prompt (recommended)
        ),
        connection: .init(
            connectionTimeout: 15  // seconds, default
        ),
        media: .init(
            video: .init(
                maxBitrate: 2_500_000,  // default
                preferredCodec: "VP8"   // default
            )
        )
    )
)

let localStream = RealtimeMediaStream(videoTrack: videoTrack, id: .localStream)
let remoteStream = try await manager.connect(localStream: localStream)
```

**`RealtimeConfiguration` parameters:**

* `model` (required) - Realtime model from `Models.realtime()`
* `resolution` (optional) - `.p720` or `.p1080`. Omit for the server's 720p default; pass `.p1080` to request a 1080p remote stream from supported models.
* `speed` (optional) - `.fast` opts into [fast mode](#fast-mode) (2x rate) on supported models. Omit for standard mode. Requires v0.7.1+.
* `initialPrompt` (optional) - Initial transformation prompt
  * `text` - Prompt text
  * `enrich` - Whether to auto-enhance the prompt
  * `referenceImageData` - Optional reference image `Data`
* `connection` (optional) - Connection configuration
  * `iceServers` - STUN/TURN server URLs (default: Google STUN)
  * `connectionTimeout` - Connection timeout in seconds (default: 15)
  * `rtcConfiguration` - Custom `RTCConfiguration` for advanced WebRTC tuning
* `media` (optional) - Media configuration
  * `video.maxBitrate` - Max bitrate in bps (default: 2,500,000)
  * `video.minBitrate` - Min bitrate in bps (default: 300,000)
  * `video.maxFramerate` - Max framerate (default: 30)
  * `video.preferredCodec` - Preferred video codec (default: "VP8")

**Returns:** `RealtimeMediaStream` — the transformed remote stream containing an optional `videoTrack` you can render

For image-capable models, pass the reference image data on `DecartPrompt`:

```swift theme={null}
let imageData = try Data(contentsOf: characterImageURL)

let manager = try client.createRealtimeManager(
    options: RealtimeConfiguration(
        model: Models.realtime(.lucy_v2v_14b_rt),
        initialPrompt: DecartPrompt(
            text: "Substitute the character in the video with the person in the reference image.",
            referenceImageData: imageData,
            enrich: true
        )
    )
)
```

<Tip>
  Set `initialPrompt` (with `referenceImageData` for image-capable models) so the first frame is already transformed — otherwise viewers briefly see the raw camera feed.
</Tip>

### Fast mode

Fast mode (`speed: "fast"`) gives the session lower latency and higher throughput; output quality is unchanged. It is available for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5`, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode. See [Pricing](/getting-started/pricing#realtime-models).

```swift theme={null}
let manager = try client.createRealtimeManager(
    options: RealtimeConfiguration(
        model: Models.realtime(.lucyVton3_5),
        speed: .fast
    )
)
```

Requires SDK v0.7.1+.

`ModelDefinition.supportedSpeeds` contains `.fast` for `lucy-2.5` / `lucy-latest`, `lucy-vton-3.6` / `lucy-vton-latest`, and `lucy-vton-3.5` only. Passing `speed` for another model logs a warning and connects on the standard tier.

## Managing Prompts

Change the transformation style dynamically without reconnecting:

```swift theme={null}
// Simple prompt with automatic enhancement
manager.setPrompt(DecartPrompt(text: "Anime style", enrich: true))

// Custom detailed prompt without enhancement
manager.setPrompt(
    DecartPrompt(
        text: "A detailed artistic style with vibrant colors and dramatic lighting",
        enrich: false
    )
)

// With reference image (for lucy-2.1 model)
// On iOS: let referenceData = UIImage(named: "reference")!.jpegData(compressionQuality: 0.8)!
// On macOS: let referenceData = NSImage(named: "reference")!.tiffRepresentation!
let referenceData = try Data(contentsOf: Bundle.main.url(forResource: "reference", withExtension: "jpg")!)
manager.setPrompt(
    DecartPrompt(
        text: "Match this character style",
        referenceImageData: referenceData,
        enrich: true
    )
)
```

**`DecartPrompt` parameters:**

* `text` (required) - Text description of desired style
* `referenceImageData` (optional) - Reference image data (used with `lucy-2.1`)
* `enrich` (optional) - Whether to enhance the prompt (default: `false`)

<Note>Prompt enhancement uses Decart's AI to expand simple prompts for better results. Only the `lucy-2.1` model supports reference images.</Note>

## Connection State

Monitor connection state, service status, generation ticks, and session ID using the `events` AsyncStream:

```swift theme={null}
// Observe state changes
Task {
    for await state in manager.events {
        switch state.connectionState {
        case .connecting:
            showLoadingIndicator()
        case .connected:
            hideLoadingIndicator()
        case .generating:
            showGeneratingIndicator()
        case .reconnecting:
            showReconnectingIndicator()
        case .disconnected:
            showReconnectButton()
        case .idle:
            break
        case .error:
            showError()
        }

        // Track generation progress
        if let tick = state.generationTick {
            showGenerationTime("\(tick)s")
        }

        // Track session ID
        if let sessionId = state.sessionId {
            print("Session: \(sessionId)")
        }

        // Track queue position
        if let position = state.queuePosition, let size = state.queueSize {
            showQueueStatus("Position \(position) of \(size)")
        }

        // Track service status
        switch state.serviceStatus {
        case .enteringQueue:
            showQueueMessage()
        case .ready:
            hideQueueMessage()
        case .unknown:
            break
        }
    }
}
```

**`DecartRealtimeState` properties:**

* `connectionState` — `.idle`, `.connecting`, `.connected`, `.generating`, `.reconnecting`, `.disconnected`, `.error`
* `serviceStatus` — `.unknown`, `.enteringQueue`, `.ready`
* `queuePosition` — Current position in queue (nil if not queued)
* `queueSize` — Total queue size (nil if not queued)
* `generationTick` — Seconds elapsed during generation (nil when not generating)
* `sessionId` — Current session identifier (nil before session established)

**`DecartRealtimeConnectionState` helpers:**

* `.isConnected` — `true` when connected or generating
* `.isInSession` — `true` when connected, connecting, generating, or reconnecting

## Auto-Reconnect

The SDK automatically reconnects when an unexpected disconnection occurs (e.g., network interruption). During auto-reconnect, the connection state transitions to `.reconnecting` while the SDK retries with exponential backoff (up to 5 attempts, max 10s delay).

When auto-reconnect succeeds, a new `RealtimeMediaStream` is emitted via `remoteStreamUpdates`. You must rebind your UI to the new stream's video track:

```swift theme={null}
Task {
    for await newRemoteStream in manager.remoteStreamUpdates {
        // Update your UI with the new video track
        self.remoteVideoTrack = newRemoteStream.videoTrack
    }
}
```

<Info>
  Auto-reconnect is **not** triggered on user-initiated `disconnect()`, permanent errors (401/403, invalid key, expired session), or after all retries are exhausted. If all retries fail, the state moves to `.error`.
</Info>

## Connection Quality

Two layers report network health on a shared `.good | .fair | .poor | .critical` scale: a **preflight** check before connecting, and an **in-session** signal while connected.

### Preflight

A fast, network-only reachability check. No session, no cost. Never throws — degrades to `.critical` / `.failed` on any error:

```swift theme={null}
let report = await client.checkConnectivity()
// report.metrics: transport (.udp / .relay / .failed), rttMs
if report.quality == .critical {
    showFallbackUI(report.reasons)
}
```

### In-session quality

While connected, the SDK derives a smoothed verdict from live connection stats (latency, packet loss, upstream bandwidth, frame rate) and tells you the limiting factor. The stream yields on debounced level changes; `getConnectionQuality()` returns the live snapshot whose metrics refresh on every poll:

```swift theme={null}
Task {
    for await report in manager.connectionQualityUpdates {
        // report.limitingFactor: .bandwidth | .latency | .loss | .stall | .cpu | .none
        // report.metrics: rttMs, fps, packetLoss, availableUpstreamKbps, ...
        updateBadge(report.quality)
    }
}

let latest = manager.getConnectionQuality() // ConnectionQualityReport? — nil before the first sample
```

In-session quality is on by default. Opt out by passing `observability: .init(connectionQualityEnabled: false)` in `RealtimeConfiguration`.

### Glass-to-glass latency (opt-in)

Network RTT alone doesn't reflect the latency users actually feel — a session can read `.good` while still feeling laggy. Set `debugQuality: true` to measure the real camera→display latency: the SDK stamps a pixel marker into each outgoing frame and reads it back off the rendered output, surfacing startup (`ttffMs`), steady-state (`g2gMs`), and end-to-end frame drops (`g2gDropRatio`). When present, glass-to-glass drives the latency verdict instead of RTT.

```swift theme={null}
let localStream = client.createLocalCameraStream(model: model, debugQuality: true)
let manager = try client.createRealtimeManager(
    options: .init(model: model, debugQuality: true)
)
let remoteStream = try await manager.connect(localStream: localStream)

Task {
    for await report in manager.connectionQualityUpdates {
        // report.metrics.ttffMs / g2gMs / g2gDropRatio
    }
}
```

<Warning>Diagnostic only. The marker is visible (bottom-left of the published and rendered video) and adds per-frame pixel work — don't enable it for production / end-user sessions. The `debugQuality` flag must match on both `createLocalCameraStream` and `RealtimeConfiguration`.</Warning>

### Deep preflight

For a *measured* verdict before connecting, use the deep probe — it briefly opens a real session with a synthetic source, measures glass-to-glass, then tears it down. Requires a `model` and costs a short session:

```swift theme={null}
let probe = await client.checkConnectivity(.init(deep: true, model: model))
// probe.metrics.g2gMs / ttffMs / g2gDropRatio
```

## Error Handling

Errors are thrown from async methods and can also arrive through the `events` stream when the connection state becomes `.error`:

```swift theme={null}
do {
    let remoteStream = try await manager.connect(localStream: localStream)
} catch let error as DecartError {
    switch error {
    case .invalidAPIKey:
        showError("Invalid API key. Please check your credentials.")
    case .webRTCError(let message):
        showError("Connection error: \(message)")
    case .websocketError(let message):
        showError("WebSocket error: \(message)")
    case .connectionTimeout:
        showError("Connection timed out. Please try again.")
    case .serverError(let message):
        showError("Server error: \(message)")
    default:
        showError(error.localizedDescription)
    }
    print("Error code: \(error.errorCode)")
}
```

**Error Cases:**

* `.invalidAPIKey` - API key is invalid or missing
* `.invalidBaseURL(String?)` - Base URL is malformed
* `.webRTCError(String)` - WebRTC connection failed
* `.websocketError(String)` - WebSocket connection error
* `.connectionTimeout` - Connection timed out
* `.serverError(String)` - Server returned an error
* `.processingError(String)` - Processing failed
* `.invalidInput(String)` - Invalid input parameters
* `.modelNotFound(String)` - Specified model doesn't exist
* `.networkError(Error)` - Network request failed
* `.queueError(String)` - Queue operation failed

## Cleanup

Always stop the camera track and disconnect the manager when done:

```swift theme={null}
try? await videoTrack.stop()
await manager.disconnect()
```

<Warning>Failing to disconnect can leave the LiveKit room open and waste resources.</Warning>

## Complete SwiftUI Example

Here's a full SwiftUI application using the SDK's built-in `RTCMLVideoViewWrapper`:

```swift theme={null}
import SwiftUI
import DecartSDK
import LiveKit

@main
struct RealtimeApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

struct ContentView: View {
    @StateObject private var viewModel = RealtimeViewModel()

    var body: some View {
        ZStack {
            // Remote video background
            RTCMLVideoViewWrapper(track: viewModel.remoteVideoTrack)
                .ignoresSafeArea()

            VStack(spacing: 16) {
                // Status bar
                HStack {
                    VStack(alignment: .leading, spacing: 4) {
                        Text("Decart Realtime")
                            .font(.headline)
                            .foregroundColor(.white)
                        Text(viewModel.statusText)
                            .font(.caption)
                            .foregroundColor(
                                viewModel.isConnected ? .green : .white
                            )
                    }
                    Spacer()
                }
                .padding()
                .background(Color.black.opacity(0.6))

                Spacer()

                // Local video preview
                if viewModel.isConnected {
                    HStack {
                        Spacer()
                        RTCMLVideoViewWrapper(track: viewModel.localVideoTrack)
                        .frame(width: 120, height: 160)
                        .clipShape(RoundedRectangle(cornerRadius: 12))
                        .overlay(
                            RoundedRectangle(cornerRadius: 12)
                                .stroke(Color.white, lineWidth: 2)
                        )
                        .padding()
                    }
                }

                // Controls
                VStack(spacing: 12) {
                    if let error = viewModel.lastError {
                        Text(error)
                            .foregroundColor(.red)
                            .font(.caption)
                            .padding(8)
                            .background(Color.black.opacity(0.8))
                            .clipShape(RoundedRectangle(cornerRadius: 8))
                    }

                    HStack(spacing: 12) {
                        TextField("Enter style prompt", text: $viewModel.promptText)
                            .textFieldStyle(.roundedBorder)

                        Button {
                            viewModel.updatePrompt()
                        } label: {
                            Image(systemName: "paperplane.fill")
                                .foregroundColor(.white)
                                .padding(12)
                                .background(
                                    viewModel.isConnected ? Color.blue : Color.gray
                                )
                                .clipShape(RoundedRectangle(cornerRadius: 8))
                        }
                        .disabled(!viewModel.isConnected)
                    }

                    HStack(spacing: 12) {
                        Button {
                            Task { try? await viewModel.switchCamera() }
                        } label: {
                            Image(systemName: "camera.rotate")
                                .foregroundColor(.white)
                                .padding(12)
                                .background(Color.gray.opacity(0.8))
                                .clipShape(Circle())
                        }
                        .disabled(!viewModel.isConnected)

                        Button {
                            Task { await viewModel.toggleConnection() }
                        } label: {
                            Text(viewModel.isConnected ? "Disconnect" : "Connect")
                                .fontWeight(.semibold)
                                .foregroundColor(.white)
                                .frame(maxWidth: .infinity)
                                .padding()
                                .background(
                                    viewModel.isConnected ? Color.red : Color.green
                                )
                                .clipShape(RoundedRectangle(cornerRadius: 12))
                        }
                    }
                }
                .padding()
                .background(Color.black.opacity(0.8))
                .clipShape(RoundedRectangle(cornerRadius: 16))
                .padding()
            }
        }
    }
}

@MainActor
class RealtimeViewModel: ObservableObject {
    @Published var statusText = "Disconnected"
    @Published var promptText = "Turn into a fantasy figure"
    @Published var lastError: String?
    @Published var isConnected = false
    @Published var localVideoTrack: VideoTrack?
    @Published var remoteVideoTrack: VideoTrack?

    private var manager: DecartRealtimeManager?
    private var localTrack: LocalVideoTrack?
    private var mirror: MirroringVideoProcessor?
    private var stateTask: Task<Void, Never>?
    private var reconnectTask: Task<Void, Never>?

    func toggleConnection() async {
        if isConnected {
            await disconnect()
        } else {
            await connect()
        }
    }

    func connect() async {
        statusText = "Connecting"
        lastError = nil

        do {
            let config = DecartConfiguration(
                apiKey: ProcessInfo.processInfo.environment["DECART_API_KEY"] ?? ""
            )
            let client = DecartClient(decartConfiguration: config)
            let model = Models.realtime(.lucy-restyle-2)

            // Create manager
            let manager = try client.createRealtimeManager(
                options: RealtimeConfiguration(
                    model: model,
                    initialPrompt: DecartPrompt(text: promptText, enrich: true)
                )
            )
            self.manager = manager

            // Build a LiveKit camera track sized to the model
            let captureOptions = CameraCaptureOptions(
                position: .front,
                dimensions: Dimensions(width: Int32(model.height), height: Int32(model.width)),
                fps: model.fps
            )
            let mirror = MirroringVideoProcessor(mode: .auto)
            let videoTrack = LocalVideoTrack.createCameraTrack(
                name: "video0",
                options: captureOptions,
                processor: mirror
            )
            self.mirror = mirror
            self.localTrack = videoTrack
            self.localVideoTrack = videoTrack

            // Connect
            let localStream = RealtimeMediaStream(
                videoTrack: videoTrack,
                id: .localStream
            )
            let remoteStream = try await manager.connect(localStream: localStream)
            self.remoteVideoTrack = remoteStream.videoTrack

            // Observe state changes
            stateTask = Task { [weak self] in
                for await state in manager.events {
                    guard let self else { return }
                    self.handleState(state)
                }
            }

            // Handle auto-reconnect track rebinding
            reconnectTask = Task { [weak self] in
                for await newStream in manager.remoteStreamUpdates {
                    guard let self else { return }
                    self.remoteVideoTrack = newStream.videoTrack
                }
            }
        } catch {
            lastError = error.localizedDescription
            statusText = "Disconnected"
        }
    }

    func disconnect() async {
        stateTask?.cancel()
        stateTask = nil
        reconnectTask?.cancel()
        reconnectTask = nil
        try? await localTrack?.stop()
        await manager?.disconnect()
        manager = nil
        localTrack = nil
        mirror = nil
        localVideoTrack = nil
        remoteVideoTrack = nil
        isConnected = false
        statusText = "Disconnected"
    }

    func updatePrompt() {
        guard let manager else { return }
        Task {
            do {
                try await manager.setPrompt(DecartPrompt(text: promptText, enrich: true))
            } catch {
                lastError = "Prompt rejected: \(error.localizedDescription)"
            }
        }
    }

    func switchCamera() async throws {
        guard let cameraCapturer = localTrack?.capturer as? CameraCapturer else { return }
        try await cameraCapturer.switchCameraPosition()
        mirror?.cameraPosition = cameraCapturer.position
    }

    private func handleState(_ state: DecartRealtimeState) {
        switch state.connectionState {
        case .connecting:
            statusText = "Connecting"
            isConnected = false
        case .connected:
            statusText = "Connected"
            isConnected = true
        case .generating:
            if let tick = state.generationTick {
                statusText = "Generating (\(String(format: "%.1f", tick))s)"
            } else {
                statusText = "Generating"
            }
            isConnected = true
        case .reconnecting:
            statusText = "Reconnecting..."
            isConnected = false
        case .disconnected:
            statusText = "Disconnected"
            isConnected = false
        case .error:
            statusText = "Error"
            isConnected = false
        case .idle:
            break
        }

        if state.serviceStatus == .enteringQueue,
           let position = state.queuePosition {
            statusText = "In queue (position \(position))"
        }
    }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use model properties for video constraints">
    Size `CameraCaptureOptions` from the model registry so the encoder doesn't have to rescale.

    ```swift theme={null}
    let model = Models.realtime(.lucy-restyle-2)
    let captureOptions = CameraCaptureOptions(
        position: .front,
        dimensions: Dimensions(width: Int32(model.height), height: Int32(model.width)),
        fps: model.fps
    )
    ```
  </Accordion>

  <Accordion title="Enable prompt enrichment">
    For best results, set `enrich: true` to let Decart's AI enhance your prompts. Only disable it if you need exact prompt control.
  </Accordion>

  <Accordion title="Handle auto-reconnect streams">
    Always observe `remoteStreamUpdates` to rebind your video track when the SDK auto-reconnects after a network interruption.
  </Accordion>

  <Accordion title="Observe state with AsyncStream">
    Use `for await state in manager.events` to track connection state, generation ticks, session ID, and queue position in a structured concurrency context.
  </Accordion>

  <Accordion title="Clean up properly">
    Always call `manager.disconnect()` and `capture.stopCapture()` when done to avoid memory leaks and unnecessary resource usage.
  </Accordion>

  <Accordion title="Test on real devices">
    Always test camera features on real iOS devices, as the simulator does not support WebRTC camera access.
  </Accordion>

  <Accordion title="Request permissions properly">
    Add camera and microphone usage descriptions to your Info.plist and handle permission denials gracefully in your UI.
  </Accordion>
</AccordionGroup>

## API Reference

### `DecartClient.createRealtimeManager(options:)`

Creates a realtime manager for a WebRTC session.

**Parameters:**

* `options: RealtimeConfiguration` - Configuration for the realtime session
  * `model: ModelDefinition` - Realtime model from `Models.realtime()`
  * `speed: Speed?` - `.fast` for [fast mode](#fast-mode) (2x rate) on supported models; `nil` (default) for standard. Requires v0.7.1+.
  * `initialPrompt: DecartPrompt` - Initial transformation prompt (default: empty)
    * `text: String` - Prompt text
    * `enrich: Bool` - Whether to auto-enhance the prompt
    * `referenceImageData: Data?` - Optional reference image data
  * `connection: ConnectionConfig` - Connection settings (default: standard)
  * `media: MediaConfig` - Media settings (default: standard)

**Returns:** `DecartRealtimeManager`

**Throws:** `DecartError` if the signaling URL cannot be constructed

### `DecartRealtimeManager.connect(localStream:)`

Connects to the realtime transformation service.

**Parameters:**

* `localStream: RealtimeMediaStream` - Local media stream with camera video track

**Returns:** `RealtimeMediaStream` — the transformed remote stream

**Throws:** `DecartError` if connection fails or times out

### `DecartRealtimeManager.setPrompt(_:)`

Changes the transformation style.

**Parameters:**

* `prompt: DecartPrompt` - Prompt with text, optional reference image, and enrich flag

### `DecartRealtimeManager.disconnect()`

Closes the connection and cleans up WebRTC resources.

### `DecartRealtimeManager.events`

An `AsyncStream<DecartRealtimeState>` that emits state changes.

### `DecartRealtimeManager.remoteStreamUpdates`

An `AsyncStream<RealtimeMediaStream>` that emits new remote streams after auto-reconnect.

### `LocalVideoTrack.createCameraTrack(name:options:processor:)`

LiveKit factory that opens the camera and produces a `LocalVideoTrack`. Capture starts immediately — there is no separate `startCapture()` call.

**Parameters:**

* `name: String` - Track identifier (e.g. `"video0"`)
* `options: CameraCaptureOptions` - Position, dimensions, fps
* `processor: VideoProcessor?` - Optional `MirroringVideoProcessor` (or any LiveKit `VideoProcessor`)

### `CameraCapturer.switchCameraPosition()`

Toggles between front and back cameras. Access via `videoTrack.capturer as? CameraCapturer`. After switching, update `mirror.cameraPosition = cameraCapturer.position` to keep `MirrorMode.auto` in sync.

### `LocalVideoTrack.stop()`

Async. Stops capture and releases the track. Call before `manager.disconnect()` during cleanup.

## Next Steps

<CardGroup>
  <Card title="SDK Overview" icon="swift" href="/sdks/swift">
    Learn about installation, setup, and Swift SDK fundamentals
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/DecartAI/decart-ios">
    Browse the SDK source code and contribute
  </Card>
</CardGroup>