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 small inline base64 or data URL payloads.
• 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. If an agent has a local file, it should either expose it through a temporary HTTPS URL and call upload_editor_media_from_url, or use the REST POST /api/v1/editor/media multipart upload endpoint.

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
• apply_item_transition
• split_item
• set_item_transform
• move_item_to_track
• set_item_layer_order
• 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. 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 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.