Skip to main content
With the Decart API, you can transform and edit existing videos using text prompts. Simply upload a video and describe the changes you want to make, and LucyEdit will intelligently modify your video while preserving important motion and temporal consistency. LucyEdit excels at style transfers, object modifications, character replacements, and visual transformations. Our models maintain the core motion and structure of your original video while applying your desired edits with high precision.
Output video is limited to 5 seconds.

​
Quick start

Here’s a simple example using LucyEdit, our advanced video editing model. 
# Submit job
JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-pro-v2v \
  -H "X-API-KEY: $DECART_API_KEY" \
  -F "[email protected]" \
  -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.
  • reference_image (optional, LucyEdit only) — 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).

​
Video Requirements

  • Format: MP4 (H.264 or VP8 codec)
  • Aspect Ratio: 16:9 (landscape) or 9:16 (portrait)
  • Duration: Up to 5 seconds
  • File Size: Maximum 300MB
  • 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:
  • LucyEdit — our flagship editing model for precise, high-quality video transformations.
  • LucyEdit-Fast — a fast model optimized for quick edits and rapid iteration.

​
Model Comparison

ModelQualitySpeedReference ImageBest For
LucyEditExcellentStandard✅ SupportedProduction quality, complex edits
LucyEdit-FastVery GoodFast❌ Not supportedQuick edits, rapid iteration

​
Prompt Engineering for Video Edits

Video editing requires different prompt strategies than generation. Your prompts should clearly describe what to change while implicitly indicating what to preserve. LucyEdit interprets your instructions in the context of the existing video and maintains temporal consistency. Effective editing prompts are specific about changes (what to modify), clear about scope (which elements to transform), and descriptive about the target result. Unlike generation, you don’t need to describe the entire scene—focus only on what needs to change. LucyEdit excels at motion preservation, temporal consistency, and prompt adherence. Pro tip: Detailed prompts (20–40 words) describing style, appearance, and context produce significantly better results than short instructions.

​
Supported Edit Types

​
✅ Best Performance

​
1. Clothing & Costume Changes

LucyEdit excels at swapping outfits while preserving motion and identity throughout the video.
  • Example: “Change the casual outfit to a formal black tuxedo with bow tie”
  • Example: “Replace the modern clothes with medieval knight armor”

​
2. Character/Object Replacement

Strong results when transforming objects or characters while maintaining original motion patterns.
  • Example: “Replace the car with a futuristic hoverbike, metallic finish”
  • Example: “Transform the dog into a tiger with striped orange fur”

​
3. Style Transfer

Reliable for applying consistent visual styles across all frames.
  • Example: “Transform to anime style with vibrant colors and cel shading”
  • Example: “Apply film noir aesthetic with high contrast black and white”

​
⚠️ Mixed Reliability

​
4. Background Replacement

Works well but may affect foreground elements. Best with clear subject-background separation.
  • Example: “Change the city street to a tropical beach with palm trees”
  • Tip: Specify what should remain unchanged for better results

​
5. Weather & Atmosphere

Can add environmental effects but intensity may vary across frames.
  • Example: “Add heavy rain and storm clouds with lightning”
  • Example: “Make it a foggy morning with soft diffused lighting”

​
6. Color Grading

Sometimes subtle, sometimes dramatic. Works best with specific descriptions.
  • Example: “Apply warm sunset color grade with orange and pink tones”
  • Tip: Specify exact moods and color palettes for consistency

​
Additional Optimization Tips

  • Motion preservation: The model excels at maintaining original movement patterns
  • Detail improves results: Include style, materials, colors, and textures in your prompts
  • Batch similar edits: Process videos with similar edits together for more consistent results
Bottom line: LucyEdit performs best with detailed prompts that clearly describe the desired changes. Focus on clothing swaps, character replacements, and style transfers for the most reliable results.

​
Using Reference Images

For more precise edits, LucyEdit 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 only supported with the LucyEdit model (lucy-pro-v2v), not LucyEdit-Fast.
# Submit job with reference image
JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-pro-v2v \
  -H "X-API-KEY: $DECART_API_KEY" \
  -F "[email protected]" \
  -F "prompt=Add these sunglasses to her face" \
  -F "[email protected]" | 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.

Video Generation

Learn how to generate new videos from scratch with Lucy-Pro.