Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.platform.decart.ai/llms.txt

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

Transform and edit existing videos using text prompts, reference images, or both. Upload a video, describe the changes you want, and Lucy 2.1 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.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-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

​
Parameters

  • data (required) — Input video file to edit.
  • prompt (required) — Text description of the changes to apply. For Lucy 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).
You can drive edits with text, a visual reference, or a combination of both.

​
Video Requirements

  • Format: MP4 (H.264 or VP8 codec)
  • Aspect Ratio: 16:9 (landscape) or 9:16 (portrait)
  • Duration: Unlimited with Lucy 2.1. Previous-generation Lucy Clip supports clips up to 5 seconds.
  • File Size: Maximum 200MB
  • Output Resolution:
    • 720p: 720×1280 (portrait) or 1280×720 (landscape)
For complete API documentation including response formats and error codes, see the API Reference.

​
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.1 (Recommended) — our latest and most advanced editing model. Fastest speed, excellent quality, unlimited duration, supports prompt and optional reference image.
  • Lucy Clip (Previous generation) — older editing model. Limited to 5-second clips.
Lucy Clip is a previous-generation model. We recommend Lucy 2.1 (lucy-2.1) for all new video editing projects. It is faster, supports unlimited duration, and costs the same or less.

​
Model Comparison

ModelStatusQualitySpeedReference ImageDurationCostBest For
Lucy 2.1RecommendedExcellentFastest✅ SupportedUnlimited$0.04/secAll video editing use cases (latest)
Lucy ClipLegacyExcellentStandard✅ SupportedMax 5 sec$0.15/sec—

​
Prompting Guide

Lucy 2.1 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 typePrompt 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.1 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.
Reference images are supported with Lucy 2.1 (lucy-2.1) and the previous-generation Lucy Clip (lucy-clip).
With Lucy 2.1, you can use a reference image with an empty prompt — the model will transform the video to match the reference image directly: 
# 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...

# 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...

​
Endpoint and Full API Reference

​
Next steps

Now that you know the basics of video editing, you might want to check out one of these resources next.

Edit a video in the Platform

Try out video editing and other models in the interactive platform.

Full API reference

Check out all the options for video editing in the API reference.

Virtual Try-On

Dress people in videos with text prompts or garment reference images.