Image-to-Video

Image-to-video generation animates static images into dynamic videos. Decart provides two models for this capability: lucy-pro-i2v for production use and lucy-dev-i2v for development and testing.

Basic Usage

Import Dependencies

import { decart } from '@decartai/ai-sdk-provider';
import { experimental_generateVideo as generateVideo } from 'ai';
import fs from 'fs';

Load Image

Load your input image as a Uint8Array:

const imageData = fs.readFileSync('input-image.jpg');

Generate Video

Pass the image and an optional text prompt:

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: imageData,
    text: 'The subject begins to walk forward slowly',
  },
});

Source Reference: examples/tasks/video-generation-i2v.ts:7-14

Save the Video

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

Complete Example

import { decart } from '@decartai/ai-sdk-provider';
import { experimental_generateVideo as generateVideo } from 'ai';
import fs from 'fs';

export async function animateImage(imagePath: string) {
  const imageData = fs.readFileSync(imagePath);
  
  const result = await generateVideo({
    model: decart.video('lucy-pro-i2v'),
    prompt: {
      image: imageData,
      text: 'The subject begins to walk forward slowly',
    },
  });
  
  const filename = `animated-${Date.now()}.mp4`;
  fs.writeFileSync(filename, result.videos[0].uint8Array);
  console.log(`Video saved to ${filename}`);
  
  return result;
}

Model Selection

lucy-pro-i2v (Production)

Use lucy-pro-i2v for high-quality, production-ready image-to-video generation:

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: imageData,
    text: 'The character turns their head and smiles',
  },
});

Source Reference: src/decart-video-settings.ts:3

lucy-dev-i2v (Development)

Use lucy-dev-i2v for faster iteration during development:

const { videos } = await generateVideo({
  model: decart.video('lucy-dev-i2v'),
  prompt: {
    image: imageData,
    text: 'Testing animation concept',
  },
});

The development model processes faster but may have lower quality compared to the production model.Source Reference: src/decart-video-settings.ts:4

Image Input Formats

The image field accepts different input types:

Uint8Array
URL
Base64

const imageData = fs.readFileSync('image.jpg');

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: imageData,
    text: 'The scene comes to life',
  },
});

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: { type: 'url', url: 'https://example.com/image.jpg' },
    text: 'The scene comes to life',
  },
});

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: {
      type: 'data',
      data: base64String,
      mediaType: 'image/jpeg',
    },
    text: 'The scene comes to life',
  },
});

The provider automatically handles image format conversion and appends it to the request.Source References:

Image handling: src/decart-video-model.ts:51-63
Base64 conversion: src/decart-video-model.ts:65-72
FormData append: src/decart-video-model.ts:164-166

Animation Guidance

Text Prompts for Animation

The text prompt guides how the image should be animated:

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: portraitImage,
    text: 'The person looks around curiously',
  },
});

Effective Animation Prompts

Good Animation Prompts:

“The character turns their head to the left”
“Gentle wind blows through the trees”
“The subject walks forward towards the camera”
“Waves crash against the shore”
“The person smiles and nods”

Tips:

Describe natural, plausible movements
Keep motion descriptions simple and focused
Consider the physics and constraints of the scene
Specify direction and speed when relevant

Image-Only Generation

You can omit the text prompt to let the model determine appropriate animation:

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: imageData,
  },
});

While text prompts are optional, providing clear animation guidance typically produces better results.

Customizing Output

Aspect Ratio

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: imageData,
    text: 'The scene animates smoothly',
  },
  aspectRatio: '16:9',
});

Supported aspect ratios: 16:9 (landscape) and 9:16 (portrait)Source Reference: src/decart-video-model.ts:113-122

Resolution

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: { image: imageData, text: 'Animate' },
  resolution: '1280x720',
});

Source Reference: src/decart-video-model.ts:42-49

Reproducible Results

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: imageData,
    text: 'The subject looks to the right',
  },
  seed: 12345,
});

Using the same image, prompt, seed, and settings will produce consistent results.

Advanced Options

Custom Polling

Image-to-video generation is asynchronous. Customize the polling behavior:

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: {
    image: imageData,
    text: 'Complex animation sequence',
  },
  providerOptions: {
    decart: {
      pollIntervalMs: 2000,  // Check every 2 seconds
      pollTimeoutMs: 600000, // 10 minute timeout
    },
  },
});

Source References:

Poll interval: src/decart-video-model.ts:196
Poll timeout: src/decart-video-model.ts:197

Direct Orientation Control

Override aspect ratio by setting orientation directly:

const { videos } = await generateVideo({
  model: decart.video('lucy-pro-i2v'),
  prompt: { image: imageData, text: 'Animate' },
  providerOptions: {
    decart: {
      orientation: 'portrait',
    },
  },
});

Source Reference: src/decart-video-model.ts:27-28

Comparison: Production vs Development

Feature	lucy-pro-i2v	lucy-dev-i2v
Quality	High	Standard
Speed	Standard	Faster
Use Case	Production	Development/Testing
API Interface	Identical	Identical
Settings Support	Full	Full

Error Handling

try {
  const imageData = fs.readFileSync('portrait.jpg');
  
  const { videos } = await generateVideo({
    model: decart.video('lucy-pro-i2v'),
    prompt: {
      image: imageData,
      text: 'The person waves hello',
    },
  });
  
  fs.writeFileSync('animated.mp4', videos[0].uint8Array);
} catch (error) {
  if (error.name === 'AI_APICallError') {
    console.error('Animation failed:', error.message);
  }
  throw error;
}

Common issues:

Invalid image format or corrupted image data
Image too large or too small
Generation timeout (default: 5 minutes)
Network errors during upload or download

Next Steps

Motion Control

Control precise movement with trajectories

Text-to-Video

Generate videos from text prompts

Settings Reference

View all configuration options

Examples

Browse complete working examples

Get Started

Image Generation

Video Generation

Advanced

Basic Usage

Complete Example

Model Selection

lucy-pro-i2v (Production)

lucy-dev-i2v (Development)

Image Input Formats

Animation Guidance

Text Prompts for Animation

Image-Only Generation

Customizing Output

Aspect Ratio

Resolution

Reproducible Results

Advanced Options

Custom Polling

Direct Orientation Control

Comparison: Production vs Development

Error Handling

Next Steps

Motion Control

Text-to-Video

Settings Reference

Examples

Build docs developers (and LLMs) love

Get Started

Image Generation

Video Generation

Advanced

Documentation Index

​Basic Usage

​Complete Example

​Model Selection

​lucy-pro-i2v (Production)

​lucy-dev-i2v (Development)

​Image Input Formats

​Animation Guidance

​Text Prompts for Animation

​Image-Only Generation

​Customizing Output

​Aspect Ratio

​Resolution

​Reproducible Results

​Advanced Options

​Custom Polling

​Direct Orientation Control

​Comparison: Production vs Development

​Error Handling

​Next Steps

Motion Control

Text-to-Video

Settings Reference

Examples

Build docs developers (and LLMs) love

Basic Usage

Complete Example

Model Selection

lucy-pro-i2v (Production)

lucy-dev-i2v (Development)

Image Input Formats

Animation Guidance

Text Prompts for Animation

Image-Only Generation

Customizing Output

Aspect Ratio

Resolution

Reproducible Results

Advanced Options

Custom Polling

Direct Orientation Control

Comparison: Production vs Development

Error Handling

Next Steps