Video Editing

Apply edits to video files: trim, crop, overlay, speed changes, text, audio mixing, and more.

POST/api/v1/video/edit

Request Body

Parameter	Type	Required	Description
operation	string	Yes	The editing operation to perform (see operations below)
params	object	No	Operation-specific parameters
mediaIds	string[]	No	Media IDs to operate on (number depends on operation)
audioMediaId	string	No	Audio media ID (used by editAudio and audioTrim)
promptText	string	No	Text content for textOverlay operation
captionSegments	array	No	Caption segments for textOverlay caption mode

Response

{
  "editorJobId": "ej_..."
}

Operations

trim

Trim a video to a specific time range. Requires 1 mediaId.

Parameter	Type	Required	Description
trimStartMs	number	Yes	Start time in milliseconds (min 0)
trimEndMs	number	Yes	End time in milliseconds (min 100). trimEndMs - trimStartMs must be >= 100

Example

{
  "operation": "trim",
  "mediaIds": ["media_abc"],
  "params": {
    "trimStartMs": 0,
    "trimEndMs": 5000
  }
}

crop

Crop a video with position, padding, and aspect ratio controls. Requires 1 mediaId.

Parameter	Type	Required	Description
position	string	No	Crop anchor: top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right
paddingTop	number	No	Top padding (0-50)
paddingRight	number	No	Right padding (0-50)
paddingBottom	number	No	Bottom padding (0-50)
paddingLeft	number	No	Left padding (0-50)
cropAxis	string	No	Axis to crop: `"width"` \| `"height"`
cropPercent	number	No	Crop percentage (10-100)
aspectRatio	string	No	16:9, 9:16, 1:1, 4:5, 21:9, custom (default 16:9)
customWidth	integer	No	Custom width (required when aspectRatio is custom)
customHeight	integer	No	Custom height (required when aspectRatio is custom)

Example

{
  "operation": "crop",
  "mediaIds": ["media_abc"],
  "params": {
    "position": "center",
    "aspectRatio": "9:16",
    "cropAxis": "width",
    "cropPercent": 80
  }
}

volume

Adjust video volume or mute. Requires 1 mediaId.

Parameter	Type	Required	Description
volume	number	No	Volume level (0-100, default 100)
muted	boolean	No	Mute the video (default false)

Example

{
  "operation": "volume",
  "mediaIds": ["media_abc"],
  "params": { "volume": 50 }
}

speed

Change video playback speed. Requires 1 mediaId.

Parameter	Type	Required	Description
speed	number	No	Playback speed multiplier (0.33-3, default 1)
preservePitch	boolean	No	Keep original audio pitch (default true)

Example

{
  "operation": "speed",
  "mediaIds": ["media_abc"],
  "params": { "speed": 2, "preservePitch": true }
}

textOverlay

Add text or captions on top of a video. Requires 1 mediaId and either promptText or captionSegments at the request body level.

Parameter	Type	Required	Description
mode	string	No	`"text"` \| `"caption"` (default text)
durationMode	string	No	`"full"` \| `"duration"`
startTime	string	No	Start time in MM:SS format (required if durationMode is duration)
endTime	string	No	End time in MM:SS format (required if durationMode is duration)
position	string	No	top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right
padding	number	No	Padding around text (0-50)
sizePercent	number	No	Text container size (10-100)
fontFamily	string	No	Inter, Montserrat, Bebas Neue, Oswald, Bungee Inline, League Spartan, Roboto, Poppins, Raleway, Anton, Darker Grotesque, TikTok Sans, TikTok Sans Condensed, TikTok Sans SemiCondensed, TikTok Sans SemiExpanded, TikTok Sans Expanded, TikTok Sans ExtraExpanded, Nohemi, Comic Cat, Gavency
fontSizeScale	number	No	Font size multiplier (0.3-3)
textColor	string	No	Hex color for the text (e.g. #FFFFFF)
strokeColor	string	No	Hex color for the text stroke
highlightColor	string	No	Hex color for the text highlight
strokeWidth	number	No	Stroke width (0-20)
showShadow	boolean	No	Show drop shadow behind text

Example

{
  "operation": "textOverlay",
  "mediaIds": ["media_abc"],
  "promptText": "Hello World!",
  "params": {
    "mode": "text",
    "durationMode": "full",
    "position": "bottom-center",
    "fontFamily": "Montserrat",
    "textColor": "#FFFFFF",
    "strokeColor": "#000000",
    "strokeWidth": 2
  }
}

editAudio

Mix an audio track into a video. Requires 1 mediaId and an optional audioMediaId.

Parameter	Type	Required	Description
videoVolume	number	No	Volume of the original video audio (0-100)
audioVolume	number	No	Volume of the added audio track (0-100)
audioStartMs	number	No	Start offset of the audio track in milliseconds (min 0)
audioEndMs	number	No	End offset of the audio track in milliseconds (min 0, optional)
audioOffsetMs	number	No	Offset where the audio starts in the video timeline (min 0)

Example

{
  "operation": "editAudio",
  "mediaIds": ["media_video"],
  "audioMediaId": "media_audio",
  "params": {
    "videoVolume": 30,
    "audioVolume": 80,
    "audioStartMs": 0,
    "audioOffsetMs": 2000
  }
}

extractAudio

Extract the audio track from a video. Requires 1 mediaId. No additional params. Returns an audio file.

Example

{
  "operation": "extractAudio",
  "mediaIds": ["media_abc"]
}

reverseVideo

Reverse the playback of a video. Requires 1 mediaId. No additional params.

Example

{
  "operation": "reverseVideo",
  "mediaIds": ["media_abc"]
}

extractFrame

Extract a single frame from a video as a JPEG image. Requires 1 mediaId.

Parameter	Type	Required	Description
timestampMs	integer	No	Absolute timestamp in milliseconds. Takes precedence over timestampPercent
timestampPercent	number	No	Relative position as a percentage (0-100)

Example

{
  "operation": "extractFrame",
  "mediaIds": ["media_abc"],
  "params": { "timestampMs": 3500 }
}

imageToVideo

Convert a static image into a video. Requires 1 mediaId (image).

Parameter	Type	Required	Description
durationMs	number	No	Duration in milliseconds (500-60000, default 5000)

Example

{
  "operation": "imageToVideo",
  "mediaIds": ["media_img"],
  "params": { "durationMs": 3000 }
}

overlay

Place one video or image on top of another. Requires 2 mediaIds (base + overlay).

Parameter	Type	Required	Description
position	string	No	top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right
padding	number	No	Padding around overlay (0-50)
resizeAxis	string	No	Axis to constrain: `"width"` \| `"height"`
resizePercent	number	No	Overlay size as percentage of base (10-100)
baseVideoVolume	number	No	Volume of the base video (0-100, default 0)
overlayVideoVolume	number	No	Volume of the overlay video (0-100, default 100)
overlayStartMs	number	No	When the overlay appears in the base timeline (ms)
overlayDurationMs	number	No	How long the overlay is visible (ms)

Example

{
  "operation": "overlay",
  "mediaIds": ["media_base", "media_overlay"],
  "params": {
    "position": "bottom-right",
    "resizeAxis": "width",
    "resizePercent": 30,
    "padding": 10
  }
}

splitScreen

Combine two videos side by side in a split-screen layout. Requires 2 mediaIds.

Parameter	Type	Required	Description
targetAspectRatio	string	No	`"16:9"` \| `"9:16"` (default 16:9)

Example

{
  "operation": "splitScreen",
  "mediaIds": ["media_top", "media_bottom"],
  "params": { "targetAspectRatio": "9:16" }
}

merge

Concatenate 2 to 5 videos sequentially. Requires 2-5 mediaIds. No additional params.

Example

{
  "operation": "merge",
  "mediaIds": ["media_a", "media_b", "media_c"]
}

splitScenes

Detect and split a video into individual scenes. Requires 1 mediaId.

Parameter	Type	Required	Description
threshold	number	No	Scene detection sensitivity (0.01-0.9, default 0.5)
minClipDuration	number	No	Minimum clip duration in seconds (0.1-5, default 0.5)
mode	string	No	`"split"` (output all clips) \| `"omit"` (remove detected scenes). Default split
outputSelection	string \| integer	No	`"first"`, `"last"`, or an integer index to pick a single clip (default 1)

Example

{
  "operation": "splitScenes",
  "mediaIds": ["media_abc"],
  "params": {
    "threshold": 0.3,
    "minClipDuration": 1,
    "mode": "split",
    "outputSelection": "first"
  }
}

motionDesign

Generate a motion graphics video from a text prompt using an AI model. Accepts 0-2 mediaIds as visual context.

Parameter	Type	Required	Description
prompt	string	Yes	Description of the motion design to generate
model	string	No	gemini-2.5-pro, claude-opus-4, claude-sonnet-4.5 (default claude-sonnet-4.5)
canvas	string	No	`"landscape"` \| `"portrait"` \| `"square"` (default landscape)
durationMs	number	No	Duration in milliseconds (1000-60000, default 5000)
includeMediaContext	boolean	No	Include attached media as visual context (default false)

Example

{
  "operation": "motionDesign",
  "mediaIds": [],
  "params": {
    "prompt": "Animated logo reveal with particles",
    "model": "claude-sonnet-4.5",
    "canvas": "landscape",
    "durationMs": 5000
  }
}