Tool reference

Parameters

shareIdstringrequired

Share ID or full URL (e.g., "abc123" or "https://app.com/share/abc123/mcp")

Parameters

rollType"aroll" | "broll"required

The CORRECT role: "aroll" = interview/spoken footage (gets a transcript), "broll" = cutaway/overlay footage.

shareIdstringrequired

Share ID

mediaIdsstring[]optional

Multiple sources to reclassify to the same rollType in one call. Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

sourceIdstringoptional

Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide. Single source.

Parameters

shareIdstringrequired

Share ID

sourceIdsstring[]required

The source(s) to remove from the project. Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide. Duplicates share a filename, so a filename alone is ambiguous for exactly the case this tool exists for — use the 1-based list_sources index or the exact source id.

confirmbooleanoptional

Pass true ONLY when re-issuing the identical call after reading the plan back to the user, and only together with the `planId` that plan returned. Without both, the call returns the plan again and removes nothing.

planIdstringoptional

The `planId` from the plan you are confirming. It is derived from this share and this exact set of sources, so it stops a confirmation from applying to a list that changed after the plan was shown.

reasonstringoptional

Optional short reason for the audit record, e.g. 'duplicate import'. Do not put personal details in it.

Parameters

shareIdstringrequired

Share ID

cursorstringoptional

action="read" only: page.nextCursor from the previous page, passed exactly, with the same sourceIds and fields. Omit for the first page. Keep calling until page.complete is true.

fields"technical" | "sourceResolution" | "original" | "multicam" | "descriptive" | "logFootage" | …[]optional

action="read" only: the blocks to return per source (sourceId and fileName always come back). Omit for everything. For a list or CSV of many sources — names, labels, a shot log, a rename sheet — pass ["descriptive"]: about 180 bytes a source instead of about 2 KB, so hundreds of sources fit in one page.

fileNamestring | string[]optional

action="read" only: return only the sources whose file name matches — a prefix ("IMG_45"), part of a name ("interview"), or a glob ("A0*_C01?.mov"); case is ignored; pass a list for several names. The reply says how many sources each pattern matched. Use it whenever the user names files by part of their name, above all on a large project.

limitintegeroptional

action="read" only: most sources in one page (default and max 500). A page also stops at a size budget, so read page.nextCursor rather than assuming you got them all.

sourceIdsstring[]optional

action="read" only: limit to these sources (default: all sources). Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

Parameters

shareIdstringrequired

Share ID

countintegeroptional

mode="clip": how many evenly-spaced frames to return (default 6, max 12). Need the whole clip? Use mode="scan". Need a closer look at part of it? Make further calls with explicit, narrower startTime/endTime windows instead of raising the count. mode="overview": frames in the row (default 6, max 8; a larger count is served as 8).

editContactSheetintegeroptional

Contact sheet of the saved edit named in editName: how many frames to sample evenly across the whole edit (2-12, default 9). Returns one grid image.

editNamestringoptional

editSegmentIndicesinteger[]optional

endTimenumberoptional

mode="clip": window end in seconds (default source duration; clamped to sourceDurationSec).

maxImagesintegeroptional

mode="segments": max thumbnails to return (default 4, max 8).

maxSheetsintegeroptional

mode="scan": sprite sheets per call (default and max 10 — the whole strip when it fits, else a page; each 5×5 sheet is 25 frames).

mode"clip" | "segments" | "scan" | "overview"optional

How to pick frames. DEFAULT 'clip' = evenly-spaced frames across a clip window; works on ANY source with a video, NO transcript required (b-roll, montages, not-yet-transcribed footage). 'overview' = ONE small low-resolution row of frames spread across the WHOLE clip, several times cheaper than any other mode — the first pass when you must look at every clip; pass sourceIds to cover many clips in one call. 'scan' = the WHOLE clip: every sheet of the frame strip extracted at import, in time order, paged with sheetOffset — the way to search footage visually. 'segments' = frames for specific transcript segments (requires a transcribed source); request it explicitly.

motionGraphicIdstringoptional

sectionsobject[]optional

mode="segments": time ranges to render (alternative to segmentIndices).

segmentIndicesinteger[]optional

mode="segments": segment indices to render (from get_transcript).

sheetOffsetintegeroptional

mode="scan": 0-based index of the first sprite sheet to return (default 0 = the start of the clip). Pass the previous answer's nextSheetOffset to read the next page.

sourceIdstringoptional

ONE source to read. Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide. For mode="clip", any source with a video file. To read SEVERAL clips in one call, pass sourceIds instead.

sourceIdsstring[]optional

SEVERAL sources to read in ONE call, in this order — the way to look at many clips without paying a round trip each. Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide. Every other argument (mode, window, count) applies to each clip in the list, and each clip costs exactly what it would cost in a call of its own. At most 32 per call, read in batches of 8; a longer list is refused and nothing is read.

startTimenumberoptional

mode="clip": window start in seconds (default 0). Must be before the end of the source — a start ≥ sourceDurationSec is an error.

Parameters

projectIdstringoptional

The import project ID, not a share ID. Omit to cancel your one running import.

Parameters

shareIdstringrequired

Share ID

sourcestringrequired

The source to transcribe: Source ID from list_sources (preferred), exact file name, or list index. For several sources use transcribe_sources instead.

confirmbooleanoptional

false/omitted = quote the exact charge, change nothing. true = the user approved the quoted charge — charge and start.

languagestringoptional

Force this STT language for THIS run (ISO code like "es", "fr-CA", "pt-BR"; "auto" = detect, the default). Overrides the project's transcription-language setting for the run. An unsupported code fails with the full valid list.

mode"missing" | "replace"optional

"missing" (default) = transcribe a source that has NO transcript. "replace" = re-run STT for a source that already has one and swap it in place.

setProjectDefaultbooleanoptional

With `language`: also save it as the project's transcription-language default for future transcriptions (default false — the override applies to this run only).

Parameters

shareIdstringrequired

Share ID

sourcesstring[]required

The sources to transcribe (1-60 per call): Source IDs from list_sources (preferred), exact file names, or list indexes. Sources that already have a transcript are left out, so passing every source in the project is fine.

confirmbooleanoptional

false/omitted = quote the exact total for the batch, change nothing. true = the user approved the quoted total — charge once and start every transcription.

languagestringoptional

Force this STT language for every source in the batch (ISO code like "es", "fr-CA", "pt-BR"; "auto" = detect, the default). This batch only; it does not change the project default.

Parameters

shareIdstringrequired

Share ID (e.g., "abc123")

endTimenumberoptional

Only return segments overlapping at/before this second. Single-source only.

includeWordsbooleanoptional

Attach per-word timings (`words`: [{text, start, end}], source-media seconds) to each returned segment — the exact cut points for word/phrase-boundary trims. Single-source only, and only honored on pages of ≤25 segments: narrow with startTime/endTime (or limit) to the moment you are timing.

limitintegeroptional

Max segments to return (default 200, max 500). Single-source only.

offsetintegeroptional

Segment index to start from (default 0). Single-source only.

sourceIdstringoptional

Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide. Omit to fetch ALL sources at once.

startTimenumberoptional

Only return segments overlapping at/after this second. Single-source only.

Parameters

shareIdstringrequired

Share ID

sourceIdstringrequired

Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

correctionsobject[]optional

The corrections to apply (up to 20 per call).

revertAllbooleanoptional

Remove ALL stored corrections for this source instead of adding new ones.

Parameters

shareIdstringrequired

Share ID

endTimenumberoptional

Only segments overlapping at/before this second.

kind"transcript" | "sound"optional

What to search. "transcript" (the default) searches spoken words. "sound" searches what the analyser HEARD and OBSERVED — b-roll sound (music, ambience, sound effects, silence) and interview moments (a voice breaking, a long pause, wiping an eye, looking away) — matching the kind, the observed label and the `readsAs` reading, and returns {sourceId, start, end} rows on each source's own timeline. It covers every roll, but only footage that HAS been analysed: sources without sound events or moments return nothing, which means "not analysed", never "silent" and never "nothing happened".

limitintegeroptional

Max matches to return (default 50, max 200).

querystringoptional

Case-insensitive text to search for in segment content. A PASTED LINE (four words or more) that no single segment holds is matched tolerantly — across sentences, through punctuation, filler words, contractions, numbers, speaker labels, timecodes and small transcription slips — and `pastedLine` gives each place a score and what differed, or, when the line is not there, its nearest places. Pass the line as the user gave it, once; never re-search it in fragments or rewordings.

sourceIdstringoptional

Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide. OMIT to search every transcribed source in the project (A-roll, plus any b-roll with a transcript).

speakerstringoptional

Only segments spoken by this person. Matches the display name, the diarization label, or one word of a full name ("Jill" matches "Jill Okafor"). An unrecognized name fails with the list of real speakers.

startTimenumberoptional

Only segments overlapping at/after this second.

Parameters

itemsobject[]required

Labels to apply.

shareIdstringrequired

Share ID

target"source" | "multicam_group"required

What to label: individual source files ("source") or multicam groups ("multicam_group").

removebooleanoptional

If true, remove these labels instead of adding them.

Parameters

action"bookmark" | "label"required

Whether to bookmark the segments or apply a custom label (requires "label").

shareIdstringrequired

Share ID

sourceIdstringrequired

Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

labelstringoptional

The label to add or remove (required when action="label").

removebooleanoptional

If true, remove the bookmark/label from the matched segments.

sectionsobject[]optional

Time ranges to tag (alternative to segmentIndices).

segmentIndicesinteger[]optional

Segment indices to tag (from get_transcript).

Parameters

shareIdstringrequired

Share ID

Parameters

shareIdstringrequired

Share ID

Parameters

shareIdstringrequired

Share ID

confirmbooleanoptional

false/omitted = state the price, change nothing and charge nothing. true = the user agreed to the rate — start the analysis. Ignored when runId is given (a progress read never starts a run).

includeArollbooleanoptional

Analyse the interview (A-roll) footage. Default true — this is the footage the feature is for. Set false only when the user explicitly wants the b-roll alone.

includeBrollbooleanoptional

Analyse the b-roll as well. Default true. Set false to spend the run on the interviews alone, which is cheaper because less footage is analysed.

runIdstringoptional

The runId a previous call returned. Pass it to READ PROGRESS; it never starts a second analysis and never charges twice. Omit it to quote or to start.

topicsstring[]optional

WHAT TO LOOK FOR, in the user's own words — the shots or moments they are hunting, e.g. ["music drifting out from a roadside diner", "hesitation before answering"]. This is the lens that turns a general description pass into a SEARCH. At most 50 entries of 100 characters each; a list outside that is refused with a sentence naming the entry, so send what the user said and relay the refusal rather than trimming it yourself. Guidance for THIS RUN only; nothing is saved on the project. Omit it to run the general pass. Never invent topics.

Parameters

editNamestringrequired

Edit name to inspect

shareIdstringrequired

Share ID

Parameters

editNamestringrequired

Edit name

shareIdstringrequired

Share ID

assignmentsobject[]optional

Per-segment angle choices (optional when only setting mainCameraId / mainAudioId)

groupstringoptional

Which multicam group this call applies to — a groupId or groupName from get_multicam_angles. Optional (and unnecessary) when the edit uses a single group. REQUIRED alongside mainCameraId / mainAudioId when the edit spans several groups, since those are per-group settings. When given, every assignment must target a segment in that group.

mainAudioIdstringoptional

Set the group's MAIN AUDIO (project-wide, per group): a mediaId, role, or name from get_multicam_angles, belonging to `group` (or to the edit's only group). Every cut of the group takes its program audio from it (player, MP4 render, NLE exports — where it is the single declared audio angle). Pass 'clear' to return to the default (the group's reference audio). When the group carries a microphone mix, the default is that mix, not the reference audio. Pass 'mix' to play EVERY separate microphone recording of a group the user made by hand together, as one level-matched track — use it when the user asks to join, combine or mix the microphones or to hear both mics. It clears any single member named as the main audio, the mix is ready a few minutes later in the player and the MP4 export (NLE exports keep each microphone on its own track), and it is free. Do not call it again while it is being mixed. WHAT IS MIXED: two or more AUDIO-ONLY files (separate recorders) are mixed on their own. A group with fewer than two of those mixes the sound of EVERY file in the group that has sound, VIDEO files included — for example a podcast with one video file per person, each carrying that person's own mic: both mics then play together. A file with no sound is left out. Every camera's sound joins that sum, a wide camera's room sound too; to take ONE camera's sound under a line instead, use set_segment_audio `audioFrom` per segment.

mainCameraIdstringoptional

Set the group's MAIN CAMERA (project-wide, per group — not per segment): a mediaId, role, or name from get_multicam_angles, belonging to `group` (or to the edit's only group). Every unassigned segment of the group plays it (player, MP4 render, NLE exports), and it is the default active angle on exported mc-clips and the first mc-angle. Pass 'clear' to return to the reference angle.

Parameters

shareIdstringrequired

Share ID

anglesobject[]optional

Every camera other than the reference, with offsets.

clearbooleanoptional

true = remove a user-created group instead.

groupstringoptional

With clear: the user-created group id to remove.

method"audio" | "picture"optional

How to sync the cameras. 'audio' (default) matches what the cameras hear. 'picture' is opt-in: it matches a moment every camera can SEE (two claps or flashes a few seconds apart, in view of every camera, work best). It may refuse a camera, its result is a proposal the user reviews before anything changes, and it costs credits by footage minutes.

namestringoptional

Short name for the group (e.g. "interview"). Same name = same group (re-calls replace it). Defaults to the reference filename.

offsetSource"measured" | "user_supplied"optional

REQUIRED whenever you pass `angles` (per-angle `offsetSource` overrides it). "measured" = you read the offset off matching transcript timestamps or a moment both cameras captured. "user_supplied" = the human gave or confirmed this exact number. There is no third option: if neither is honestly true, do not call this tool — ask the user for the offset, or run resync_all_multicam to measure it.

referencestringoptional

The reference camera (source id or filename from list_sources) — the timing anchor, offset 0. Prefer the camera that covers the whole take.

Parameters

groupstringrequired

The group to dissolve: a multicam group id from list_sources, or any source in the group (id, filename, or list index).

shareIdstringrequired

Share ID

confirmbooleanoptional

Required (true) only when saved edits reference the group — confirm with the user first.

Parameters

shareIdstringrequired

Share ID

sourceIdstringrequired

The newly-added clip to add (source id from list_sources)

targetGroupstringrequired

Existing group to add it to: a multicam group id, or a source id/filename already in that group

method"audio" | "picture"optional

How to sync the cameras. 'audio' (default) matches what the cameras hear. 'picture' is opt-in: it matches a moment every camera can SEE (two claps or flashes a few seconds apart, in view of every camera, work best). It may refuse a camera, its result is a proposal the user reviews before anything changes, and it costs credits by footage minutes.

Parameters

shareIdstringrequired

Share ID

cameraChoicesobject[]optional

Only after a commit was HELD (held=true): the user's answer for each held camera. "timecode" = place it by its timecode, "audio" = place it by the audio match, "drop" = leave it out (a camera already in a group stays where it is). Never choose for the user.

commitbooleanoptional

true = apply the previously-proposed grouping (requires proposalId). Omit/false = analyze and propose (charges, changes nothing).

method"audio" | "picture"optional

How to sync the cameras. 'audio' (default) matches what the cameras hear. 'picture' is opt-in: it matches a moment every camera can SEE (two claps or flashes a few seconds apart, in view of every camera, work best). It may refuse a camera, its result is a proposal the user reviews before anything changes, and it costs credits by footage minutes.

onContradiction"apply_measured" | "keep_applied"optional

Only needed if a commit was refused with contradiction=true (a camera is already synced at an offset that materially disagrees with what the sync run measured). Show the user the reported numbers and let THEM choose: "apply_measured" (recommended — replace the applied offsets with the measured ones) or "keep_applied" (leave those cameras exactly as they are and commit the rest). Never pick one on the user's behalf.

proposalIdstringoptional

With commit=true: the proposalId returned by the propose step to apply.

Parameters

shareIdstringrequired

Share ID

runIdstringoptional

The runId returned by resync_all_multicam. Omit to report the most recent camera sync for this project.

Parameters

shareIdstringrequired

Share ID

sourceIdstringrequired

Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

confirmbooleanoptional

Pass true ONLY when re-issuing an identical call after the tool returned a needs_confirmation preview for a large removal, and only after verifying the preview matches what the user asked to remove.

nearstringoptional

Surrounding text to disambiguate which occurrence (the unique words around the target).

occurrencestring | integeroptional

"all" to cut every occurrence (good for filler), or the 1-based index of one specific occurrence.

phrasestringoptional

The exact words to cut, as they appear in the transcript (e.g. "um", "you know", "I, I think").

restorebooleanoptional

If true, reverse (un-delete / un-cut) whatever the same target specifies.

sectionsobject[]optional

Time ranges (SOURCE-media seconds). Whole-segment coverage deletes the segment; a partial range cuts just those words.

segmentIdstringoptional

Restrict the phrase search to a single segment id.

segmentIdsstring[]optional

PREFERRED whole-segment targeting: exact segment ids (the `segmentId` field from get_transcript / find_transcript_segments for THIS source). Unknown ids are a hard error.

segmentIndicesinteger[]optional

0-based SOURCE-transcript indices to delete wholesale (from get_transcript for this source, NEVER from get_edit). Out-of-range indices are a hard error. Prefer segmentIds.

Parameters

editNamestringrequired

The edit these orientations apply to (from list_edits / get_edit). Stored per-edit; only this edit changes.

shareIdstringrequired

Share ID

clearbooleanoptional

If true, return the given segments to their untransformed orientation instead of setting one.

overlaysobject[]optional

segmentsobject[]optional

Parameters

editNamestringrequired

The edit these regions apply to (from list_edits / get_edit). Regions are stored per-edit and only affect this edit.

segmentIndexintegerrequired

The segment's 0-based `index` from get_edit(format="segments").

shareIdstringrequired

Share ID

clearbooleanoptional

If true, remove every region on this segment. `regions` is ignored.

regionsobject[]optional

The regions to set. Required unless `clear` is true.

replacebooleanoptional

If true, the regions given REPLACE every region already on this segment instead of adding to them.

Parameters

editNamestringrequired

Edit to modify (from list_edits).

shareIdstringrequired

Share ID

cutInSecnumberoptional

MID-SEGMENT CUT: start of the range to remove, in SOURCE-media seconds (inside the segment's startTime/endTime from get_edit format="segments"). Requires cutOutSec; not combinable with extendHeadSec/extendTailSec.

cutOutSecnumberoptional

MID-SEGMENT CUT: end of the range to remove, in SOURCE-media seconds (must be greater than cutInSec).

cutsobject[]optional

Up to 100 {index, cutInSec, cutOutSec} mid-segment cuts in one call (silences, gaps). Send alone.

extendHeadSecnumberoptional

Seconds to extend the head EARLIER into the source (negative tightens). E.g. 0.5 starts the clip half a second sooner.

extendTailSecnumberoptional

Seconds to extend the tail LATER into the source (negative tightens).

indexintegeroptional

Segment index from get_edit(format="segments").

restoreCutbooleanoptional

RESTORE A CUT: with cutInSec + cutOutSec, put that range BACK into the segment instead of cutting it — the part of its removedRanges inside the range plays again. Not combinable with extendHeadSec/extendTailSec.

Parameters

editNamestringrequired

Edit to modify (from list_edits).

shareIdstringrequired

Share ID

confirmbooleanoptional

Pass true ONLY when re-issuing an identical call after the tool returned a needs_confirmation preview for a large removal, and only after verifying the preview matches what the user asked to remove.

expectedobject[]optional

What you expect each target to be. Required for every segmentIndices entry. A mismatch refuses the whole call and lists the current segments.

segmentIdsstring[]optional

PREFERRED. Edit-segment ids to remove — the `segmentId` values from get_edit(format="segments") for this edit. Stable across reorders and earlier removals. Unknown ids are a hard error.

segmentIndicesinteger[]optional

0-based EDIT-segment positions to remove — the `index` values from get_edit(format="segments") for THIS edit, NEVER from get_transcript. Each one needs a matching `expected` entry; prefer segmentIds.

Parameters

editNamestringrequired

Edit to modify (from list_edits).

shareIdstringrequired

Share ID

afterSegmentIdstringoptional

Destination: put the moved segment(s) immediately AFTER this segment id.

beforeSegmentIdstringoptional

Destination: put the moved segment(s) immediately BEFORE this segment id.

segmentIdsstring[]optional

Edit-segment ids to move — the `segmentId` values from get_edit(format="segments") for this edit. PREFERRED over segmentIndices: ids do not shift when the edit changes. Unknown ids are a hard error.

segmentIndicesinteger[]optional

0-based EDIT-segment indices to move — the `index` values from get_edit(format="segments") for THIS edit. Resolved against the edit as it stands at call time; prefer segmentIds, which do not shift. Out-of-range indices are a hard error.

sortBy"source_time"optional

Reorder the WHOLE edit in one call. "source_time" = recording order: sources by recording time, then each clip by its in-point. Pass with editName only — no segmentIds, segmentIndices or destination.

swapWithIndexintegeroptional

Destination: exchange the one named segment with the segment at this index. Requires exactly one segment to move.

swapWithSegmentIdstringoptional

Destination: exchange the one named segment with this segment id. Requires exactly one segment to move.

toIndexintegeroptional

Destination: the position the FIRST moved segment occupies in the FINAL order. 0 puts the block at the start of the edit.

Parameters

editNamestringrequired

Edit to modify (from list_edits).

shareIdstringrequired

Share ID

atSecnumberoptional

Where to cut, in seconds on the EDIT timeline. Give this or timecode, not both.

cutsobject[]optional

Several cuts in one call, instead of atSec/timecode/segmentId at the top level. Each item gives exactly one of atSec or timecode. All or nothing.

segmentIdstringoptional

Optional: the segment the time must fall in (segmentId from get_edit(format="segments")). The call is refused if the time is in a different segment.

timecodestringoptional

Where to cut, as HH:MM:SS:FF (frames at the edit rate), HH:MM:SS or MM:SS on the EDIT timeline. Give this or atSec, not both.

Parameters

editNamestringrequired

Edit to modify (from list_edits).

segmentIdsstring[]required

Ids of the deleted segments to restore — the `segmentId` values get_edit(format="segments") shows with `deleted: true` for this edit.

shareIdstringrequired

Share ID

toIndexintegeroptional

Optional destination: the position the FIRST restored segment occupies in the FINAL order. 0 puts it at the start of the edit. Omit to restore in place.

Parameters

editNamestringrequired

Edit to modify (from list_edits).

shareIdstringrequired

Share ID

afterIndexintegeroptional

Index (from get_edit format="segments") of the segment the pause follows. For multiple pauses use afterIndices instead.

afterIndicesinteger[]optional

Batch form (PREFERRED for ranges): indices of ALL segments whose following pause should be included, in one call. All indices refer to the ORIGINAL get_edit segment order — do not re-fetch between items.

Parameters

shareIdstringrequired

Share ID

analysisIdstringoptional

Poll mode: fetch the status/result of a previously started analysis. Must be the EXACT analysisId string the start call returned (format "an-<uuid>") — never a placeholder, template, or invented value.

editNamestringoptional

Edit to analyze (from list_edits). Required to start.

feedback_as_commentsbooleanoptional

Post the feedback as timestamped Eddie comments on the edit timeline instead of returning prose. Use when the user asks for feedback/notes/a review of the edit.

questionstringoptional

Optional specific question to focus the feedback on (e.g. "does the opening hook work?").

Parameters

editNamestringrequired

Edit to lay out

shareIdstringrequired

Share ID

brollFit"fill" | "fit" | "blur"optional

How b-roll cutaways sit on this canvas. 'fill' (default) scales each cutaway up to cover the canvas and crops what spills over. 'fit' scales it down to show the WHOLE frame, letterboxed or pillarboxed with black bars, nothing cropped — e.g. 3:2 footage on a 4:3 canvas. 'blur' is 'fit' with a blurred background of the same shot in place of the black bars. A b-roll clip with its own crop_segments rect keeps that framing. Applies to the player, the MP4 export and the desktop render ('blur' is 'fit' there). Stored with the layout, so pass it again on each layout_edit call.

canvasobjectoptional

Canvas size/aspect. Required unless clear=true. Preset or explicit pixel dimensions.

clearbooleanoptional

Remove the layout instead of setting one.

layersobject[]optional

Video layers (the edit-level default). At most one V1 and one V2 entry. Omit for a bare canvas change.

segmentOverridesobject[]optional

Per-segment layer overrides — e.g. full-frame whoever is speaking on their segments, split-screen everywhere else. Segments not listed use the edit-level layers. Replaces ALL previous overrides each call.

speakerSidesobjectoptional

Vertical canvas only. Who sits on which side of a wide two-person shot, by speaker (the label or name get_edit shows), e.g. {"Speaker 1":"left","Speaker 2":"right"}. Only needed when the response's `speakerFraming` says a speaker's side could not be told; look at one frame, then send it once for the whole edit.

spineFit"fill" | "fit" | "blur"optional

The main (A-roll) clip when its shape does not match the canvas. 'fill' (default) crops it to cover (a vertical clip in a 16:9 edit is zoomed about 3x). 'fit' shows it whole with black bars; 'blur' shows it whole over a blurred background of the same shot. A crop_segments rect or V1 crop keeps its framing. Pass again on each call.

splitobjectoptional

SPLIT SCREEN preset: two angles of ONE multicam group on screen at once. The server computes each panel and each face crop; do not pass `layers` or `segmentOverrides` with it. `canvas` is optional with it: omitted = the edit's own canvas.

Parameters

editNamestringrequired

Unique name for this edit sequence (1-8 words, up to 80 characters). Letters and digits of ANY script are accepted, including accents and combining marks — pass the name the user asked for, in their own language. Emoji, punctuation and control characters are removed. MUST be different from all prior edit names in this share.

shareIdstringrequired

Share ID

soundbitesobject[]required

allowContiguousCutsbooleanoptional

Off by default: adjacent clips of the SAME source that follow each other (gap of 1.5s or less, same speaker/angle, no removed speech between) are merged into ONE continuous clip, so a run of sentences from one take does not play as rapid jump cuts; the result reports `mergedContiguous`. Set true ONLY when the user explicitly wants every sentence as its own cut (a jump-cut style). An explicit `tight` pacing merges only pieces that are effectively touching (0.3s).

allowDuplicatesbooleanoptional

Set true ONLY when the user deliberately wants the SAME footage placed more than once in this cut (a shot reprised at the end, a deliberate callback). It turns off the repeated-footage guard for this call. Leave it off for ordinary builds — the guard is what stops several soundbites that landed on one long transcript segment writing that segment over and over.

allowPartialFootagebooleanoptional

Set true ONLY when the USER has explicitly chosen to build now from partial footage. When this project still has sources importing and your frame reads for it came back empty, this build is otherwise held with a message saying how many sources are ready. Before setting it, tell the user what is still importing and that it will be missing from the cut — never set it silently, and never hide the hold from them.

allowWholeSourceClipsbooleanoptional

Set true ONLY when the user really wants a whole raw file (no transcript, not b-roll) placed in the cut. Otherwise a clip spanning the entire source of an untranscribed, non-b-roll source is refused as unwatched tail padding.

audioOnlyDeliverablebooleanoptional

Set true ONLY when the USER asked for a deliverable with no picture — an audio-only cut, a podcast audio version, a transcript stringout to listen to. A build whose runtime is mostly anchored to audio-only sources, with nothing covering it, renders as BLACK frames with sound and is REFUSED before anything is written unless this flag says the user asked for exactly that. Not needed in a project whose every source is audio-only — those build without it. Setting it to get past that refusal on a cut the user expects to SEE is the one use this flag must never have: repair the grouping the refusal names, or build the spine from a video source, instead.

briefstringoptional

The user's brief for this cut, verbatim ("30-45 minutes, focus on pricing, exclude the store tour, eliminate shaky footage"). The length it states becomes the target, floor and cap (an explicit targetDurationMinutes still wins) and is remembered on the edit for append_to_edit; the result carries durationTarget. The finished edit is checked against its inclusions and exclusions and the result carries briefCheck; unmet items are named in the message and must be fixed or told to the user before the cut is called done. Omit when the user gave no brief.

keepAudioOnlyTakesbooleanoptional

Set true ONLY when the user asked for lines the script marks On Camera to play from an audio-only recording with no picture of the presenter. Without it, a build that takes an On Camera line from an audio-only file while a take of the same words exists with picture is refused, and the refusal names those takes.

keepDefaultAnglebooleanoptional

Set true ONLY when the user wants ONE camera throughout a multicam cut. By default, segments cut from a multicam group are assigned to the speaker's own camera when the angles carry a camera_label (source_metadata), and the result reports what was assigned and what still plays the group default. With this flag nothing is assigned and no notice is raised; every segment plays the group main camera or reference angle.

minimumDurationMinutesnumberoptional

The FLOOR of the user's ask, in minutes — set when they stated a RANGE ("28-30 minutes" → 28, with targetDurationMinutes 29) or an explicit MINIMUM ("at least 20 minutes" → 20). A result materially under it (below ~90%) is flagged underDurationFloor and must not be narrated as done: lengthen it with additional real segments (append_to_edit), never padding. Has no effect without targetDurationMinutes, and never combined with targetIsMaximum.

pacing"tight" | "natural" | "breathy"optional

How much of the speaker's own pause to keep at each cut: `tight` keeps none (only for a fast, punchy cut the user asked for), `natural` keeps a short breath at sentence ends (the default), `breathy` keeps most of each pause (conversational). Pass it only when the user asked for a pacing in their own words. A social clip, a short or a reel is NOT a reason to pass `tight`: a clip cut from a conversation, an interview or a podcast keeps `natural` unless the user asked for fast or tight cuts. A restart or a stumble never keeps a breath under any setting.

preserveTimingbooleanoptional

Keep the SOURCE'S OWN TIMING: set true when the user wants this cut to stay on the source clock — an uncut camera on the base track that clips are then layered over at matching source timecode, or "keep the original timing". Every forward gap between consecutive clips of one source is then KEPT (a quiet one as a pause, one that holds words with its words) instead of closed, windows are cut at exactly the seconds given, and nothing is merged, floored or snapped, so along a run of one source timeline second t plays source second in + t. A `brief` that asks to match source timecode turns this on by itself; pass false to build a tightened cut from such a brief. Lay the layered clips with add_brolls syncToBase: true.

targetDurationMinutesnumberoptional

How long this cut is meant to run, in minutes. Use the length the user asked for ("make it about ten minutes" → 10) — or pass their words as `brief` and the length is read from it; if they gave none, use the target list_sources proposed (a footage-based default, never an override of a stated length) from the amount of footage. Omit ONLY when neither is available — the tool then falls back to the footage-derived target so the result is still measured against something. When the number came from the USER and the build lands materially under it (below ~80%), the result carries underDurationTarget and must not be reported as done at their number: extend it with real segments, or say plainly how long it runs and why the footage supports no more. Materially OVER it (above ~120%) carries overDurationTarget and is the same failure in the other direction: tighten the cut to their length, or say plainly how long it runs and why. CHECKED BEFORE THE BUILD TOO: when the project holds less than half this much usable footage, the call is refused without creating anything, and the refusal names the longest cut the footage can actually support — tell the user both numbers and let them choose before you build again.

targetIsMaximumbooleanoptional

Set true when targetDurationMinutes is a HARD CAP the user stated ("45 seconds max", "no longer than a minute", "keep it under 90s") rather than a goal. The length check then treats ANY overshoot as a failure: the result carries overDurationCap and must not be narrated as done until the edit is trimmed to fit. Has no effect without targetDurationMinutes.

visualConstraintobjectoptional

Pixel-side enforcement for a visible-person request. Rejects black, unsampled and non-matching clips; fails closed if no resolved clip can be visually verified.

voiceOverLedbooleanoptional

Set true when the USER asked for a cut LED BY NARRATION with picture over it — a voice-over documentary, a scripted read, a recorded narration the visuals follow. The spine then anchors the narration, which carries no picture of its own, so the build is written as an UNFINISHED cut: the result reports `pictureCoverage` (seconds with no picture, and the segment ranges to cover) and you must then lay picture over it with add_brolls, create_video_sequence, or find_stock_broll plus import_stock_broll, and tell the user how much has no picture yet. It is NOT a way past the black-timeline refusal for a cut that was supposed to show the speaker — that is a grouping repair. It is NOT audioOnlyDeliverable either: that one says the user wants no picture at all, and it wins if both are set. In a project that holds only audio the picture can come only from stock b-roll or motion graphics, and the result says so.

Parameters

durationSecondsnumberrequired

How long the break lasts, in seconds (0.1–600). Typical breathing room is 1–4s; a title/establishing beat 3–6s. A PAUSE IN A NARRATION OR VOICE-OVER READ: when the user asks for pauses and names no length, make each one 2.5–2.9s. A shorter gap in a continuous read sounds like the voice skipping, not pausing. Under music, the music stays down through a pause shorter than 3s and comes back up in a longer one.

editNamestringrequired

Name of the existing edit to add the break to.

shareIdstringrequired

Share ID

afterSegmentIdstringoptional

Insert the break AFTER the segment with this id. Alternative to afterSegmentIndex.

afterSegmentIndexintegeroptional

Insert the break AFTER the segment at this 0-based index (from get_edit / list). Omit with afterSegmentId/atStart.

atStartbooleanoptional

Insert the break at the very START of the edit.

colorstringoptional

Make the break a SOLID-COLOUR CARD instead of black: a hex code such as 00B140 (the leading hash is optional) or a name ('chroma green' or 'green screen' is hex 00B140, 'blue screen' is hex 0047BB, 'white', 'yellow', ...). Use it for a plain colour background — for example chroma-key green behind a title: add the break with the colour, then add the title over it. Free. It shows in the player and the MP4 export. NLE files show the card as black; their export notes say so. Omit for black.

slotFill"stock_or_project_footage" | "generated_broll" | "user_asked_empty"optional

What will fill this break, when the edit would otherwise play mostly black (over half its runtime with nothing over it). "stock_or_project_footage" = the project's own footage or free stock you will place on it; "generated_broll" = AI clips (generate_broll): the black is priced against the balance first, and the break is not added if the balance cannot pay for them; "user_asked_empty" = ONLY when the user asked for empty black slots. Omit for an ordinary pause.

titleCardAwaitingTextstring[]optional

Set when this break is the slot for a title or end card whose WORDS the brief does not give, e.g. ["brand name", "tagline"]. The slot is labelled "Title card: waiting for your brand name and tagline" for the user, and the composer offers a chip to give the text — instead of reading as one more black break. Ask for the words in your reply too. Place the card with add_graphic once you have them; that clears the label.

Parameters

editNamestringrequired

Unique name for this edit (1-8 words, up to 80 characters). Letters and digits of ANY script are accepted, including accents and combining marks — pass the name the user asked for, in their own language. Emoji and punctuation are removed. A name that collides with an existing edit is de-duplicated ("… 2") rather than refused — read `editName` back off the response and use that.

shareIdstringrequired

Share ID

allowPartialFootagebooleanoptional

Set true ONLY when the USER has explicitly chosen to build now from partial footage. When this project still has sources importing and your frame reads for it came back empty, this build is otherwise held with a message saying how many sources are ready. Before setting it, tell the user what is still importing and that it will be missing from the cut — never set it silently, and never hide the hold from them.

clipsobject[]optional

Ordered clips; they play back-to-back in this order. Use when the in/out points differ per clip; for a uniform batch use `sourceIds` instead. Exactly one of `clips` / `sourceIds` is required.

clipSecondsnumberoptional

Seconds per clip for the `sourceIds` form (default 4 — a still's own fixed length, so N photos is exactly N×4 seconds). Ignored when `clips` is used.

sourceIdsstring[]optional

Ordered source ids — one clip per id, each clipSeconds long and clamped to the real source length. Each clip opens on the first analysed good clip of its source when the b-roll analysis names one, and at 0.00s otherwise, so a multi-shot camera file starts on a real shot rather than on the head of the roll. Use INSTEAD of `clips` for a large uniform batch (e.g. every photo in the project, in order); pass `clips` when a clip needs a specific in-point. Produces exactly the same timeline as the equivalent `clips` array.

subclips"all" | "first"optional

With `sourceIds` only. "all" = one clip per ANALYSED b-roll window of each source, at the window's own in/out points, in time order (every shot of a multi-shot file); "first" = the earliest window of each source only. The analysed window is the usable span of the shot, so leave clipSeconds unset; if you pass it, it caps each window instead of fixing its length. A source with no analysed window gets one clip from 0.00s and is listed in `sourcesWithoutWindow`.

targetDurationMinutesnumberoptional

How long this montage is meant to run, in minutes. Use the length the user asked for ("about 60 seconds" is 1; "match this 36-second track" is 0.6). The response reports the finished duration against it: materially under (below ~80%) carries underDurationTarget and materially over (above ~120%) carries overDurationTarget, and neither may be narrated as done at the user's number. Reach a target by changing the clip lengths, NEVER by quietly using fewer sources.

Parameters

shareIdstringrequired

Share ID

Parameters

editNamestringrequired

Edit name from list_edits

shareIdstringrequired

Share ID or full URL

classes"wrong_person" | "empty_venue" | "repeat" | "content_mismatch"[]optional

format="broll_check" only: kinds of mistake to check. Omit (with no correction) to run every check.

correctionstringoptional

format="broll_check" only: the user's correction in their own words. The kinds of mistake it names are checked.

format"segments" | "timeline" | "export" | "broll_check"optional

'segments' = paginated edit segments; 'timeline' = visible-clip timeline; 'export' = flat frame-accurate multi-track NLE timeline; 'broll_check' = every b-roll placement checked for a kind of mistake.

includeMarkersbooleanoptional

format="export" only: include per-clip spoken text + speaker (for markers/clip names). Default false to keep the payload small — only set true when you actually need markers, since dumping a long transcript can bloat context and degrade FCPXML/OTIO accuracy.

likeSegmentIndexintegeroptional

format="broll_check" only: index of the segment whose b-roll the user corrected. Placements from the same file, or described in mostly the same words, are returned too.

limitintegeroptional

format="segments" only.

offsetintegeroptional

format="segments" only.

voiceoverText"preview" | "full"optional

Every format: 'full' returns each voice-over's whole script in `voiceovers` and `removedVoiceovers`; default 'preview' cuts it short.

Parameters

editNamestringrequired

Edit name to delete

shareIdstringrequired

Share ID

confirmbooleanoptional

Set true ONLY when the user has EXPLICITLY asked to delete this edit or rebuild it from scratch. A built edit cannot be deleted without this. If the user asked for a scoped change (remove captions, remove gaps, trim, drop a clip), leave this off and use the targeted tools instead.

confirmBatchbooleanoptional

Whole-batch confirmation, separate from `confirm`. A delete that is not the first of this run, or that would leave the project with no edits, returns a preview of every edit and its segment count instead of deleting. Read that preview as a BATCH, tell the user which edits go, then re-issue with confirmBatch:true. Pass it on every remaining delete in the run — the confirmation is given once, not per edit.

Parameters

shareIdstringrequired

Share ID

confirmbooleanoptional

Pass true ONLY when re-issuing the identical call after reviewing the preview diff, and only if the diff matches what the user wants reverted.

toRevisionintegeroptional

The revision to revert to — use the `baseRevision` echoed by the destructive call you are undoing. Defaults to the revision immediately before the current head (undoes the most recent write).

Parameters

shareIdstringrequired

Share ID or full URL

beforeintegeroptional

Page further back: return only versions OLDER than this revision. Pass the `nextBefore` from the previous page. Omit for the most recent versions. Ignored without editName.

compareFromintegeroptional

Compare two saved versions of editName: the OLDER revision (from this listing). The answer is what changed — segments added, removed, moved and trimmed, b-roll added, removed and moved, and music, titles and other treatments added, removed or changed. Requires editName.

compareTointegeroptional

With compareFrom: the NEWER revision to compare against. Omit it to compare against the edit as it is saved now.

editNamestringoptional

The edit to show history for — from list_edits, or the name the user remembers even if list_edits no longer shows it. Omit for a rollup of every edit the project has ever had.

limitintegeroptional

How many versions to return per page (default 10, max 50). Ignored without editName.

Parameters

editNamestringrequired

The edit whose version to restore — the ORIGINAL name, even if the edit is gone from the current state.

revisionintegerrequired

The revision to restore, from list_edit_versions. Must be a revision at which this edit actually existed.

shareIdstringrequired

Share ID or full URL

Parameters

editNamestringrequired

Current edit name

newNamestringrequired

New unique edit name. Letters and digits of any script are accepted, accents and combining marks included.

shareIdstringrequired

Share ID

Parameters

editNamestringrequired

Name of the existing edit to add B-rolls to

shareIdstringrequired

Share ID

clearbooleanoptional

If true, remove ALL existing B-roll placements from this edit. Alone it clears the B-roll track; with placements it rebuilds the track from only these placements.

confirmbooleanoptional

Approve the b-roll charge for this edit. The FIRST call that would place b-roll on an edit returns a price and writes NOTHING; tell the user the figure, then re-send the same call with confirm:true. Once an edit has been charged, later calls on that edit need no confirm: they bill only b-roll files the edit has not already paid for, and nothing at all when they reuse files it has. Inspect calls and removals never charge and never need it.

instructionsstringoptional

Optional editorial guidance for choosing B-rolls, e.g. match barber shop visuals to barber shop A-roll.

libraryOffsetintegeroptional

Index to start listing the B-roll library from on an inspect call. The library is listed a page at a time; when a page is truncated the response carries a "libraryPage" block with the totals and the nextOffset to pass here. Every id in the project is placeable, whichever page it appeared on.

placementsobject[]optional

B-roll placements chosen by the calling AI agent. Omit on the first call to inspect available B-roll options.

quoteOnlybooleanoptional

true = price this call and do NOTHING else: no b-roll is placed, removed or charged, on any edit (one already charged too). The reply is action "add_brolls_price" with the credits this exact call would bill now (0 when every file it draws on is already paid for). Send the same call again without quoteOnly (with confirm:true when the reply asks for it) to place it.

removeinteger[]optional

A-roll segment indices whose existing B-roll placements should be deleted. Use alone to just remove B-roll, or together with placements to delete and insert in one atomic call. Other segments are never shifted. A placement can be named by the index of the segment it was placed on, by the index it visibly plays at, or by the index its coverage row reports — all three reach it, whichever one your last read gave you. An index that reaches no placement is reported back in "unmatchedRemovalIndices", and a call that removes nothing at all fails instead of returning success: never tell the user a clip is gone without a removal count that says so.

removeOverlaysinteger[]optional

Existing cutaways to take off, each by its `overlayIndex` from get_edit(format="timeline"). Only those overlays come off; every other overlay, on the same segment or any other, is left exactly as it is. Use alone, or with placements in one atomic call.

replacebooleanoptional

If true, the existing B-roll each placement covers on its target A-roll segment is removed before the new placement is laid down — swap a cutaway in one atomic call; the segment's other cutaways are kept. Without it placements are additive and only fill whatever room the target segment has left.

subclipRunIdstringoptional

List the subclips of a SPECIFIC generate_broll_subclips run instead of the project's current one. Every run keeps its own clips permanently, but the project points at one run at a time, so a later run leaves an earlier run's clips unlisted until you name it here. generate_broll_subclips returns a runId when it completes; the inspect response also lists every run of this project under "subclipRuns" with its id and clip count. Use it when the user asks for the clips of an earlier run ("the run that found 60", "the first set"). Inspect only — it changes nothing, and the subclips of the named run are addressable for placement exactly like the current ones.

userAskedToRemovebooleanoptional

Set true ONLY when the user's own message asked for the b-roll that remove:[segmentIndex] or clear:true takes to go ("remove the b-roll from the intro", "start the b-roll over"). Without it, a call that would leave the edit with fewer overlays than it had, by more than the overlays it names, is refused with nothing written. Never set it to get past that refusal.

Parameters

shareIdstringrequired

Share ID

Parameters

guidancestringrequired

REQUIRED. The user's own words for what the subclips should be of — the rubric clips are selected BY. Never invent this; elicit it in conversation first. e.g. "wide establishing aerials with smooth movement, nothing with people in frame".

shareIdstringrequired

Share ID

confirmbooleanoptional

false/omitted = state the price, change nothing. true = the user agreed to the rates — charge and start.

maxPerSourceintegeroptional

Maximum subclips to cut per source (default 3). Raising it CAN raise the price: every clip produced carries a 10-credit minimum, so a scope that would otherwise be billed on its duration can end up billed on its clip count instead. Raise it when the user wants more coverage, not by default.

scopestring[]optional

Optional b-roll source ids to analyse (from list_sources / the b-roll library). Omit to analyse every b-roll source in the project. Ids that are not analysable b-roll are refused rather than silently skipped.

Parameters

shareIdstringrequired

Share ID

notLoggedCursorstringoptional

Optional. The `notLoggedNextCursor` from an earlier DONE reply: returns the next page of not-logged b-roll clips (sourceId, name, reason) instead of the full status. Omit for the normal status.

Parameters

editNamestringrequired

The edit these crops apply to (from list_edits / get_edit). Crops are stored per-edit and only affect this edit.

shareIdstringrequired

Share ID

clearbooleanoptional

If true, remove crops for the given segmentIndices instead of setting them.

consistentbooleanoptional

anchor:"face" only. Set true when the user wants the SAME framing across segments ("consistently", "throughout", "every clip", "all segments"), or when the camera is locked off (an interview on a tripod). The server then finds the presenter on a spread sample of the segments and stores ONE rectangle per camera and zoom on every requested segment of that camera, so the picture does not shift at the cuts. The 24-segment limit does not apply in this mode: send every segment of the edit in one call. Leave it off only when the subject really moves between segments (a walk-and-talk, a stage) and each segment needs its own window.

cropsobject[]optional

overlaysobject[]optional

B-roll cutaways to frame, each by overlayIndex or atSec with x/y/w/h on the cutaway's own frame. Not together with `crops`.

Parameters

editNamestringrequired

The edit these stabilization flags apply to (from list_edits / get_edit). Flags are stored per-edit and only affect this edit.

shareIdstringrequired

Share ID

enablebooleanoptional

true (default) stabilizes the segments; false un-stabilizes them (reverts to the original footage).

overlaysobject[]optional

B-roll cutaways (add_brolls overlays) to (un-)stabilize, each by `overlayIndex` from get_edit(format="timeline") or by `atSec` (the overlay on screen at that timeline second).

segmentIndexesinteger[]optional

The 0-based segment `index` values from get_edit(format="segments") to (un-)stabilize. Send `segmentIndexes`, `overlays`, or both.

Parameters

editNamestringrequired

The edit these motions apply to (from list_edits). Motion is stored per-edit and only affects this edit.

shareIdstringrequired

Share ID

motionsobject[]optional

One entry per segment to animate (or clear).

overlaysobject[]optional

B-roll cutaways (add_brolls overlays) to animate (or clear), each by `overlayIndex` or `atSec`.

Parameters

shareIdstringrequired

Share ID

style"cinematic" | "static"required

"cinematic" = auto motion ON (Ken Burns on stills + subtle push/drift on b-roll & montage clips, plus subtle jump-cut reframes on talking-head cuts where enabled); "static" = ALL auto motion OFF — every clip, talking-head spine included, holds still. Explicit per-segment motion is unaffected either way.

Parameters

editNamestringrequired

The edit these speed ramps apply to (from list_edits). Stored per edit.

shareIdstringrequired

Share ID

overlaysobject[]optional

One entry per B-roll overlay to retime (or clear). Each overlay keeps its length and position; it plays less of its footage, slower.

rampsobject[]optional

One entry per A-roll segment to retime (or clear). Send `ramps`, `overlays`, or both.

Parameters

editNamestringrequired

The edit these transitions apply to (from list_edits). Transitions are stored per-edit and only affect this edit.

shareIdstringrequired

Share ID

audioCrossfadeSecnumberoptional

AUDIO crossfade at EVERY cut of this edit's dialogue, in seconds (0.02-2; 0 removes it). The transitions above are picture-only; this is the sound. The outgoing clip fades out and the incoming clip fades in across the cut (equal power), using a little of each clip's audio beyond the cut, so the edit's length and picture timing do not change. Baked into cloud MP4 renders. NLE exports carry their own short audio crossfades at cuts. The web player previews it as a smooth dip in level through each cut; the MP4 export blends the two sides. Can be sent with or without `transitions`.

overlaysobject[]optional

B-roll cutaways to fade in and/or out (or clear), each by overlayIndex or atSec. Can be sent with or without `transitions`.

transitionsobject[]optional

One entry per transition to set (or clear). Optional when only `audioCrossfadeSec` is sent.

Parameters

editNamestringrequired

Edit to grade (from list_edits). Only this edit changes.

shareIdstringrequired

Share ID

clearbooleanoptional

If true, remove this edit's entire grade (whole-edit look + source overrides) instead of setting it.

contrastnumberoptional

Contrast multiplier, ~0.5–1.5 (1 = neutral).

exposurenumberoptional

Brightness multiplier, ~0.5–1.5 (1 = neutral).

grainobjectoptional

FILM GRAIN: animated grain over the picture (a new grain pattern every frame).

hazeobjectoptional

HAZE / DIFFUSION GLOW: soft bloom around bright areas and milky lifted blacks, like a Pro-Mist filter.

lookMatchbooleanoptional

Set true when NOBODY asked for this look in words: a default look you add on your own, or a look matched to a reference clip or a Backgrounder reference video. The stored grade is then held to a gentle strength: it never tints a neutral grey by more than 10% at any tone, and saturation stays within 0.15 of 1. Omit it when the user asked for the look in their own words.

saturationnumberoptional

Saturation multiplier, 0–2 (1 = neutral, 0 = black & white).

sourceOverridesobject[]optional

Per-source refinements WITHIN this edit; each entry layers over the whole-edit look for that source only.

splitToneobjectoptional

SPLIT TONING: one hue in the shadows and another in the highlights (e.g. teal shadows / orange highlights). Pure black and pure white stay neutral.

temperaturenumberoptional

Cool ↔ warm, -100..100 (0 = neutral).

tintnumberoptional

Green ↔ magenta, -100..100 (0 = neutral).

Parameters

editNamestringrequired

Edit whose title track to read (from list_edits).

shareIdstringrequired

Share ID or full URL

findstringoptional

The user's own words for an item already on the edit ("the question cards", "the logo"). Searches every on-screen layer and returns `onScreenLookup`.

Parameters

editNamestringrequired

Edit whose title track to set (from list_edits).

shareIdstringrequired

Share ID

titlesobject[]required

The full title list (replaces existing). Empty = clear. Each item has EXACTLY these fields: text, startSec, endSec, optional fontFamily, color, position, entrance, entranceSeed, fadeOutSeconds — no other field names are accepted.

Parameters

editNamestringrequired

Edit to place the graphic on (from list_edits).

shareIdstringrequired

Share ID

clearbooleanoptional

true = delete ALL graphics on this edit.

endSecnumberoptional

idstringoptional

Existing graphic id to replace in place.

origin"user_asked" | "brief_implies" | "own_judgement"optional

Who wants this NEW graphic: 'user_asked' (the user asked for it, now or earlier, or approved your plan for it), 'brief_implies' (not asked, but the brief clearly implies it, such as an ad's end card), 'own_judgement' (your idea). A graphic the brief neither asks for nor implies is refused. When you add one on your own judgement, say so to the user in one line.

propsobjectoptional

The template's props (see template contracts).

removestringoptional

Graphic id to delete.

startSecnumberoptional

stylePack"eddie-default" | "editorial-bold" | "explainer" | "bold-social" | "signal" | "clean-white" | …optional

Style pack for this edit's graphics. Sets the edit default (same as set_style_pack) and styles this graphic.

template"kinetic-title" | "lower-third" | "stat-callout"optional

Template to use (required unless remove/clear).

Parameters

editNamestringrequired

Edit to style (from list_edits).

pack"eddie-default" | "editorial-bold" | "explainer" | "bold-social" | "signal" | "clean-white" | …required

Style pack to apply to this edit.

shareIdstringrequired

Share ID

Parameters

shareIdstringrequired

Share ID

anchorobjectoptional

blend"normal" | "screen" | "multiply" | "overlay" | "exclusion" | "difference"optional

Optional blend mode for the whole clip against the footage: "exclusion" or "difference" make white text and shapes invert against the picture (the POV founder vlog look — the author is told to design in bold white); "screen" lightens, "multiply" darkens, "overlay" adds contrast; "normal" (default) draws on top. Change it later for free with set_blend_mode. Set it only when the user asks for a blend or a look that needs one.

buyCutoutnumberoptional

The paid HIGH-QUALITY CUT-OUT of the person for this edit's behind-subject clips (the final picture; the standard cut-out is free). Used ON ITS OWN with shareId and editName, never with a prompt. 0 = state the price and buy nothing. The quoted price = buy at that price — only after you told the user the price and they agreed. A price that changed since the quote is refused and nothing is charged. Seconds already cut out are never charged again.

canvasAspect"16:9" | "9:16" | "1:1"optional

Only on a project with NO edit and NO footage, where this call starts a graphics-only edit: its frame. "16:9" (1920x1080, default), "9:16" (1080x1920, vertical) or "1:1". Pass "9:16" when the user asks for a vertical, Reels, TikTok or Shorts graphic. Ignored when the edit already exists.

depth"over" | "behind-subject"optional

Where the clip sits: 'over' the picture (default) or 'behind-subject' — composited under the person in the footage, so big text reads as if it stands behind them. Behind-subject needs a person in frame; with no person the clip simply shows over the picture. Use 'behind-subject' when the user asks for "text behind me", "words behind the person", "title behind the speaker", "text behind the subject", "text between the layers". It is also how Eddie puts a NEW BACKGROUND behind the person in the edit ("change the background", "replace the background", "put me in a studio"): author an opaque, full-frame backdrop clip with 'behind-subject' over the window they name, so everything but the person is covered. Tell the user the edge around the person comes from a cut-out, not a keyed green screen, and to check it in the preview. A video FILE with the background removed is cut_out_subjects, not this.

editNamestringoptional

Edit to place the clip on (from list_edits). Required unless jobId is passed — except on a project with no edit and no footage, where it names the graphics-only edit this call starts (default "mgfx").

endSecnumberoptional

Timeline second the clip ends (default startSec + 4).

fieldsobjectoptional

With template: the real words for every field of that template, by field key (e.g. {"name":"Dana Reyes","role":"Head of Design"}); a number field takes a number. Placeholder words are refused.

jobIdstringoptional

Collect a QUEUED authoring job instead of starting one: pass the jobId from this tool's earlier "motion_graphic_queued" receipt (with shareId only). Authoring runs in the background for 30–90 s; each collect call waits up to ~18 s and answers with the clip once it is saved.

namestringoptional

Clip name; the author names it when omitted.

origin"user_asked" | "brief_implies" | "own_judgement"optional

Who wants this NEW graphic: 'user_asked' (the user asked for it, now or earlier, or approved your plan for it), 'brief_implies' (not asked, but the brief clearly implies it, such as an ad's end card), 'own_judgement' (your idea). A graphic the brief neither asks for nor implies is refused, and one added on your own judgement must be named to the user in one line. Placeholder words in quotes ("Your Brand", "Lorem", "[Product]") are refused.

promptstringoptional

What the graphic is, what it says, and how it moves — e.g. "an animated lower third for Dana Reyes, Head of Design, sliding in from the left with the accent bar". Required unless jobId or template is passed.

startSecnumberoptional

Timeline second the clip starts (default 0).

templatestringoptional

Place a designer template by id INSTEAD of authoring from a prompt — free and instant, no credits. One of: afterglow-name-chip, afterglow-title, brand-end-card, chapter-slate, headline-title, hook-slam, ink-name-tag, ink-stamp-stat, location-date-stamp, logo-bars-sting, name-lower-third, price-tag, pull-quote, ring-percent-stat, ruled-lower-third, stat-count-up, subscribe-cta, sunroom-title, three-point-list. Pass its words in `fields`; never together with prompt.

textBoxobjectoptional

Optional: the box the lettering must fill, as fractions of the frame. Pass exactly what an apply_style plan step gives (it was placed so the speaker does not cover the words); never invent one.

Parameters

shareIdstringrequired

Share ID

clipIdstringoptional

The motion graphics clip to change (mg-… from add_motion_graphic / get_edit treatments.motionGraphics). Required unless jobId is passed.

editNamestringoptional

Edit the clip is on (from list_edits). Required unless jobId is passed.

elementstringoptional

CSS selector ("#id" or "[data-mg-id=x]") to rewrite ONLY that element; omit for a whole-clip change.

jobIdstringoptional

Collect a QUEUED refine job instead of starting one: pass the jobId from this tool's earlier "motion_graphic_queued" receipt (with shareId only). The refinement runs in the background for 30–90 s; each collect call waits up to ~18 s and answers with the new version once it is saved.

promptstringoptional

The change to make, in plain words. Required unless jobId is passed.

Parameters

editNamestringrequired

Edit to caption (from list_edits).

shareIdstringrequired

Share ID

activeColorstringoptional

Highlight color for the word being spoken (hex). Default #39E0A6. Ignored for 'static' captions (no per-word highlight).

avoidFacesbooleanoptional

Keep caption cards off the speaker's face. ON by default. Eddie looks at where the subject is in each shot and picks a band that is clear, preferring `position` whenever it already is. Set false to pin every card to `position` regardless of what is in the frame.

background"none" | "pill" | "scrim"optional

Per-line background band: 'pill' = solid rounded band, 'scrim' = soft translucent wash, 'none' = bare text with shadow. Overrides the look's band. Default none (social = pill, documentary = scrim).

bandOpacitynumberoptional

Background band opacity override (pill default 0.6, scrim 0.38). Ignored without a band.

blend"normal" | "screen" | "multiply" | "overlay" | "exclusion" | "difference"optional

Optional blend mode against the footage: "exclusion" or "difference" make white text invert against the picture instead of sitting on top (the POV founder vlog look — pair it with large, bold, white type); "screen" lightens (dark parts vanish), "multiply" darkens (light parts vanish), "overlay" adds contrast; "normal" (default) draws on top. The blend appears in the player and MP4 exports only; NLE exports do not carry or mention it. Set it only when the user asks for a blend or a look that needs one.

cleanTextbooleanoptional

Clean the caption TEXT: drop profanity and stutters ("I, I think" → "I think", a broken-off "th-" goes). The audio and the transcript are untouched — a bleep is not this. false captions them again.

clearbooleanoptional

Remove the caption track instead of adding it.

colorstringoptional

Word/text color (hex). Default #FFFFFF. For static captions this is the only color used.

entrance"none" | "fade-up" | "slide-in" | "drop-in" | "random"optional

Per-card entrance animation: 'fade-up' = every card fades in while rising; 'slide-in' = slides in from the left; 'drop-in' = falls in from above; 'random' = varied entrance per card, deterministic from entranceSeed so preview == export. Default none (cards cut in).

entranceSeedintegeroptional

Seed for the 'random' entrance variation (stored so the web preview and the MP4 bake move identically). Absent = rolled once server-side.

excludeobjectoptional

Leave some words uncaptioned: a speaker (an interviewer), a source that already carries burned-in captions, or single segments. Excluded clips keep their place on the timeline; only their captions go. Stored on the track, so later rebuilds keep it. To change ONLY what is excluded on an edit that already has captions, pass only shareId, editName and exclude: the look and every other setting stay. Pass {} to caption everything again. Applies to the player, the MP4 export, Final Cut captions and SRT/VTT files.

fontFamilystringoptional

Pass ONLY when the user names a font (a face uploaded to the workspace, so the MP4 burn-in stages the same file the preview shows). Omit it otherwise: the attached brand kit's font is applied automatically and wins over the look's typeface; with no kit font the look's typeface or Open Sauce Two renders. The result's `font` reports the face and its source. Latin lines only — non-Latin scripts keep their bundled face for glyph coverage.

fontPackFamily"Open Sauce Two" | "Libre Franklin" | "Fraunces" | "Chivo" | "Space Grotesk"optional

A bundled display typeface for latin caption text — one the MP4 bake also stages, so preview and export match. The default is Open Sauce Two. 'Chivo' is heaviest (short-form), 'Libre Franklin' is a news gothic, 'Fraunces' is an editorial serif. Non-latin scripts keep their own face either way. The attached brand kit's font, or a `fontFamily` the user named, overrides this.

hideDuringTitlesbooleanoptional

Hide the captions while each of this edit's titles (set_titles, and kinetic-title graphics) is on screen: adds those titles' windows to hideWindows. Pass true when the user says captions collide with or overlap a title. If titles are added or moved later, call again.

hideWindowsobject[]optional

Timeline windows (edit seconds, as get_edit shows them) where NO caption shows — for example while a title or a full-screen graphic is on screen, so the two do not collide. Replaces the windows the track had; [] shows captions everywhere again. The words in a window are left out of the captions only: the audio plays on. Applies to the player, the MP4 export, Final Cut titles, the Resolve subtitle track and SRT/VTT files.

keepFillersbooleanoptional

Keep filler words (um, uh, er, hmm, "you know" tics) in the caption text. Default false — fillers are stripped from captions (never from the audio or transcript). Set true only when the user explicitly asks for verbatim captions.

languagestringoptional

Pass this ONLY when the user named a language for the captions ("Spanish subtitles", "captions in French"). It exists so that ask can be answered, not so it can be granted: captions are the spoken words verbatim, and Eddie does not translate them, so this argument always REFUSES and tells the user what to do instead. Translating what an edit says into another language is dubbing — generate_voiceover with `dubLanguage`. Never pass this argument on your own initiative.

look"social" | "documentary" | "minimal" | "punch" | "editorial"optional

Designed caption look: 'social' = big word-pop on a rounded band, yellow highlight; 'documentary' = calm static phrases on a soft wash; 'minimal' = small bare text; 'punch' = short-form/vertical style, TWO words a card, very large upper-case, green highlight, no band; 'editorial' = explainer style, four words a card in a news gothic on a soft wash. Sets defaults for the params below; any explicit param overrides its field.

lowercasebooleanoptional

Write the caption words in lower case (the all-lowercase caption style). false restores the transcript casing. Cannot be combined with uppercase.

maxCharsPerLineintegeroptional

The most characters on one caption line, 16-60 (broadcast subtitles use 32-42). A caption then holds at most two such lines, so a smaller number gives shorter captions. 0 removes the limit. Default: no line limit. Applies to the player, the MP4 export, SRT/VTT files and the NLE captions.

position"bottom" | "center" | "top"optional

Where the caption band rests. Default bottom. 'top' is the upper third. This is a PREFERENCE: with avoidFaces on (the default) a card that would land on the speaker's face moves to a clear band instead.

punctuation"keep" | "remove" | "removeLineEnds"optional

Punctuation in the caption TEXT. 'keep' (default) = as transcribed; 'remove' = no punctuation at all (apostrophes and hyphens inside a word stay); 'removeLineEnds' = no comma, full stop, colon, semicolon, ellipsis or dash at the end of a line (question and exclamation marks stay). Display only: the transcript keeps its punctuation, and a caption still ends where a sentence ends. Applies to the player, the MP4 export, SRT/VTT files and the NLE captions (an SRT cue or an NLE caption counts as one line).

shadow"none" | "soft" | "strong"optional

The text shadow. 'none' = clean text, with no outline and no drop shadow; 'soft' = a light drop shadow; 'strong' = a heavy outline and drop shadow, for bare text over busy or bright footage. The documentary and minimal looks default to 'none'; the other looks keep their own shadow. Shows in the player and the MP4 export. NLE files do not carry it: each editor uses its own caption look.

sizeFractionnumberoptional

Font size as a fraction of canvas height (default 0.06).

speakerColorsobject[]optional

Caption color PER SPEAKER, e.g. [{speaker:'Speaker 2', color:'yellow'}] for "make speaker 2 yellow". A listed speaker's words rest in that color instead of `color`; unlisted speakers keep `color`; the active-word highlight is unchanged; a caption card never mixes two speakers. To change ONLY speaker colors on an edit that already has captions, pass only shareId, editName and speakerColors: the track keeps its words, look and every other setting, and earlier speaker colors stay unless named again. Pass [] to remove every speaker color. Shows in the player and the MP4 export. An FCPXML carries it on each caption title. SRT/VTT files and the caption file beside a Premiere project are text only, and a Resolve project's subtitle track uses Resolve's own subtitle style.

style"word-pop" | "static"optional

'word-pop' (default) = animated karaoke-style, each word pops/highlights as it's spoken. 'static' = plain subtitle block, whole phrase appears at once, no per-word animation.

uppercasebooleanoptional

Render caption text UPPERCASED (display only — stored words keep their transcript casing). Default false.

wordsPerCardintegeroptional

How many words a caption card may hold (1-12; default 7). This is the biggest lever on how captions read: 7 is subtitle rhythm, 2-3 is the short-form creator rhythm. Cards still break earlier at sentence ends and real pauses.

Parameters

editNamestringrequired

Edit to watermark

shareIdstringrequired

Share ID

clearbooleanoptional

Remove the watermark instead of setting one.

endSecnumberoptional

End of the watermark window, timeline seconds. Omit (with startSec) for the whole edit.

logoImagestringoptional

Use this project image as the logo instead of the Brand kit logo: its Source ID (preferred) or name from list_sources. Only images in this project; PNG, JPG or WEBP.

position"top-left" | "top-right" | "bottom-left" | "bottom-right"optional

Named corner for the logo. Required unless `rect` is given (or clear=true).

rectobjectoptional

Custom normalized placement rect (x,y,w,h, 0..1) on the canvas — an escape hatch for finer control than a named corner. Overrides `position` when both are given (position is still stored, snapped to the nearest corner, for export labeling).

sizeFractionnumberoptional

Logo width as a fraction of canvas width. Default 0.12 (~12%).

startSecnumberoptional

Start of the watermark window, timeline seconds. Omit (with endSec) for the whole edit.

Parameters

shareIdstringrequired

Share ID

Parameters

editNamestringrequired

Existing edit name

shareIdstringrequired

Share ID

compositionIdstringoptional

Composition id from list_adobe_motion_graphics

confirmbooleanoptional

false/omitted = a new After Effects render only quotes its price. true = the user approved the quoted price: charge and queue the render.

controlsobjectoptional

Editable control values keyed as listed

endSecnumberoptional

Optional end in timeline seconds

importIdstringoptional

Import id from list_adobe_motion_graphics

renderJobIdstringoptional

Queued Adobe render to collect

renderMode"native" | "adobe-assisted"optional

Native editable conversion by default; explicitly select the original Adobe render when needed

startSecnumberoptional

Start in timeline seconds

Parameters

editNamestringrequired

The edit these clean-up flags apply to (from list_edits / get_edit). Flags are stored per-edit and only affect this edit.

segmentIndexesinteger[]required

The 0-based segment `index` values from get_edit(format="segments") whose sound to clean up (or restore).

shareIdstringrequired

Share ID

enablebooleanoptional

true (default) plays the cleaned voice on these segments; false puts their original sound back (free).

quoteOnlybooleanoptional

true = only price the clean-up: which files (every microphone of a multicam mix included), how many minutes and how many credits. Nothing is flagged or charged.

Parameters

shareIdstringrequired

audioOnlybooleanoptional

confirmbooleanoptional

editNamestringoptional

jobIdstringoptional

mode"extended" | "standard"optional

sourceIdstringoptional

voice"female" | "male"optional

Parameters

editNamestringrequired

Edit to attach the soundtrack to (from list_edits).

shareIdstringrequired

Share ID

acceptOfferbooleanoptional

Set true ONLY when the user answered a quoted offer of a new music track with a plain yes. The offer comes from append_to_edit (`musicOffer`). The track is made at the quoted length and the quoted price, no more, and replaces the edit's soundtrack. Pass just shareId + editName (and `prompt` if the offer says so). Nothing is charged unless the offer is open, unexpired and not already accepted.

appendbooleanoptional

Place the cue right after the last cue on the lane (instead of at `startSec`). The sequential-files case.

cueIdstringoptional

An existing cue on the lane (ids come back from get_edit / a previous placement). With `remove:true` removes that cue; with only `gainDb`/`ducking` re-levels that cue alone; with `prompt` or `trackId` REPLACES that cue with the new track, in the same window.

duckingobjectoptional

Transcript-driven auto-ducking under speech. Omitted = enabled with defaults.

endSecnumberoptional

Where the cue ends on the timeline. Omit = the cue runs until its file runs out (or the edit ends). With `prompt`, `endSec - startSec` is the generated length when `durationSec` is omitted.

fadeInSecnumberoptional

Fade-in length for this cue (default 0, or 1 s when it meets another cue).

fadeOutSecnumberoptional

Fade-out length for this cue (default 0, or 1 s when it meets another cue).

gainDbnumberoptional

The bed's base level in dB: 0 = today's level (the maximum), -6 = half as loud, -40 = barely audible. Ducking is relative to this, so the bed sits here between lines and `gainDb + duckDb` under speech. Omitted = unchanged.

lengthGovernance"picture" | "track"optional

THE USER'S ANSWER to the length question — required only when the tool has already refused with one. 'picture' = the cut governs (the bed is clamped/looped to the edit; this is what every soundtrack did before the shelf). 'track' = the track governs (nothing is trimmed; the edit is meant to grow to the track's length). Do NOT supply a value the user did not give you.

offerIdstringoptional

The `musicOffer.offerId` being accepted. Optional: without it the newest open offer for this edit is meant.

offsetSecnumberoptional

Start playback this many seconds INTO the file (skip an intro). Cue placements only.

removebooleanoptional

If true, remove the edit's music (the whole lane, or one cue when `cueId` is given).

sourceIdstringoptional

Use an audio-only file already imported into THIS project (its source id or filename from list_sources) as the track (FREE): it is copied onto the workspace music shelf, then attached or placed like a shelf track. Takes the place of `trackId`; ignored when `prompt` is given.

startSecnumberoptional

PLACE the track as a cue starting at this timeline second (see the cue rules above). Omit for the whole-edit bed behaviour.

titlestringoptional

Short display title for the track (default: prompt).

trackIdstringoptional

Attach this track from the workspace music shelf (FREE): the track's id, or its title as the user names it. Omit to attach whatever the project has attached in its context picker (or the shelf's only track). Ignored when `prompt` is given. Never an upload — the shelf is filled on the /music page.

userAskedbooleanoptional

Set true only when the USER asked for music (in an earlier message, or by approving your plan for it). Needed only when this tool has refused an unasked generation and told you to offer it first.

Parameters

editNamestringrequired

Edit to place the sound on (from list_edits).

shareIdstringrequired

Share ID

acceptCreditsnumberoptional

Batch only, with confirm:true: the total credits the quote stated. A batch that now costs more than this is refused and re-quoted.

anchoranyoptional

Optional: {kind:"segment", segmentId, offsetSec} | {kind:"word", sourceId, wordIndex, offsetSec} | {kind:"clip", clipId, offsetSec}; default {kind:"timeline"}.

clearbooleanoptional

Delete every sound effect on this edit. Free; no prompt needed.

confirmbooleanoptional

Batch only: true places the batch and takes the charge. Send it with acceptCredits after the user agreed to the quoted total.

durationSecnumberoptional

Requested length in seconds, 0.5–30 (default 2; a bare house cue name uses its house length).

gainDbnumberoptional

Level in dB (default -6).

namestringoptional

Optional short label for the timeline chip.

placementsobject[]optional

Place several sounds in one call: up to 50 items, each {prompt, startSec, durationSec?, loop?, name?, gainDb?, anchor?}. Used INSTEAD of the top-level prompt/startSec. Without confirm the call is a quote and does nothing.

promptstringoptional

The sound, in plain words — or just a house cue name (whoosh, swoosh, pop, ding, click, riser, impact, sparkle, glitch, tick; leave durationSec out) for the house sound. Required unless `remove` or `clear` is given.

removestringoptional

Sound effect itemId to delete (from get_edit treatments.soundEffects). Free; no prompt needed.

startSecnumberoptional

Timeline second the sound starts (default 0).

Parameters

shareIdstringrequired

Share ID

cueIdstringoptional

With editName: measure this ONE cue of the edit's music lane (cue ids come from get_edit's `treatments.musicCues`). Omit on a lane of several cues to get every cue's grid, or the cue ids still to measure.

editNamestringoptional

Analyze this edit's attached soundtrack (from list_edits). Pass exactly one of editName / sourceId.

forcebooleanoptional

Re-analyze past the cache (a fresh PAID analysis). Only useful when the audio itself changed.

sourceIdstringoptional

Analyze a project source instead (music imported as footage). Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

Parameters

editNamestringrequired

Edit whose cuts to snap (from list_edits).

shareIdstringrequired

Share ID

sourceIdstringoptional

Snap against this analyzed project source's beat grid instead of the edit's own soundtrack. Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

toleranceSecnumberoptional

How far a cut may move to reach a beat, in seconds (0.05–1, default 0.3). A cut only ever moves to one of its two adjacent beats — it never crosses a beat.

Parameters

editNamestringrequired

Edit whose track to mute (from list_edits).

mutedbooleanrequired

true silences the lane in playback and every export; false restores its audio.

shareIdstringrequired

Share ID

track"original" | "voiceover" | "music" | "sfx"required

Which lane: 'original' = the clips' own synced camera audio (V1 dialogue spine), 'voiceover' = the VO lane's generated narration clips, 'music' = the M lane's soundtrack, 'sfx' = the SFX lane's sound effects.

Parameters

editNamestringrequired

Edit whose audio to level (from list_edits).

shareIdstringrequired

Share ID

autoLevelSpeechbooleanoptional

true levels each source's speech to −16 LUFS before the mix; false keeps every source at its recorded level. Omit to leave it unchanged.

deliveryLoudness"web" | "broadcast_ebu" | "broadcast_atsc" | "off"optional

Final loudness of the video file: 'web' (−14 LUFS, YouTube and social), 'broadcast_ebu' (−23 LUFS), 'broadcast_atsc' (−24 LKFS) or 'off' (keep the mix level). Omit to leave it unchanged.

Parameters

endSecnumberrequired

End of the window, in seconds. At most 10 minutes after startSec; a window past the end of the file is cut at the end.

shareIdstringrequired

Share ID

sourceIdstringrequired

Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

startSecnumberrequired

Start of the window, in seconds on the source's own timeline (the get_transcript clock).

minSilenceMsintegeroptional

The shortest silence to report, in milliseconds (100 to 10000, default 300).

requireSpeechProfilebooleanoptional

For speaker volume balancing, wait for a measured passage-level RMS and peak profile before treating this source as ready. The result must include speechProfileReady:true.

silenceThresholdDbnumberoptional

A silence is audio at or below this level, in dBFS (-90 to -20). Omit it to use 6 dB above the file's own noise floor, never above -35.

Parameters

editNamestringrequired

The edit whose segments to change (from list_edits). Stored per edit.

segmentsobject[]required

shareIdstringrequired

Share ID

Parameters

channelsinteger[] | nullrequired

0-BASED channels to play (send [1] for the user's "channel 2"); null clears the choice at this level.

shareIdstringrequired

Share ID

filestringoptional

With `group`: which file of the group (mediaId, role or name from get_multicam_angles); default the group's audio file. Without `group`: the file whose own default to set (a source id or name from list_sources).

groupstringoptional

A multicam group (groupId or name from get_multicam_angles): set the channels for every cut of that group. Omit to set a file's own default.

Parameters

editNamestringrequired

shareIdstringrequired

atSecnumberoptional

Parameters

shareIdstringrequired

fcpxmlVersion"1.13" | "1.14"optional

jobTokenstringoptional

labelledOnlybooleanoptional

Parameters

shareIdstringrequired

curve"slog3" | "clog3" | "vlog" | "dlog" | "applelog"optional

sizenumberoptional

sourceIdstringoptional

Parameters

contentstringrequired

The COMPLETE file content, already formatted for the chosen format — valid SRT/VTT cues, CSV with a header row, etc. You build this. With combineFrom, this is appended AFTER the combined files; pass "" when there is nothing to add.

filenamestringrequired

File name WITHOUT extension, e.g. "Episode 4 transcript (French)".

format"srt" | "vtt" | "txt" | "md" | "csv" | "json" | …required

srt/vtt = subtitles, txt/md = plain/markdown, csv = spreadsheet, json = data, pdf/docx = typeset documents (write markdown-style content).

shareIdstringrequired

Share ID

combineFromstring[]optional

Optional: download links of files already built on THIS project, in the order they belong. Their stored text is joined into this file before `content`. Text formats only (srt, vtt, txt, md, csv); every part must be the same format (txt and md mix). At most 20.

rowsobjectoptional

Optional, csv/txt/md only: sort and/or de-duplicate the rows of the finished file (after combineFrom and content are joined). The CSV header stays first.

Parameters

shareIdstringrequired

Share ID

format"txt" | "md" | "srt" | "vtt" | "csv" | "json" | …optional

File format. Default txt.

sourceIdstringoptional

Source id, filename or list_sources index. Omit to export every transcribed source, one file per source.

startAtintegeroptional

Only with sourceId omitted: the position in the project's source list to start from (0 = the first). A partial answer gives nextStartAt; pass it here to continue.

Parameters

editNamestringrequired

Edit to verify (from list_edits).

shareIdstringrequired

Share ID

Parameters

editNamestringrequired

Edit to export (from list_edits).

format"fcpxml" | "fcpxml-resolve" | "premiere" | "premiere-xml" | "otio" | "mp4" | …required

fcpxml (Final Cut Pro), fcpxml-resolve (DaVinci Resolve), premiere (a NATIVE Premiere Pro project file, .prproj — what a user means by "export to Premiere", and the same file the web Export menu's Premiere row sends), premiere-xml (the older Premiere interchange XML; use it when the user asks for the XML by name, or names a Premiere older than 2026 or does not know their version (the .prproj is checked against Premiere Pro 2026 only, and every Premiere release imports the XML)), otio (OpenTimelineIO), mp4 (finished video, cloud-rendered — max 60 minutes), resolve-cloud (Blackmagic mirror projects only: lands the cut as a timeline INSIDE the connected DaVinci Resolve cloud project — no file, no download; call again to check progress), or premiere-production (Production mirror projects only: writes the cut as a native .prproj into the connected Premiere Production's Eddie folder — no file, no download; call again to check progress). The .prproj keeps bins, per-clip crops, gains, audio channel layout and REAL multicam clips; premiere-xml flattens multicam onto stacked tracks and carries none of the rest — so never offer the XML as the better file, only as the older-Premiere one. This list is what THIS TOOL can produce, not everything Eddie exports: the native DaVinci Resolve `.drp` is real and supported but comes from the web share view's Export menu rather than from here. `fcpxml-resolve` is an interchange file Resolve imports — it is NOT a substitute for a `.drp`, so never offer it as one. wav / mp3: the edit’s full mix as ONE AUDIO FILE and no picture (WAV: 48 kHz, 24-bit, stereo; MP3: 320 kbps, 48 kHz, stereo). Use it when the user wants the audio, a podcast file or the soundtrack of the cut. It is the MP4 export’s own mix, so it sounds the same. HOW TO OPEN IT: every "premiere" and "premiere-xml" result carries howToOpen; put it in your reply in your own words. A request for "a Premiere project", "the project file" or "not an XML" is "premiere". A user who wants the timeline inside the Premiere project they already have open needs no second file: the .prproj imports into an open project with File > Import (Import Selected Sequences), the same way the XML does, so never offer a paid "premiere-xml" export as the way into their current project. A version is the exception: the .prproj is built and checked against Premiere Pro 2026 only, so a user who names an older Premiere, does not know their version, or says the project will not open is offered "premiere-xml" by default, and you never say or imply a .prproj opens in any particular older version or re-send the same .prproj to that user. If a "premiere" call fails and you deliver "premiere-xml" instead, the reply names the switch and why.

shareIdstringrequired

Share ID

acceptCreditsintegeroptional

mp4 only: the credits stated by the quote the user approved. Pass with confirm: true; required for a 200-credit export over 20 minutes.

captionsAsTitlesbooleanoptional

fcpxml only: write each caption card as its own connected Basic Title clip above the storyline, instead of Final Cut's native caption lane. Use it when the user wants to restyle or move each caption card on its own in Final Cut. Default false: native captions. No effect on an edit without captions. fcpxml-resolve always writes caption cards as titles; the other formats ignore this.

confirmbooleanoptional

mp4 only: approve the price an earlier mp4_export_quote result stated. Without it a priced MP4 export starts and charges nothing. A free export never needs it.

exportJobTokenstringoptional

For a pending fcpxml, fcpxml-resolve, or premiere-xml export only: pass back the exportJobToken from the previous export_edit response, with the same shareId, editName, and format, to collect the finished file.

favoriteRangesbooleanoptional

fcpxml only: ALSO mark every clip of this edit as a Final Cut FAVORITE on its source clip in the browser — each clip's own in and out point becomes a green Favorite range, so the moments show under the browser's Favorites filter on import. The timeline is still in the file. Use it when the user wants their selects, best moments or logged ranges "marked as Favorites" in Final Cut: build the ranges as an edit first (create_video_sequence with subclips "all" lays the analysed best moments of each b-roll clip at their own in and out points), then export it with this. It needs no transcript, so it works on silent b-roll. Retimed or disabled clips and audio-only clips are not marked, and the reply counts them. A long export can return an exportJobToken: pass favoriteRanges again with the token. Same price as the plain fcpxml export.

includeBrollSpeechbooleanoptional

Deprecated compatibility flag. The unified mcp-api-state interchange exporter does not carry source-side b-roll transcript markers yet, so NLE exports proceed without them and include an explicit note. MP4 ignores this flag.

maxSizeMBnumberoptional

mp4 only: the largest the delivered file may be, in megabytes (1 MB = 1,000,000 bytes). Use it when the user must deliver under a size limit, such as an upload form or an email attachment. The render lowers the video bitrate evenly across the whole edit so the file lands under the limit, and keeps the audio unchanged. If the edit already fits at full quality, nothing is reduced. If the limit is too small for this edit's length and resolution to stay watchable, the export is refused before anything renders, and the reply names the smallest size that works - offer the user that size, or a shorter edit. Omit it for a normal full-quality export.

redeliverbooleanoptional

resolve-cloud / premiere-production only: a finished delivery normally just reports done on repeat calls; pass true to deliver the edit AGAIN (e.g. after changing the edit) — resolve-cloud as a new versioned timeline, premiere-production as a fresh project file (overwriting Eddie's own earlier delivery, versioning any other collision).

resolution"1080p" | "2160p" | "source"optional

mp4 only: '1080p' (default, HD), '2160p' (true 4K, ONLY when the edit's picture supports it: 4K footage or a 4K canvas, motion-graphics composition clips, or clips upscaled to 4K with Topaz. Plain footage below 4K is never stretched to 4K: a 2160p request on it is refused before anything renders or is charged, and the reply names the paid Topaz upscale as the way to 4K and 1080p as the free alternative. When motion graphics lift an edit to 4K, footage below 4K beside them is scaled to the frame and the reply's sourceResolutionCeiling says so), or 'source' (original quality, up to 4K).

timelineFps"24" | "25" | "30" | "50" | "60" | "23.976" | …optional

fcpxml, fcpxml-resolve, premiere, premiere-xml and otio only: the sequence (timeline) frame rate. Omit it and the export picks the rate from the edit's footage. Use it when the user names a rate for the sequence. Each clip keeps its own frame rate and plays at normal speed; every cut lands on a frame of the chosen rate, up to half a frame from where it plays in Eddie. The export notes state the rate. mp4, wav, mp3, resolve-cloud and premiere-production ignore it.

zeroTimecodebooleanoptional

fcpxml and fcpxml-resolve only: declare every source as starting at 00:00:00:00 instead of the camera timecode Eddie read from the file. Default false. Final Cut refuses EVERY clip, with 'Invalid edit with no respective media', when the timecode the export declares does not match the timecode Final Cut reads from the media file. Some cameras store their timecode where Eddie can read it and Final Cut cannot. Use this only after the user reports that error, or reports that a Final Cut import had errors and no clips. It is not a fix for clips that import OFFLINE: those need Relink Files.

Parameters

format"premiere" | "fcpxml" | "fcpxml-resolve"required

premiere (tier N → literal video track N), fcpxml (Final Cut: tier V1 in the primary storyline, tier N above it on lane N-1) or fcpxml-resolve (the same lanes, written for DaVinci Resolve). Each delivers ONE file holding every tier. NOTE: "premiere" here is the Premiere interchange XML — a tiered selects timeline has no native .prproj; that file is export_edit's `premiere` format and covers an EDIT, not a selects reel.

shareIdstringrequired

Share ID

tiersobject[]required

ORDERED tiers, best/top-priority first — a segment lands on the FIRST tier whose criteria it matches.

keepFullCoveragebooleanoptional

Keep segments that match no tier on the LAST tier instead of omitting them (redundant when a catch-all "everything else" tier exists).

scopeobjectoptional

Omit to rate ALL a-roll sources.

selectsJobTokenstringoptional

For a pending background rating pass only: pass back the selectsJobToken from the previous export_selects response, with the same arguments, to get progress or collect the finished download links.

Parameters

editNamestringrequired

The edit whose clips are upscaled (from list_edits / get_edit). The upscale belongs to this edit.

shareIdstringrequired

Share ID

allClipsbooleanoptional

true = every clip of this edit that can be upscaled. Use it for "upscale all the clips in this edit". Cannot be combined with segmentIndexes.

confirmbooleanoptional

false/omitted = state the price, change nothing. true = the user agreed to the price — charge and start.

segmentIndexesinteger[]optional

The 0-based segment `index` values from get_edit(format="segments") to upscale. Omit together with allClips to be told what the whole edit would cost.

Parameters

editNamestringrequired

The edit to deliver upscaled (from list_edits / get_edit).

shareIdstringrequired

Share ID

confirmbooleanoptional

false/omitted = state the price, change nothing. true = the user agreed to the price — start the work. The credits are then taken clip by clip as each clip starts, not in one charge.

exportIdstringoptional

Ask where an export you already started has got to. Pass the exportId from an earlier confirmed call; shareId and editName are then ignored.

Parameters

editNamestringrequired

Edit name from list_edits

shareIdstringrequired

Share ID or full URL

openOnlybooleanoptional

Only unresolved notes. Off by default — resolved feedback is still the record of what was asked for.

reviewOnlybooleanoptional

Only notes that came in through a review link (what clients asked for), excluding the editor's own comments.

Parameters

editNamestringrequired

Edit name from list_edits

shareIdstringrequired

Share ID or full URL

bodystringoptional

The note itself. One point, in plain language, saying what you would change and why. Omit it when you pass `markers` or `onBeatGrid`.

markersobject[]optional

Several timeline markers in one call. Each becomes one timeline comment at its time, and exports as a marker.

onBeatGridobjectoptional

Markers on the music grid: one timeline comment on every beat or bar of the edit’s measured music (run detect_beats first), or of a tempo the user stated.

timelineSecnumberoptional

Seconds into the finished cut this note is about. Omit for a note about the whole edit.

Parameters

shareIdstringrequired

Share ID or full URL

editNamestringoptional

Edit name from list_edits. Use the edit the user is viewing. Omit only when you do not know it.

Parameters

shareIdstringrequired

Share ID of the project.

Parameters

recipeIdstringrequired

The recipe id, from list_recipes.

shareIdstringrequired

Share ID of the project.

Parameters

recipeIdstringrequired

The recipe id to run, from list_recipes.

shareIdstringrequired

Share ID of the project.

clipNamestringoptional

Motion graphic templates only: the new clip's name. Omit for the template's name.

controlsobjectoptional

Motion graphic templates only: control overrides keyed by control key (from get_recipe). List controls take arrays of typed rows; image controls take asset names. Required slots and sample values need real inputs before placement, e.g. {"headline": "Q3 results"}. Unknown keys are ignored and reported back.

editNamestringoptional

Motion graphic templates only: the edit to place the clip on (from list_edits).

endSecnumberoptional

Motion graphic templates only: where the clip ends (timeline seconds). Omit for the template's designed length.

startSecnumberoptional

Motion graphic templates only: where the clip starts, in TIMELINE seconds.

valuesobjectoptional

The input values, keyed by each recipe input id (e.g. {"topic": "our new studio", "length": 3}). Read the ids from get_recipe. Omit an optional input to drop its line from the prompt.

Parameters

promptTemplatestringrequired

The prompt, with each reusable blank written as {input_id}. Keep optional blanks on their own line so an empty value drops the line.

shareIdstringrequired

Share ID of the project.

taglinestringrequired

One plain sentence saying what it makes.

titlestringrequired

Short name for what the recipe produces, e.g. "Client review cut".

descriptionstringoptional

Optional longer description.

icon"film" | "phone" | "tag" | "script" | "mic"optional

Icon key (default film).

inputsany[]optional

The recipe's typed blanks (max 6). Each has an `id` (matching a {id} in the template), a `label`, and a `kind`: "textarea" ({placeholder?, required?, rows?}), "number" ({min, max, defaultValue, unit}), or "segmented" ({options:[{value,label}], defaultValue}). Omit for a recipe with no blanks.

requires"broll" | "multicam"optional

A project prerequisite the recipe needs (broll or multicam). Omit for none.

stylePackIdstringoptional

Optional style pack id to pin (from the set_style_pack pack list). Omit for none.

toolsUsedstring[]optional

Optional list of edit tool names this recipe typically uses (for display only).

Parameters

kind"bug" | "missing_feature"required

'bug' = a tool errored or did the wrong thing; 'missing_feature' = the user wanted something no tool can do.

summarystringrequired

One specific line (used to dedupe + count).

detailstringoptional

What you were trying to do, what happened, and (for a bug) any error text.

editNamestringoptional

Edit name, if relevant.

severity"blocking" | "annoying" | "nice_to_have"optional

'blocking' = you could not complete the task; 'annoying' = worked around it; 'nice_to_have' = polish.

shareIdstringoptional

Share ID/URL for context, if relevant.

toolNamestringoptional

The tool that failed, if this is about one.

Parameters

querystringrequired

Keywords for the user's question (e.g. 'export premiere', 'credits cost', 'multicam angles').

Parameters

shareIdstringrequired

Share ID

estimatedCostnumberoptional

Optional: credits the operation you are about to run costs. Returns whether the paying pool covers it and, if not, exactly how many credits short it is.

Parameters

shareIdstringrequired

Share ID

daysintegeroptional

How many days back to look (default 30, max 365). "This month" is the default; use 7 for "this week", 90 for "this quarter".

limitintegeroptional

Max transactions to return, newest first (default 50, max 200). The category rollup always covers the whole window regardless.

Parameters

shareIdstringrequired

Share ID (or share URL) of the batch project to move — the project whose footage should appear somewhere else.

confirmbooleanoptional

Pass true ONLY when re-issuing the identical call after reading the plan back to the user, and only together with the `planId` that plan returned.

detachbooleanoptional

Undo of a first move only: make the batch a stand-alone project again. Do not pass intoShareId with it.

intoShareIdstringoptional

Share ID (or share URL) of the top-level project the batch should join. Omit only with detach.

planIdstringoptional

The `planId` from the plan you are confirming. It is tied to this batch, this destination and where the batch sits now.

Parameters

namestringoptional

The project name. Omit for the default name a new project gets.

workspaceIdstringoptional

The workspace to create it in. Omit for the user's personal workspace.

Parameters

shareIdstringrequired

Share ID

backgrounderIdstringoptional

One attached document to read, with every passage listed. Omit it to read EVERY attached document that records marked passages in one call.

documentOffsetintegeroptional

With no backgrounderId: the 0-based index of the first document to return. Pass the previous answer's nextDocumentOffset to read the next page. Omit for the first page.

Parameters

editNamestringrequired

The edit whose footage the examples use (from list_edits / get_edit).

looksobject[]required

The looks (and optionally variants) to show, at most 4. Pass the looks you offered.

shareIdstringrequired

Share ID

titleTextstringoptional

The words for a "text_behind" example. Omit when the user has not said: the example then uses a short phrase from their own transcript and says it is an example.

Parameters

editNamestringrequired

The edit to change (from list_edits / get_edit).

mode"blur" | "none"required

"blur" blurs the background behind the speaker. "none" removes the background treatment from this edit.

shareIdstringrequired

Share ID

buyCreditsnumberoptional

Omit (or 0) to get the price and change nothing. Set to the quoted price, after the user agrees, to buy the cut-out and store the blur.

segmentIndexesinteger[]optional

Only these segments (0-based `index` from get_edit(format="segments")). Omit for the whole edit.

strength"light" | "medium" | "strong"optional

How soft the background gets. Default "medium".

Parameters

shareIdstringrequired

Share ID

confirmbooleanoptional

false/omitted = quote the price, change nothing. true = the user approved the quoted price: charge and start.

notestringoptional

What the user wants taken from the video, if they said.

referenceIdstringoptional

Read back a started import (free).

urlstringoptional

The YouTube link the user pasted (one video). Needed unless you pass referenceId.

Parameters

shareIdstringrequired

Share ID

analysisIdstringoptional

Read back a started shot list (free).

confirmbooleanoptional

false/omitted = quote the exact charge, change nothing. true = the user approved the quoted charge: charge and start.

notestringoptional

What the user wants kept from the video, if they said.

sourceIdstringoptional

The reference video to list the shots of. Which source, from list_sources: its Source ID (preferred — always exact), or its Name (the file extension is optional and matching ignores case, underscores and dashes), or its 1-based number in the list_sources listing. An unknown handle fails with the valid sources; a handle that matches SEVERAL sources fails with the candidates and their ids — it is never guessed at, so pass the Source ID whenever names could collide.

Parameters

shareIdstringrequired

Share ID

editNamestringoptional

Also review the clips in the order this edit plays them (continuity between neighbours).

judgeIdstringoptional

Read back a started review (free).

shotListIdstringoptional

A shot list's analysisId. Omit for the project's newest shot list.

shotsobject[]optional

Which reference shot each clip was generated for (shot index from analyze_reference_shots).

sourceIdsstring[]optional

Generated clips to review. Omit for every generated clip in the project.

Parameters

shareIdstringrequired

Share ID

querystringoptional

The user's own words for the look, e.g. "MrBeast style". Omit to list every look.

Parameters

blend"normal" | "screen" | "multiply" | "overlay" | "exclusion" | "difference"required

normal | screen | multiply | overlay | exclusion | difference

editNamestringrequired

Edit name (from list_edits)

shareIdstringrequired

Share ID

targetstringrequired

"captions" for the caption track, or a motion graphics clip id (mg-…).

Parameters

shareIdstringrequired

Share ID

buildReelbooleanoptional

Also write the cut-out reel as an edit once every photo is cut out (see the description). Call again with the same editName after adding music to put it on the beat.

confirmbooleanoptional

VIDEO ONLY: false/omitted = state the price, change nothing. true = the user agreed to the price — charge and start.

editNamestringoptional

With buildReel: the reel edit's name (default "Cut Out"); the same name again rebuilds it on its music.

endnumberoptional

VIDEO ONLY: end of the range, in seconds on the SOURCE clock. Default: the end of the source.

photosstring[]optional

Only these photos, by the asset name the photo already has in authoring (its file name, lower-cased and hyphenated). Omit for every photo in the project. With buildReel, this is also the reel order.

sourceIdstringoptional

VIDEO ONLY: the video source to remove the background from (its id from list_sources). Omit to cut out photos.

startnumberoptional

VIDEO ONLY: start of the range, in seconds on the SOURCE clock. Default 0.

Parameters

linkstringrequired

The download link build_document returned for the file.

shareIdstringrequired

Share ID

maxCharsintegeroptional

Page size in characters (default 20000).

offsetintegeroptional

First item (line, or CSV row; the header is item 0) to return. Default 0.

Parameters

editNamestringrequired

Edit to modify (from list_edits).

shareIdstringrequired

Share ID

clearbooleanoptional

true removes every rearranged-picture clip in this edit and nothing else.

pictureOrderstring[]optional

Segment ids, in the order their PICTURE should be seen, covering one unbroken run of the edit. The sound stays in the current order.

replaceExistingBrollbooleanoptional

true removes the user's other b-roll on the stretch instead of refusing. Ask the user first.

shotsobject[]optional

Source windows to show, laid back to back from timelineStart. Use for rearranging shots inside one long take.

timelineStartnumberoptional

With shots only: where on the edit, in seconds, the first shot starts. Default 0.

Parameters

languagestringrequired

The language code: "pt-BR", "es-419", "fr-CA", "de-CH", "pt-PT", "sv-SE", "en-GB", "es", … or "auto" to go back to automatic detection. An unsupported code fails with the full valid list.

shareIdstringrequired

Share ID

Parameters

shareIdstringrequired

Share ID

confirmbooleanoptional

false/omitted = state the price and change nothing. true = the user agreed to the price — charge and apply.

region"en-US" | "en-GB" | "en-AU" | "en-NZ" | "en-IN" | "pt-PT" | …optional

The region to write for: "en-GB" (British), "en-US", "en-AU", "en-NZ", "en-IN", "pt-PT" (Portugal), "pt-BR" (Brazil), "de-CH" (Switzerland), "fr-CA" (Canada), "es-419" (Latin America), "es" (Spain). Required unless revert is true.

revertbooleanoptional

true = remove the regional spelling from every transcript and stop applying it to new ones. Free.

Parameters

shareIdstringrequired

Share ID

confirmbooleanoptional

false/omitted = state the price, change nothing. true = the user agreed — charge and start.

guidancestringoptional

REQUIRED unless you pass runId. What to find, in the user's own words — e.g. "every try, from the pass that sets it up to the conversion kick".

runIdstringoptional

Read the result of an earlier search by the runId it returned. Free. Guidance and scope are then ignored.

scopestring[]optional

Optional source ids to search (from list_sources), A-roll or b-roll. Omit to search every video source in the project — name the source(s) the user means when the project has more footage than that, because every hour searched is charged.