Editor And Publishing

Editing Videos

The MCP editor tools operate on Videotok editor projects.

For editor projects, ready means the project exists and can be opened in the Videotok editor. It does not require exporting or downloading an MP4.

A typical editing flow is:

1. create_editor_video when starting from scratch, or list_editor_videos when editing an existing project. Newly created editor projects are ready to open immediately.
2. list_editor_media to find completed media from My Media.
3. upload_editor_media for new media that should become My Media, or add_editor_media for existing media/direct URLs.
4. get_editor_video to inspect track ids and item ids.
5. list_editor_sound_effects when choosing built-in SFX.
6. apply_editor_edits for supported structured operations.

Uploading Media

upload_editor_media creates a completed My Media item and returns its media.id.

Use one source per call:

• media for inline base64 or data URL payloads with decoded file size at most 3 MiB.
• upload_editor_media_from_url.url or upload_editor_media.source_url for larger files, rendered videos, signed URLs, and other agent-generated artifacts that can be fetched over HTTPS.

The hosted Videotok MCP server cannot read a local path like /Users/me/render.mp4 or a file:// URI from the agent machine. Do not put a local path in media.data; it must be base64 bytes or a data URL. REST multipart uploads are also limited to 3 MiB per file.

For a larger local file:

1. Call prepare_editor_media_upload with filename, content_type, and actual size_bytes.
2. PUT the raw file bytes from the local machine to upload.url with the returned upload.headers. Do not send multipart data or your Videotok API key to that URL.
3. After the PUT succeeds, call upload_editor_media_from_url with url set to the returned source_url, plus filename and content_type.

Remote/direct uploads allow video up to 200 MiB and image/audio up to 50 MiB. Preparation and PUT do not create a My Media item; the import returns its media.id.

Use preserve_original: true on the import only for an MP4/WebM whose playback and destination compatibility you have already checked. It stores the original bytes without waiting for transcoding, retains the source codec/container, and does not generate a thumbnail or verify codec compatibility. The default video Stream transcoding flow remains unchanged when omitted. Transfer timeouts remain possible.

After upload, reuse the returned My Media id:

• publish_media_to_social.media_id publishes the uploaded image, GIF, or video.
• add_editor_media.media_id adds it to a timeline.
• create_generation.reference_media_ids, source_video_media_id, motion_video_media_id, and audio_media_id use it as AI model input when supported.

Supported edit operations are:

• set_title
• remove_item
• set_item_timing
• set_item_source
• set_item_audio
• set_audio_levels
• set_item_animation
• set_item_motion
• apply_item_transition
• split_item
• set_item_transform
• move_item_to_track
• set_item_layer_order
• add_solid
• add_text
• update_text
• add_captions
• add_sound_effect
• add_voiceover
• update_captions
• generate_captions_from_items

Use from_seconds for timeline placement, duration_seconds for visible timeline length, and source_start_seconds when trimming into the original video/audio/captions source. Caption entries use Remotion-style JSON timing: text, startMs, endMs, optional timestampMs, optional confidence, and optional word-level words.

When track_id is omitted, add_editor_media packs compatible non-overlapping items onto existing tracks. Only force a track when layer order or overlapping timing requires it.

Music, voiceovers, voice assets, and SFX are audio timeline items. list_editor_media with media_type: "audio" includes audio and voice assets; media_type: "voice" returns voice-only. Use set_item_audio for one item, or set_audio_levels for groups by audio_roles (sound_effect, music, voiceover, voice, source_video, audio) or item_types. Older audio items without audioRole are inferred from asset metadata and normalized when matched. Do not remove SFX just to lower their volume.

Use add_voiceover to generate fresh TTS audio from text and place it on the editor timeline. It is paid, so pass a new idempotency_key for each new voice request and reuse it only when retrying that request. A paid voice request must contain exactly one add_voiceover operation and no other edits; submit additional voiceovers or timeline edits separately. Voiceover text is limited to 465 spoken words. Use recommend_voice or list_workspace_assets first when the user did not specify a voice. To replace speech in only part of a video, split the source clip around that section, lower or mute the split segment with set_item_audio or set_audio_levels, then add the generated voiceover at the same from_seconds.

Use add_editor_media for background music from My Media or an HTTPS URL with audio_role: "music". Then use set_item_audio or set_audio_levels on the music item to keep it behind speech, usually around -18 to -28 dB with short fades.

Use set_item_layer_order with position: "front" when captions or text must appear above videos. New add_text, add_captions, and generate_captions_from_items overlays are placed on a front layer by default. When top is omitted, new text overlays choose a safe vertical slot to avoid overlapping existing timed text/captions.

Use add_solid for editable backgrounds, panels, dividers, chart bars, route segments, markers, and diagram shapes. Combine it with text and item animations for native motion graphics that remain editable.

Use set_item_motion for continuous frame-driven Remotion motion. Supported types are reveal_x, reveal_y, drift, float, pulse, rotate, zoom, glitch, and typewriter. Timing is relative to the item and remains seek-safe.

Use generate_captions_from_items when the user asks for captions that match the actual narration. It transcribes selected video or audio items, respects timeline placement, source trims, playback rate, and duration, then creates a front-layer captions item or replaces captions_item_id. It needs source items with remote media URLs and an available transcription provider.

Transitions

Use set_item_animation for native editor visual transitions. The operation works on visual timeline items such as videos, images, GIFs, text, and captions. Call get_editor_video first, then pass the real item_id.

Supported transition types are fade, slide, scale, bounce, flip, zoom, glitch, swipe, float, and snap. Use enter for how an item appears and exit for how it leaves. Pass null for enter or exit to clear an existing transition.

Example:

{
  "type": "set_item_animation",
  "item_id": "item-video",
  "enter": { "type": "swipe", "direction": "left", "duration_seconds": 0.25 },
  "exit": { "type": "fade", "duration_seconds": 0.2 }
}

For overlap/crossfade-style visual transitions, use apply_item_transition. It moves the incoming item earlier so it overlaps the outgoing item, optionally preserves the incoming item's original end time, and applies exit/enter animations in one operation.

{
  "type": "apply_item_transition",
  "from_item_id": "item-hook",
  "to_item_id": "item-proof",
  "overlap_seconds": 0.2,
  "exit": { "type": "fade", "duration_seconds": 0.2 },
  "enter": { "type": "swipe", "direction": "left", "duration_seconds": 0.2 }
}

For audio transitions, use set_item_audio fade fields or add built-in SFX with add_sound_effect. Keep overlaps short when source clips include speech, because overlapping video items can also overlap their audio.

Use instructions alongside structured operations when you want the edit request recorded in natural language.

Publishing

Publishing is available through MCP tools because it requires a user-authenticated connection.

Clients must request social:read social:write during OAuth before publishing tools can work.

1. Call list_social_accounts.
2. Call list_editor_media to find the completed My Media item.
3. Call publish_media_to_social with media_id, account_ids, content, and optional title.

Duplicate social account ids are ignored before publishing.

Publishing scope and scheduling

The documented MCP publishing flow accepts completed media from My Media and connected social account ids. It does not expose a scheduled publishing time in this flow. Do not add a scheduling field or promise future publication through publish_media_to_social unless the current tool schema explicitly supports it.

Social publishing is not exposed through the public REST API. Use the MCP connection and scope instructions for publishing, and the REST API documentation for app-owned generation and editing.