Editor tool reference
Find inputs for media, text, timeline, and search tools.
Use this reference after creating or reading a saved composition. Each tool runs through the same route:
Send this request body:
{
"tool": "addClipOverlay",
"input": {
"assetId": "<PROJECT_VIDEO_ASSET_UUID>",
"sourceStartMs": 0,
"sourceEndMs": 3000,
"startFrame": 0,
"row": 1
},
"expectedUpdatedAt": "<COMPOSITION_UPDATED_AT>"
}Read and Generate permissions are required. Tools that change a composition also require Write. Use an active paid plan and an Idempotency-Key. The response is 202 with a public job ID. Read that job at GET /jobs/{jobId}.
Fields in the Required column are required. Fields in the Optional column can be omitted. Times ending in Seconds are seconds. Times ending in Ms are milliseconds. Frames and overlay IDs are integers. The final state must pass the version 1 composition rules.
For video and image media selection, use exactly one of assetId (a project asset UUID) or stock: {"provider":"pexels","id":"<NUMERIC_PROVIDER_ID>"}. Stock IDs have 1–16 digits and cannot start with zero. Sovran resolves the provider source. Do not send media URLs, source paths, preparation fields, sourceAssetId, or source dimensions in tool input. changeOverlay can set layout dimensions within the version 1 limits.
Add or replace media
| Tool | Required input | Optional input and limits |
|---|---|---|
addClipOverlay | One video media selection. | placement: primary or broll; sourceStartMs ≥ 0; sourceEndMs ≥ 1 and greater than the start; startFrame; row. The range must fit the saved source. |
addImageOverlay | One image media selection. | Positive durationSeconds; startFrame; row. |
addSoundOverlay | assetId: a project music asset UUID. | startFrame; volume: 0–1. |
replaceClipMedia | overlayId; one video media selection. | None. The saved source supplies its duration. |
addVoiceoverWithCaptions | voiceoverId: a completed project voiceover UUID. | startFrame; volume: 0–1; includeCaptions: boolean. Sovran loads saved audio, script, timing, and SRT. |
Change text, captions, and speech
| Tool | Required input | Optional input and limits |
|---|---|---|
addTextOverlay | text. | fontSize, fontWeight, color, backgroundColor; textAlign: left, center, or right; durationSeconds; startFrame; row. External style references are rejected. |
addCaptionsToOverlay | overlayId; source: generate or srt. | captionId: a saved caption UUID, required for srt; language: at most 20 characters. The saved caption must belong to the overlay's source. |
cleanupSpeechOverlay | overlayId. | removeFillers and removeSilences: default true, at least one must be true; silenceThresholdMs: 300–2,000, default 650; paddingMs: 0–400, default 120. |
Arrange the timeline and canvas
| Tool | Required input | Optional input and limits |
|---|---|---|
changeOverlay | overlayId; changes: supported partial overlay fields. | Use version 1 fields such as content, from, durationInFrames, and styles. Media and preparation references are server-owned. |
deleteOverlay | overlayId. | None. This removes the overlay from the composition. |
setCanvasSettings | At least one of aspectRatio or backgroundColor. | Ratio: 16:9, 9:16, 1:1, or 4:5; background: a hex color. |
duplicateOverlay | overlayId. | None. |
splitOverlay | overlayId; positive splitAtSeconds. | The split time is measured from the overlay's start. |
moveOverlay | overlayId; at least one of startSeconds or row. | Both values are ≥ 0. |
reorderOverlays | overlayIds: at least two overlay IDs in the required order. | None. |
Trim, mix, and frame media
| Tool | Required input | Optional input and limits |
|---|---|---|
trimClip | overlayId; a positive trimStartSeconds or trimEndSeconds. | Both values are ≥ 0. |
setClipInOut | overlayId; inSeconds or outSeconds. | Both values are ≥ 0 and must keep a valid source range. |
setAudioMix | overlayId; at least one mix setting. | volume: 0–1; fadeInSeconds and fadeOutSeconds: ≥ 0; muted: boolean. Use a sound overlay. |
cropToAspect | overlayId; aspectRatio. | Ratio: 16:9, 9:16, 1:1, 4:5, 5:4, 4:3, 3:4, or 21:9. |
reframeClip | overlayId; at least one alignment. | horizontalAlign: left, center, or right; verticalAlign: top, center, or bottom. |
Search for media and captions
Use the same direct tool body. All search limit values are integers from 1 to 20. Searches return project resource IDs or stock selections. They do not return customer media URLs.
| Tool | Input |
|---|---|
searchAssets | Optional query, type (video or music), tags (exact tag strings), and limit (default 10). |
searchProjectVideos | Required nonempty query; optional limit (default 8). |
searchStockVideo | Required nonempty query; optional orientation (landscape, portrait, or square) and limit (default 10). |
searchStockImage | Required nonempty query; optional orientation and limit with the same values as stock video. |
searchVoiceovers | Optional query and limit (default 10). |
searchTextLibrary | Optional query, kind (overlay_text or voiceover_script), favoritesOnly, and limit (default 10). |
searchCaptions | Optional assetId, language, and limit (default 10). |
generateCaptions | overlayId or a project video assetId; optional language (at most 20 characters). This prepares captions. It does not add a caption overlay. |
Search saved videos:
{
"tool": "searchAssets",
"input": {
"type": "video",
"limit": 1
},
"expectedUpdatedAt": "<COMPOSITION_UPDATED_AT>"
}Use the returned asset UUID in addClipOverlay. For stock media, use the returned stock selection.
Add the selected image:
{
"tool": "addImageOverlay",
"input": {
"stock": {
"provider": "pexels",
"id": "<RETURNED_NUMERIC_ID>"
},
"durationSeconds": 3,
"startFrame": 0
},
"expectedUpdatedAt": "<COMPOSITION_UPDATED_AT>"
}Add a saved caption:
{
"tool": "addCaptionsToOverlay",
"input": {
"overlayId": 0,
"source": "srt",
"captionId": "<SAVED_CAPTION_UUID>"
},
"expectedUpdatedAt": "<COMPOSITION_UPDATED_AT>"
}See editor limits and recovery before you submit large requests.