Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DecartAI/ai-sdk-provider/llms.txt

Use this file to discover all available pages before exploring further.

The Decart provider supports model-specific options that can be passed via providerOptions.decart when generating videos. These options allow you to control video generation behavior beyond the standard AI SDK options.

​
Overview

Provider options are passed through the providerOptions parameter in video generation calls: 
import { decart } from '@decartai/ai-sdk-provider';
import { experimental_generateVideo as generateVideo } from 'ai';

const { videos } = await generateVideo({
  model: decart.video('lucy-motion'),
  prompt: 'A camera moving through a scene',
  providerOptions: {
    decart: {
      // Decart-specific options
      trajectory: [...],
      orientation: 'landscape',
      pollIntervalMs: 2000,
      pollTimeoutMs: 600000,
    },
  },
});

​
Available Options

​
trajectory

​
trajectory
Array<{ frame: number; x: number; y: number }>
Defines a motion path for the lucy-motion model. Each point specifies a frame number and normalized x,y coordinates (0.0 to 1.0).
The trajectory array controls camera or subject movement over time. Each point in the array represents a keyframe:
  • frame: The frame number (0-based)
  • x: Horizontal position (0.0 = left, 1.0 = right)
  • y: Vertical position (0.0 = top, 1.0 = bottom)
Example - Diagonal Movement: 
const { videos } = await generateVideo({
  model: decart.video('lucy-motion'),
  prompt: {
    image: imageData,
    text: 'The camera moves diagonally across the scene',
  },
  providerOptions: {
    decart: {
      trajectory: [
        { frame: 0, x: 0.2, y: 0.2 },   // Start top-left
        { frame: 12, x: 0.5, y: 0.5 },  // Middle of video, center
        { frame: 25, x: 0.8, y: 0.8 },  // End bottom-right
      ],
    },
  },
});
Example - Circular Motion: 
const { videos } = await generateVideo({
  model: decart.video('lucy-motion'),
  prompt: {
    image: imageData,
    text: 'The camera orbits around the subject',
  },
  providerOptions: {
    decart: {
      trajectory: [
        { frame: 0, x: 0.7, y: 0.5 },   // Right
        { frame: 6, x: 0.5, y: 0.3 },   // Top
        { frame: 12, x: 0.3, y: 0.5 },  // Left
        { frame: 18, x: 0.5, y: 0.7 },  // Bottom
        { frame: 25, x: 0.7, y: 0.5 },  // Back to right
      ],
    },
  },
});
The trajectory option is only supported by the lucy-motion model. It will be ignored for other video models.

​
orientation

​
orientation
'landscape' | 'portrait'
Explicitly sets the video orientation. This overrides the orientation derived from the aspectRatio parameter.
Example: 
const { videos } = await generateVideo({
  model: decart.video('lucy-pro-t2v'),
  prompt: 'A sunset over the ocean',
  providerOptions: {
    decart: {
      orientation: 'landscape',
    },
  },
});
The orientation option takes precedence over aspectRatio. If both are provided, orientation will be used.
Orientation vs. Aspect Ratio:
aspectRatioDerived orientation
16:9landscape
9:16portrait
Otherundefined (warning)

​
pollIntervalMs

​
pollIntervalMs
number
default:"1500"
The interval in milliseconds between status polling requests when checking video generation job status.
Video generation is asynchronous. After submitting a job, the SDK polls the API to check when the video is ready. This option controls how frequently those checks occur. Example - Faster Polling: 
const { videos } = await generateVideo({
  model: decart.video('lucy-pro-t2v'),
  prompt: 'A fast-paced action scene',
  providerOptions: {
    decart: {
      pollIntervalMs: 1000, // Poll every second
    },
  },
});
Example - Slower Polling: 
const { videos } = await generateVideo({
  model: decart.video('lucy-pro-t2v'),
  prompt: 'A peaceful landscape',
  providerOptions: {
    decart: {
      pollIntervalMs: 3000, // Poll every 3 seconds
    },
  },
});
Setting pollIntervalMs too low may result in unnecessary API calls and increased costs. The default of 1500ms is recommended for most use cases.

​
pollTimeoutMs

​
pollTimeoutMs
number
default:"300000"
The maximum time in milliseconds to wait for video generation to complete. Default is 300,000ms (5 minutes).
If the video generation job doesn’t complete within this time, the SDK will throw a timeout error. Example - Extended Timeout: 
const { videos } = await generateVideo({
  model: decart.video('lucy-pro-t2v'),
  prompt: 'A complex scene with many details',
  providerOptions: {
    decart: {
      pollTimeoutMs: 600000, // 10 minutes
    },
  },
});
Example - Short Timeout: 
const { videos } = await generateVideo({
  model: decart.video('lucy-pro-t2v'),
  prompt: 'Quick test video',
  providerOptions: {
    decart: {
      pollTimeoutMs: 120000, // 2 minutes
    },
  },
});
If a timeout occurs, you’ll receive an AI_APICallError with a message indicating the timeout duration. See Error Handling for more details.

​
Complete Example

Here’s a comprehensive example using all provider options: 
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-motion'),
  prompt: {
    image: fs.readFileSync('input.png'),
    text: 'The camera slowly pans across the scene from left to right',
  },
  aspectRatio: '16:9',
  seed: 42,
  resolution: '1280x720',
  providerOptions: {
    decart: {
      // Define a smooth left-to-right pan
      trajectory: [
        { frame: 0, x: 0.2, y: 0.5 },
        { frame: 8, x: 0.4, y: 0.5 },
        { frame: 16, x: 0.6, y: 0.5 },
        { frame: 25, x: 0.8, y: 0.5 },
      ],
      // Explicitly set landscape orientation
      orientation: 'landscape',
      // Poll every 2 seconds
      pollIntervalMs: 2000,
      // Wait up to 10 minutes
      pollTimeoutMs: 600000,
    },
  },
});

fs.writeFileSync('output.mp4', videos[0].uint8Array);
console.log('Video generated successfully!');

​
Polling Behavior

The Decart API uses an asynchronous job-based system for video generation:
  1. Submit Job: The SDK sends a POST request to /v1/jobs/{modelId} with your parameters
  2. Receive Job ID: The API returns a job ID immediately
  3. Poll Status: The SDK repeatedly checks /v1/jobs/{jobId} until the status is completed or failed
  4. Download Video: Once complete, the SDK downloads the video from /v1/jobs/{jobId}/content
The polling options control steps 3 and 4: 
// Job submitted, polling begins
let elapsed = 0;
while (elapsed < pollTimeoutMs) {
  await delay(pollIntervalMs);
  
  const status = await checkJobStatus(jobId);
  
  if (status === 'completed') {
    // Download and return video
    return await downloadVideo(jobId);
  }
  
  if (status === 'failed') {
    throw new Error('Job failed');
  }
  
  elapsed += pollIntervalMs;
}

throw new Error('Timeout');

​
Model Support

Different options are supported by different models:
Optionlucy-pro-t2vlucy-pro-i2vlucy-dev-i2vlucy-motion
trajectoryNoNoNoYes
orientationYesYesYesYes
pollIntervalMsYesYesYesYes
pollTimeoutMsYesYesYesYes
  • Configuration - Learn about provider-level configuration
  • Error Handling - Learn how to handle polling timeouts and other errors
  • Video Models - Learn about available video models and their capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us