Skip to main content

​
Overview

The Decart SDK provides a type-safe model registry that organizes models into three categories:
  • Realtime models - WebRTC-based streaming for interactive experiences
  • Video models - Queue-based async processing for video generation
  • Image models - Synchronous processing for image generation
Each model comes with a complete definition including resolution, frame rate, and input validation schema.

​
Model Registry Functions

The SDK exports a models object with three factory functions: 
import { models } from '@decartai/sdk';

// Get a realtime model definition
const realtimeModel = models.realtime('mirage');

// Get a video model definition
const videoModel = models.video('lucy-pro-t2v');

// Get an image model definition
const imageModel = models.image('lucy-pro-t2i');

​
TypeScript Signatures

type models = {
  realtime: <T extends RealTimeModels>(model: T) => ModelDefinition<T>;
  video: <T extends VideoModels>(model: T) => ModelDefinition<T>;
  image: <T extends ImageModels>(model: T) => ModelDefinition<T>;
};

​
Model Definitions

Each model definition contains: 
type ModelDefinition = {
  name: string;           // Model identifier
  urlPath: string;        // API endpoint path
  queueUrlPath?: string;  // Queue API endpoint (for video/image models)
  fps: number;            // Frames per second
  width: number;          // Video/image width in pixels
  height: number;         // Video/image height in pixels
  inputSchema: ZodSchema; // Zod validation schema for inputs
};

​
Example Model Definition

const model = models.video('lucy-pro-t2v');

console.log(model);
// {
//   name: 'lucy-pro-t2v',
//   urlPath: '/v1/generate/lucy-pro-t2v',
//   queueUrlPath: '/v1/jobs/lucy-pro-t2v',
//   fps: 25,
//   width: 1280,
//   height: 704,
//   inputSchema: ZodObject { ... }
// }

​
Realtime Models

Realtime models use WebRTC for low-latency interactive video streaming.
​
mirage
RealTimeModel
Real-time video restyling model
  • FPS: 25
  • Resolution: 1280x704
​
mirage_v2
RealTimeModel
Real-time video restyling model (v2)
  • FPS: 22
  • Resolution: 1280x704
​
lucy_v2v_720p_rt
RealTimeModel
Real-time video editing model
  • FPS: 25
  • Resolution: 1280x704
​
lucy_2_rt
RealTimeModel
Real-time video editing model with reference image support
  • FPS: 20
  • Resolution: 1280x720
​
live_avatar
RealTimeModel
Real-time avatar generation model
  • FPS: 25
  • Resolution: 1280x720

​
Usage with Realtime Client

import { createDecartClient, models } from '@decartai/sdk';

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

const stream = await client.realtime.connect({
  model: models.realtime('mirage'),
  onRemoteStream: (stream) => {
    videoElement.srcObject = stream;
  }
});

​
Video Models

Video models use the queue API for asynchronous video generation.
​
lucy-pro-t2v
VideoModel
Text-to-video (Pro quality)
  • FPS: 25
  • Resolution: 1280x704
  • Inputs: prompt, seed?, resolution?, orientation?
​
lucy-pro-i2v
VideoModel
Image-to-video (Pro quality)
  • FPS: 25
  • Resolution: 1280x704
  • Inputs: prompt, data (image), seed?, resolution?
  • Output: 5 seconds max
​
lucy-dev-i2v
VideoModel
Image-to-video (Dev quality)
  • FPS: 25
  • Resolution: 1280x704 (720p only)
  • Inputs: prompt, data (image), seed?, resolution?
  • Output: 5 seconds max
​
lucy-pro-v2v
VideoModel
Video-to-video (Pro quality)
  • FPS: 25
  • Resolution: 1280x704 (720p only)
  • Inputs: prompt, data (video), reference_image?, seed?, resolution?, enhance_prompt?
  • Output: 5 seconds max
​
lucy-fast-v2v
VideoModel
Video-to-video (Fast quality)
  • FPS: 25
  • Resolution: 1280x720 (720p only)
  • Inputs: prompt, data (video), seed?, resolution?, enhance_prompt?
  • Output: 5 seconds max
​
lucy-restyle-v2v
VideoModel
Video restyling (video-to-video)
  • FPS: 22
  • Resolution: 1280x704 (720p only)
  • Inputs: Either prompt OR reference_image (not both), data (video), seed?, resolution?, enhance_prompt?
​
lucy-pro-flf2v
VideoModel
First-last-frame-to-video (Pro quality)
  • FPS: 25
  • Resolution: 1280x704
  • Inputs: prompt, start (image), end (image), seed?, resolution?
​
lucy-motion
VideoModel
Motion-based image-to-video with trajectory guidance
  • FPS: 25
  • Resolution: 1280x704 (720p only)
  • Inputs: data (image), trajectory (array of frame/x/y points), seed?, resolution?
  • Output: 5 seconds max

​
Usage with Queue Client

import { createDecartClient, models } from '@decartai/sdk';

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

const result = await client.queue.submitAndPoll({
  model: models.video('lucy-pro-t2v'),
  prompt: 'A beautiful sunset over the ocean',
  seed: 42,
  resolution: '720p'
});

if (result.status === 'completed') {
  const videoUrl = URL.createObjectURL(result.data);
}

​
Image Models

Image models use the process API for synchronous image generation.
​
lucy-pro-t2i
ImageModel
Text-to-image (Pro quality)
  • FPS: 25
  • Resolution: 1280x704
  • Inputs: prompt, seed?, resolution?, orientation?
  • Resolutions: 720p (default), 480p
​
lucy-pro-i2i
ImageModel
Image-to-image (Pro quality)
  • FPS: 25
  • Resolution: 1280x704
  • Inputs: prompt, data (image), seed?, resolution?, enhance_prompt?
  • Resolutions: 720p (default), 480p

​
Usage with Process Client

import { createDecartClient, models } from '@decartai/sdk';

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

const blob = await client.process({
  model: models.image('lucy-pro-t2i'),
  prompt: 'A beautiful sunset over the ocean',
  seed: 42,
  resolution: '720p'
});

const imageUrl = URL.createObjectURL(blob);

​
Type Guards

The SDK provides type guard functions to check model types: 
import { isRealtimeModel, isVideoModel, isImageModel } from '@decartai/sdk';

const modelName = 'lucy-pro-t2v';

if (isRealtimeModel(modelName)) {
  // modelName is typed as RealTimeModels
}

if (isVideoModel(modelName)) {
  // modelName is typed as VideoModels
}

if (isImageModel(modelName)) {
  // modelName is typed as ImageModels
}

​
File Input Types

Models that accept image or video inputs support multiple file formats: 
type FileInput =
  | File              // Browser File object
  | Blob              // Blob object
  | ReadableStream    // ReadableStream
  | URL               // URL object
  | string            // URL as string
  | ReactNativeFile;  // React Native file object

// React Native file format
type ReactNativeFile = {
  uri: string;
  type: string;
  name: string;
};

​
Example with Different Input Types

// Using a URL string
await client.queue.submit({
  model: models.video('lucy-pro-i2v'),
  prompt: 'Animate this image',
  data: 'https://example.com/image.jpg'
});

// Using a File object
const file = new File([blob], 'image.jpg', { type: 'image/jpeg' });
await client.queue.submit({
  model: models.video('lucy-pro-i2v'),
  prompt: 'Animate this image',
  data: file
});

// Using a Blob
await client.queue.submit({
  model: models.video('lucy-pro-i2v'),
  prompt: 'Animate this image',
  data: blob
});

​
Custom Model Definitions

You can provide custom model configurations: 
import type { CustomModelDefinition } from '@decartai/sdk';

const customModel: CustomModelDefinition = {
  name: 'my-custom-model',
  urlPath: '/v1/custom/model',
  fps: 30,
  width: 1920,
  height: 1080
};

// Use with any client
await client.realtime.connect({
  model: customModel,
  onRemoteStream: (stream) => { /* ... */ }
});

Build docs developers (and LLMs) love

Get started for freeTalk to us