Skip to main content
The Process API enables you to generate videos and images from text, or transform existing media with style transfer. Perfect for building content creation tools, media processing pipelines, batch transformations, and creative applications.

​
Video

​
Video Generation

Generate videos from text prompts: 
result = await client.process({
    "model": models.video("lucy-pro-t2v"),
    "prompt": "A serene lake at sunset with mountains in the background",
    "seed": 42,
    "resolution": "720p",
    "orientation": "landscape",
})

# Save the video
with open("output.mp4", "wb") as f:
    f.write(result)
Parameters:
  • prompt (required) - Text description of the video to generate
  • seed (optional) - Random seed for reproducible results
  • resolution (optional) - Output resolution (e.g., “480p”, “720p”)
  • orientation (optional) - Output orientation (“landscape”, “portrait”)
Model: lucy-pro-t2v

​
Image Animation

Animate static images into videos: 
# Using a file path
with open("image.jpg", "rb") as image_file:
    result = await client.process({
        "model": models.video("lucy-pro-i2v"),
        "prompt": "Animate with gentle motion and wind",
        "data": image_file,
        "seed": 123,
        "resolution": "720p",
    })
Parameters:
  • prompt (required) - Text description of the animation style
  • data (required) - Input image (file object, bytes, or URL)
  • seed (optional) - Random seed for reproducible results
  • resolution (optional) - Output resolution
Model: lucy-dev-i2v, lucy-pro-i2v

​
Motion Control

Control object motion with precise trajectory paths: 
from decart.types import MotionTrajectoryInput

# Using a file path
with open("product-image.jpg", "rb") as image_file:
    result = await client.process({
        "model": models.video("lucy-motion"),
        "data": image_file,
        "trajectory": [
            MotionTrajectoryInput(frame=0, x=0, y=0),
            MotionTrajectoryInput(frame=1, x=100, y=100),
            MotionTrajectoryInput(frame=2, x=200, y=150),
            MotionTrajectoryInput(frame=3, x=300, y=180),
        ],
        "seed": 42,
    })
Parameters:
  • data (required) - Input image (file object, bytes, or URL)
  • trajectory (required) - List of MotionTrajectoryInput objects with frame, x, y
  • seed (optional) - Random seed for reproducible results
  • resolution (optional) - Output resolution (currently only “720p”)
Model: lucy-motion
For detailed documentation, see the Video Generation guide.

​
Video Editing

Transform and restyle existing videos: 
# Using a file path
with open("video.mp4", "rb") as video_file:
    result = await client.process({
        "model": models.video("lucy-pro-v2v"),
        "prompt": "Convert to anime style with vibrant colors",
        "data": video_file,
        "enhance_prompt": True,
        "num_inference_steps": 50,
    })
You can also use URLs as input: 
result = await client.process({
    "model": models.video("lucy-pro-v2v"),
    "prompt": "Watercolor painting style",
    "data": "https://example.com/video.mp4",
})
Parameters:
  • prompt (required) - Text description of the style transformation
  • data (required) - Input video (file object, bytes, or URL string)
  • seed (optional) - Random seed for reproducible results
  • resolution (optional) - Output resolution
  • enhance_prompt (optional) - Auto-enhance the prompt for better results
  • num_inference_steps (optional) - Number of inference steps (pro model only)
Model: lucy-dev-v2v, lucy-pro-v2v

​
Image

​
Image Generation

Generate images from text prompts: 
result = await client.process({
    "model": models.image("lucy-pro-t2i"),
    "prompt": "A futuristic cityscape at night with neon lights",
    "seed": 42,
    "orientation": "portrait",
    "resolution": "720p",
})

# Save the image
with open("output.png", "wb") as f:
    f.write(result)
Parameters:
  • prompt (required) - Text description of the image to generate
  • seed (optional) - Random seed for reproducible results
  • resolution (optional) - Output resolution
  • orientation (optional) - Output orientation (“landscape”, “portrait”)
Model: lucy-pro-t2i

​
Image Editing

Transform and restyle existing images: 
with open("image.jpg", "rb") as image_file:
    result = await client.process({
        "model": models.image("lucy-pro-i2i"),
        "prompt": "Oil painting style with impressionist brushstrokes",
        "data": image_file,
        "enhance_prompt": True,
        "seed": 123,
    })
Parameters:
  • prompt (required) - Text description of the style transformation
  • data (required) - Input image (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-pro-i2i

​
Input Types

The data, start, and end parameters accept flexible input types: 
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: 
# Path object (recommended for files)
from pathlib import Path

result = await client.process({
    "model": models.video("lucy-pro-i2v"),
    "prompt": "Animate this",
    "data": Path("./image.jpg"),
})

# File object from open()
with open("image.jpg", "rb") as file:
    result = await client.process({
        "model": models.video("lucy-pro-i2v"),
        "prompt": "Animate this",
        "data": file,
    })

# Bytes
with open("image.jpg", "rb") as f:
    image_bytes = f.read()

result = await client.process({
    "model": models.video("lucy-pro-i2v"),
    "prompt": "Animate this",
    "data": image_bytes,
})

# URL string
result = await client.process({
    "model": models.video("lucy-pro-v2v"),
    "prompt": "Transform this video",
    "data": "https://example.com/video.mp4",
})

# File path string (auto-detected)
result = await client.process({
    "model": models.video("lucy-pro-v2v"),
    "prompt": "Transform this",
    "data": "./video.mp4",  # Automatically detected as file path
})
The SDK automatically detects whether a string is a file path or URL. Use Path objects for explicit file paths.

​
Cancellation

Cancel long-running operations using asyncio.Event: 
import asyncio

cancel_token = asyncio.Event()

try:
    result = await client.process({
        "model": models.video("lucy-pro-t2v"),
        "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: 
import asyncio

current_cancel_token: asyncio.Event | None = None

async def generate_video(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.video("lucy-pro-t2v"),
        "prompt": prompt,
        "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: 
from decart import (
    DecartClient,
    InvalidInputError,
    InvalidAPIKeyError,
    ProcessingError,
    DecartSDKError,
)

try:
    with open("image.jpg", "rb") as image_file:
        result = await client.process({
            "model": models.video("lucy-pro-i2v"),
            "prompt": "Animate 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: 
# Missing required field
await client.process({
    "model": models.video("lucy-pro-i2v"),
    "prompt": "test",
    # Missing 'data' field
})
# Raises InvalidInputError: Invalid inputs for lucy-pro-i2v: data is required
Import specific exception types for better error handling and type safety.

​
API Reference

​
client.process(options)

Generate or transform media. Parameters:
  • options: dict - Configuration dictionary with model and inputs:
    • model - Model from models.video() or models.image()
    • cancel_token: asyncio.Event - Optional event for cancellation
    • Additional fields depend on the model (see below)
Returns: bytes - The generated/transformed media Inputs by Model:
  • prompt: str - Text description (required)
  • seed: int - Random seed for reproducibility
  • resolution: str - Output resolution (e.g., “480p”, “720p”)
  • orientation: str - Output orientation (“landscape”, “portrait”)
  • prompt: str - Text description (required)
  • data: FileInput - Input image (required)
  • seed: int - Random seed
  • resolution: str - Output resolution
  • prompt: str - Style description (required)
  • data: FileInput - Input video (required)
  • seed: int - Random seed
  • resolution: str - Output resolution
  • enhance_prompt: bool - Auto-enhance prompt
  • num_inference_steps: int - Number of inference steps (pro only)
  • prompt: str - Text description (required)
  • seed: int - Random seed
  • resolution: str - Output resolution
  • orientation: str - Output orientation
  • prompt: str - Style description (required)
  • data: FileInput - Input image (required)
  • seed: int - Random seed
  • resolution: str - Output resolution
  • enhance_prompt: bool - Auto-enhance prompt
  • data: FileInput - Input image (required)
  • trajectory: List[MotionTrajectoryInput] - Motion path with frame, x, y (required)
  • seed: int - Random seed
  • resolution: str - Output resolution (default: “720p”)

​
Next Steps

Realtime API

Learn how to build realtime video applications

Examples

See complete example applications