Skip to content
RPT AI Video Studio

All docs pages

Reference

MCP tool reference

Generated from the MCP server registry. The list your agent sees in tools/list is shorter: it only shows the tools its token mode and allow-list permit.

POST /api/v1/agent/mcp · 159 tools

Read tools change nothing. Write tools change your workspace; most take a request_key. Paid tools need an execute token; most start paid work at once, and create_quote only prices it.

Orient

7 tools

  • agent_preflight

    Read

    Read-only production preflight: blockers, warnings, budget headroom, video model readiness and the exact next calls for this token.

    Required
    project_id

  • agent_continue

    Read

    Re-evaluate the project and return the next step receipt: status (ready/needs_human/waiting/blocked/complete), the exact next_call and alternatives.

    Required
    project_id
    Optional
    request_key

  • list_video_models

    ReadWorkspace tool

    List the workspace video models with readiness, ratios, resolutions, input modes and a usage hint (create_quote.resolution must be one the chosen model lists).

    Required
    workspace_id

  • list_voices

    ReadWorkspace tool

    List and filter TTS voices (the voice library) by voice model, name, gender, age, language, use case, region and tone; each voice has age/use_cases metadata and sample_available (preview audio exists).

    Required
    none
    Optional
    voice_model, query, gender, language, region, tone, age, use_case, workspace_id, favorite, limit

  • read_external_context

    Read

    Read a redacted, server-authoritative project context and composition schema for an external AI client.

    Required
    project_id

  • get_project_state

    Read

    Read the current project summary.

    Required
    project_id

  • get_studio_state

    Read

    Read planning messages, planning intents and composition revisions.

    Required
    project_id

Projects and folders

10 tools

  • create_project

    WriteNeeds interactiveWorkspace tool

    Create a project and open its agent session from a natural-language brief.

    Required
    workspace_id, title, request_key
    Optional
    product, brief, duration, ratio, preset, video_model, folder_id

  • clone_project

    WriteNeeds interactive

    Clone a project's READY run into a new sibling branch project with the same storyboard, references and keyframes; optionally swap every AI video shot to another video_model (same ratio).

    Required
    project_id, request_key
    Optional
    run_id, title, video_model

  • list_workspace_folders

    ReadWorkspace tool

    List active or archived project folders in a workspace.

    Required
    workspace_id
    Optional
    archived

  • create_folder

    WriteNeeds interactiveWorkspace tool

    Create a durable folder for projects in a workspace.

    Required
    workspace_id, name, request_key

  • rename_folder

    WriteNeeds interactive

    Rename a project folder without changing its projects.

    Required
    folder_id, name, request_key

  • archive_folder

    WriteNeeds interactiveA person confirms

    Archive a project folder safely; projects remain in the workspace and can be moved later.

    Required
    folder_id, confirmed, request_key

  • restore_folder

    WriteNeeds interactive

    Restore an archived project folder.

    Required
    folder_id, request_key

  • move_project_to_folder

    WriteNeeds interactive

    Move a project into a folder or set folder_id to null to remove it from folders.

    Required
    project_id, request_key
    Optional
    folder_id

  • archive_project

    WriteNeeds interactiveA person confirms

    Archive a project safely instead of hard deleting it.

    Required
    project_id, confirmed, request_key

  • restore_project

    WriteNeeds interactive

    Restore an archived project to the workspace.

    Required
    project_id, request_key

Sources

5 tools

  • list_sources

    Read

    List project source links, uploaded references and their analysis state.

    Required
    project_id

  • create_source

    WriteNeeds interactive

    Add a web, video, or pasted-text source.

    Required
    project_id, request_key
    Optional
    url, kind, text, refresh

  • get_source_upload_info

    Read

    Get the authenticated REST upload path for a video reference; no signed secret is returned.

    Required
    project_id, source_id

  • analyze_source

    PaidNeeds execute

    Analyze a fetched source on the server.

    Required
    project_id, source_id, request_key
    Optional
    cap_micros, confirmed

  • select_source_facts

    WriteNeeds interactive

    Apply explicitly confirmed facts and structural style choices from a ready source to the project plan inputs.

    Required
    project_id, source_id, expected_revision, expected_content_hash, request_key
    Optional
    facts, apply_pacing, apply_visual, apply_tone

Asset library

18 tools

  • list_asset_types

    ReadWorkspace tool

    List extensible asset types registered in a workspace.

    Required
    workspace_id

  • create_asset_type

    WriteNeeds interactiveWorkspace tool

    Register a custom asset type with schema, traits and validation metadata.

    Required
    workspace_id, key, label, request_key
    Optional
    schema_version, schema, traits, validation_rules

  • update_asset_type

    WriteNeeds interactiveWorkspace tool

    Edit a custom asset type (label, schema, traits, validation rules); bumps schema_version.

    Required
    workspace_id, type_id, expected_schema_version, request_key
    Optional
    label, schema, traits, validation_rules

  • delete_asset_type

    WriteNeeds interactiveWorkspace tool

    Delete a custom asset type that has no active entities.

    Required
    workspace_id, type_id, request_key

  • list_asset_entities

    ReadWorkspace tool

    List or search asset entities and their current immutable revision. query matches title and attributes, accent-insensitive.

    Required
    none
    Optional
    workspace_id, project_id, query, type_key, include_archived, limit

  • get_asset_entity

    Read

    Read one asset entity, type definition and current revision.

    Required
    entity_id
    Optional
    project_id

  • import_asset_entity

    WriteNeeds interactive

    Create a DRAFT asset entity with attributes filled automatically from an approved Library version (character/product/brand) or a ready project image/video.

    Required
    project_id, request_key
    Optional
    library_version_id, asset_id, type_key, title

  • create_asset_entity

    WriteNeeds interactiveWorkspace tool

    Create an asset entity revision from structured attributes and ready media handles.

    Required
    type_key, title, request_key
    Optional
    workspace_id, project_id, attributes, media_asset_ids, rights, provenance

  • update_asset_entity

    WriteNeeds interactive

    Create the next immutable revision of an asset entity.

    Required
    entity_id, type_key, title, expected_revision, request_key
    Optional
    attributes, media_asset_ids, rights, provenance, project_id

  • approve_asset_entity

    WriteNeeds interactive

    Approve the current asset entity revision after rights are confirmed.

    Required
    entity_id, expected_revision, request_key
    Optional
    project_id

  • approve_asset_entities

    WriteNeeds interactive

    Approve several asset entities in one call; each still needs confirmed rights.

    Required
    items, request_key
    Optional
    project_id

  • archive_asset_entity

    WriteNeeds interactive

    Delete (archive) an asset entity. History is kept; archived entities cannot be mapped or quoted.

    Required
    entity_id, request_key
    Optional
    project_id

  • restore_asset_entity

    WriteNeeds interactive

    Restore an archived asset entity.

    Required
    entity_id, request_key
    Optional
    project_id

  • list_scene_asset_bindings

    Read

    Read asset mappings for a composition revision.

    Required
    project_id, composition_revision_id

  • suggest_scene_asset_mapping

    Read

    Read-only auto-match: finds scenes whose narration, visual, subject or on-screen text mention an asset's title or aliases.

    Required
    project_id, composition_revision_id
    Optional
    entity_ids

  • preview_scene_asset_mapping

    Read

    Preview scene asset mapping changes without writing, calling providers or reserving budget.

    Required
    project_id, composition_revision_id, mappings

  • apply_scene_asset_mapping

    WriteNeeds interactive

    Persist deterministic asset bindings to scenes.

    Required
    project_id, composition_revision_id, mappings, request_key

  • remove_scene_asset_mapping

    WriteNeeds interactive

    Remove asset bindings from a composition revision by binding id or scene_index + role.

    Required
    project_id, composition_revision_id, bindings, request_key

Plan the storyboard

14 tools

  • get_director_artifacts

    Read

    Read validated script, storyboard, approved story identities, asset list and generation plan.

    Required
    project_id

  • start_planning

    PaidNeeds execute

    Start the server-side planning job. Runs immediately (no price approval); the reserved estimate is recorded in the budget ledger.

    Required
    project_id, expected_revision, message, request_key
    Optional
    routing, confirmed

  • submit_external_composition

    Write

    Submit a typed storyboard/composition authored by an external AI client.

    Required
    project_id, expected_project_revision, expected_composition_revision, context_handle, context_hash, composition, client_task_id, request_key
    Optional
    provenance, client_kind, external_model

  • propose_storyboard

    WriteNeeds interactive

    Preview a complete revised composition with rationale; requires user confirmation, does not generate or approve media.

    Required
    project_id, composition, rationale

  • create_draft_change

    WriteNeeds interactive

    Preview a draft scene text change; requires user confirmation.

    Required
    project_id, scene_index, field, value

  • get_scene_detail

    Read

    Read a scene from the latest composition.

    Required
    project_id, scene_index, composition_id

  • get_plan_nodes

    Read

    Read the per-scene pipeline status of the plan: outline -> expanded -> lint -> keyframe -> quoted -> generated -> locked, per chapter counts, scenes an AI job is still writing (busy), and the pending outline.

    Required
    project_id

  • plan_outline

    PaidNeeds execute

    Phase 1 of long-film planning: the AI writes only an outline (logline, world, cast, chapters and one line per scene), not the full scenes.

    Required
    project_id, expected_revision, message, request_key
    Optional
    scene_count, confirmed

  • quote_outline_chapters

    Read

    Price writing the scene lines of a chapter plan, one paid job per chapter.

    Required
    project_id, intent_id
    Optional
    chapters

  • write_outline_chapters

    PaidNeeds execute

    Phase 1b of a long film: the AI writes the scene lines of each chapter of an approved chapter plan, one paid job per chapter.

    Required
    project_id, intent_id, request_key
    Optional
    chapters, cap_micros, confirmed

  • approve_outline

    WriteNeeds interactiveA person confirms

    Approve the pending outline (intent_id from get_plan_nodes outline.intent_id; for a chapter plan only once every chapter has its scenes): creates the plan skeleton as the next composition revision, one scene per outline line.

    Required
    project_id, intent_id, request_key, confirmed

  • quote_expand

    Read

    Price an expand: which scenes would be written, in how many batches, and the total reserve.

    Required
    project_id, expected_revision
    Optional
    scope, chapter, shot_ids, reexpand

  • expand_scenes

    PaidNeeds execute

    Phase 2: the AI writes the full scenes (visual, narration, subtitle, speech, director) for the chosen scenes, one paid job per batch of 5 with the world, cast and neighbouring scenes as context.

    Required
    project_id, expected_revision, request_key
    Optional
    scope, chapter, shot_ids, reexpand, cap_micros, confirmed

  • patch_scenes

    WriteNeeds interactive

    Field-level edit of existing scenes without resending the whole composition: patches = [{index or shot_id, set: {title, visual, narration, subtitle, overlay, speech_window, director, transition, keyframes}}]. preview=true returns the diff and saves nothing.

    Required
    project_id, expected_revision, patches, request_key
    Optional
    preview

Quote and approve

3 tools

  • create_quote

    PaidNeeds execute

    Create and store a quote (price per shot and total) from a current composition; does not submit media.

    Required
    project_id, composition_id, request_key
    Optional
    resolution, candidates, voice, voice_model, image_model, image_size, music_model, music_prompt, subtitles, audio_mode, audio_mix, phase, rendition_ratios, base_run_id, force_nodes, regenerate_reason

  • approve_production

    PaidNeeds execute

    Submit production for a stored quote through the durable outbox, with no price approval step: it starts immediately.

    Required
    project_id, quote_id, expected_content_hash, request_key
    Optional
    cap_micros, confirmed

  • confirm_tool

    WriteNeeds interactive

    Execute a previously previewed agent tool with its short-lived confirmation token.

    Required
    session_id, confirmation_token, request_key

Standalone media

3 tools

  • quote_media_task

    WriteNeeds interactiveWorkspace tool

    Quote one standalone voice, music, sound-effect or image task without a project storyboard.

    Required
    workspace_id, kind, request_key
    Optional
    duration_seconds, resolution, route, reference_asset_id, text, voice, language, style, prompt, model, size, ratio, operation, source_asset_id, mask_asset_id, reference_asset_ids

  • generate_media_task

    PaidNeeds executeWorkspace tool

    Run one quoted voice, music, sound-effect or image task; it starts at once.

    Required
    workspace_id, task_id, request_key
    Optional
    confirmation_digest, cap_micros, confirmed

  • get_media_task

    ReadWorkspace tool

    Read one standalone voice or image task: state, error_code and, when READY, an authenticated download_path.

    Required
    workspace_id, task_id

Production

5 tools

  • get_production_state

    Read

    Read quotes, approvals, runs, tasks and provider progress for the project.

    Required
    project_id

  • get_run_progress

    Read

    Read latest or selected run progress.

    Required
    project_id
    Optional
    run_id

  • resume_run

    PaidNeeds execute

    Resume a stopped run (PAUSED_BUDGET/NEEDS_ATTENTION) under the same approval, at most 3 attempts per task.

    Required
    project_id, run_id, approval_id, action, request_key
    Optional
    confirmed

  • list_available_media

    Read

    List checksum-verified media available now: video artifacts (kind video), including completed clips from an incomplete, paused, failed, or running production, and finished keyframe stills (kind keyframe, e.g. from a KEYFRAMES_READY run).

    Required
    project_id
    Optional
    run_id

  • get_media_asset

    Read

    Return metadata and an authenticated download path for one verified video artifact or keyframe still.

    Required
    project_id, artifact_id, name

Review

3 tools

  • get_review_state

    Read

    Read legacy review rounds/comments and per-run delivery readiness.

    Required
    project_id

  • decide_review

    WriteNeeds interactiveA person confirms

    Legacy, optional: record an approve/request_changes note on an open review round.

    Required
    project_id, run_id, decision, confirmed, request_key
    Optional
    note, quality_checks

  • save_feedback

    WriteNeeds interactive

    Preview saving feedback to an open review; requires user confirmation.

    Required
    project_id, run_id, text

Delivery

4 tools

  • prepare_delivery

    WriteNeeds interactive

    Prepare the delivery manifest for a READY run (no human QC gate; the review round is closed automatically).

    Required
    project_id, run_id, request_key

  • issue_delivery

    WriteNeeds interactiveA person confirms

    Build and issue the delivery package for a READY run through the existing private storage path.

    Required
    project_id, run_id, confirmed, request_key

  • list_deliveries

    Read

    List deliveries for the current project.

    Required
    project_id

  • get_delivery_download

    Read

    Audit and return private download metadata for an issued delivery; no signed secret is returned.

    Required
    project_id, delivery_id, request_key

Studio view

2 tools

  • open_workspace_view

    WriteNeeds interactive

    Navigate to an allowlisted workspace view.

    Required
    project_id, view
    Optional
    filter, query

  • focus_scene

    WriteNeeds interactive

    Focus a scene in the Canvas.

    Required
    project_id, scene_index

Brand and product library

4 tools

  • list_library

    ReadWorkspace tool

    List brand/product/character library items and their versions in a workspace.

    Required
    workspace_id

  • save_library_version

    WriteNeeds interactiveWorkspace tool

    Save a new DRAFT version of a library item (brand, product or character).

    Required
    workspace_id, kind, content, request_key
    Optional
    item_id, expected_version

  • approve_library_version

    WriteNeeds interactiveWorkspace tool

    Approve a library version after rights are confirmed; only approved versions can be applied to projects.

    Required
    workspace_id, version_id, expected_content_hash, request_key

  • apply_library_to_project

    WriteNeeds interactive

    Attach up to three approved library versions (one brand, one product, one character) to a project plan.

    Required
    project_id, expected_revision, version_ids, request_key

Story bible

4 tools

  • list_story_bible

    ReadWorkspace tool

    List story bible entities (character, costume, prop, location, creature, crowd, voice, style, constraint, world) and versions.

    Required
    workspace_id

  • save_story_bible_version

    WriteNeeds interactiveWorkspace tool

    Save a new DRAFT story bible version (omit bible_id to create the entity).

    Required
    workspace_id, kind, content, request_key
    Optional
    bible_id, expected_version

  • approve_story_bible_version

    WriteNeeds interactiveWorkspace tool

    Approve a story bible version so shots can reference it.

    Required
    workspace_id, version_id, expected_content_hash, request_key

  • apply_story_bible_to_project

    WriteNeeds interactive

    Attach approved story bible versions to a project (replaces its current set).

    Required
    project_id, expected_revision, request_key
    Optional
    version_ids

Project data and scenes

15 tools

  • list_projects

    ReadWorkspace tool

    List projects of a workspace (newest first), optionally by folder or archived.

    Required
    workspace_id
    Optional
    folder_id, archived

  • update_project

    WriteNeeds interactive

    Update a project's title, product, brief, duration, ratio, preset, overrides/routing/speech or its attached assets (asset_ids REPLACES the attached set, no project limit; use list_project_assets for ids, including edited images).

    Required
    project_id, expected_revision, request_key
    Optional
    title, product, brief, duration, ratio, preset, overrides, routing, speech, asset_ids

  • get_workspace

    ReadWorkspace tool

    Read the workspace (id, name, your role).

    Required
    workspace_id

  • import_source_image

    WriteNeeds interactiveA person confirms

    Import one image from a fetched source snapshot (index 0-11) into the project as a ready asset.

    Required
    project_id, source_id, index, expected_revision, request_key, confirmed

  • list_project_assets

    Read

    List every ready image/video asset of the project, attached or not (ids, mime, size, dimensions, source_asset_id/operation/params lineage for edited images, attached flag).

    Required
    project_id

  • list_presets

    ReadWorkspace tool

    List creative presets (format, style) the project can start from.

    Required
    workspace_id

  • get_shot_graph

    Read

    Read the shot graph: shots, dependencies, approved identities and reuse links.

    Required
    project_id

  • edit_composition

    WriteNeeds interactive

    Save the next composition revision of a project from a full Composition object (same body as the Canvas editor).

    Required
    project_id, expected_revision, composition, request_key

  • compile_scene_prompt

    Read

    Free, read-only: compile one scene of a composition into the exact prompt a quote would freeze.

    Required
    project_id, composition_id, scene_index

  • import_scene_prompt

    Read

    Free, read-only, no AI: read a pasted manual prompt of one scene into structured shot fields.

    Required
    project_id, composition_id, scene_index
    Optional
    raw_prompt, shot

  • add_scene

    WriteNeeds interactive

    Add one blank scene to the plan (new composition revision; creates no paid task). index = position of the new scene (0 = first, omit = append); it joins the chapter of the scene before it and copies that scene's kind, model and duration.

    Required
    project_id, expected_revision, request_key
    Optional
    index, title

  • duplicate_scene

    WriteNeeds interactive

    Duplicate scene `index` right after itself (new composition revision; creates no paid task).

    Required
    project_id, expected_revision, index, request_key
    Optional
    title

  • delete_scene

    WriteNeeds interactive

    Delete scene `index` (new composition revision; the earlier revision stays in history).

    Required
    project_id, expected_revision, index, request_key

  • get_run_script

    Read

    Read the approved script/storyboard snapshot a production run was built from.

    Required
    project_id, run_id

  • get_run_provenance

    Read

    Read the provenance record of a run (models, prompts, sources, rights).

    Required
    project_id, run_id

Media library

8 tools

  • list_media_library

    ReadWorkspace tool

    List the workspace media library: images, video, audio and documents with favorite, upscaled and archived flags.

    Required
    workspace_id
    Optional
    scope, kind, favorite, upscaled, archived, resolution, ratio, project_id, created_from, created_to, q, sort, limit, offset

  • mark_media

    WriteNeeds interactiveWorkspace tool

    Favorite/unfavorite or archive/unarchive up to 100 media library items (reversible, free).

    Required
    workspace_id, media_ids, action, request_key

  • set_voice_favorite

    WriteNeeds interactiveWorkspace tool

    Favorite or unfavorite a voice of the voice library (names from list_voices) for the calling user.

    Required
    workspace_id, voice, favorite, request_key

  • add_media_to_project

    WriteNeeds interactive

    Attach library media (ids from list_media_library) to a project as assets.

    Required
    project_id, media_ids, request_key

  • list_videos

    ReadWorkspace tool

    List the workspace Videos library: every generated video (render, clip, edit, task) newest first with title, prompt, project, model, size, status (active|delivered|deleted), in_use (why delete_videos would refuse it now) and days_left for deleted ones.

    Required
    workspace_id
    Optional
    project_id, model, kind, status, created_from, created_to, q, cursor, limit

  • delete_videos

    WriteNeeds interactiveA person confirmsWorkspace tool

    Soft delete up to 100 videos (ids from list_videos).

    Required
    workspace_id, ids, request_key, confirmed

  • restore_videos

    WriteNeeds interactiveWorkspace tool

    Restore deleted videos (ids from list_videos status=deleted) inside their 7-day window.

    Required
    workspace_id, ids, request_key

  • create_asset_element

    WriteNeeds interactiveWorkspace tool

    Quick-create an element: ready media assets plus a unique @name and a description; rights_confirmed is the human's decision.

    Required
    workspace_id, name, media_asset_ids, request_key
    Optional
    description, type_key, rights_confirmed

Explore

4 tools

  • list_explore_items

    ReadWorkspace tool

    Explore: the workspace's finished videos as cards plus skill cards.

    Required
    workspace_id
    Optional
    category, sub_category, q, limit

  • get_explore_board

    Read

    Read the making-of board of a finished project: reference images, storyboard shots in order and the final video.

    Required
    project_id

  • reverse_source_video

    Read

    Reverse an analyzed reference video source into a scene board (beats with shot type, camera, composition, transition, text style), hook/pacing/palette/caption/audio/CTA style and detected facts.

    Required
    project_id, source_id

  • create_project_from_reverse

    WriteNeeds interactive

    Start a new project in the same workspace from a reversed source board: brief = scene outline, ratio/duration of the video, source style (pacing, visual, tone) pre-selected.

    Required
    project_id, source_id, request_key
    Optional
    title

Takes

5 tools

  • list_takes

    Read

    List generated takes per shot with scores, locks and open batches.

    Required
    project_id

  • assess_take

    WriteNeeds interactive

    Score a take 0-5 on identity, framing, motion, lighting and audio with written evidence.

    Required
    project_id, artifact_id, scores, evidence, request_key

  • lock_take

    WriteNeeds interactive

    Lock the chosen take of a shot (artifact_id) into a composition revision, or null to unlock.

    Required
    project_id, composition_id, expected_revision, shot, artifact_id, request_key

  • prepare_take_batch

    WriteNeeds interactive

    Freeze the price of extra takes (1-3) for one shot.

    Required
    project_id, quote, shot, reason, request_key
    Optional
    takes

  • approve_take_batch

    PaidNeeds execute

    Submit a prepared take batch (extra takes) immediately.

    Required
    project_id, batch_id, expected_hash, request_key
    Optional
    cap_micros, confirmed

Review comments

4 tools

  • add_review_comment

    WriteNeeds interactive

    Add a review comment to a run, optionally pinned to a shot and timestamp.

    Required
    project_id, run_id, text, request_key
    Optional
    shot, timestamp_ms

  • resolve_review_comment

    WriteNeeds interactive

    Mark a review comment resolved.

    Required
    project_id, comment_id, request_key

  • reopen_review_comment

    WriteNeeds interactive

    Reopen a resolved review comment.

    Required
    project_id, comment_id, request_key

  • reopen_review_round

    WriteNeeds interactive

    Reopen the review of a run after an approval so changes can be requested again.

    Required
    project_id, run_id, request_key

Delivery gallery

5 tools

  • revoke_delivery

    WriteNeeds interactiveA person confirms

    Revoke an issued delivery so its package can no longer be downloaded.

    Required
    project_id, delivery_id, reason, request_key, confirmed

  • search_deliveries

    ReadWorkspace tool

    Search the workspace delivery gallery (filters: search, project_id, sku, branch_id, date_from/date_to YYYY-MM-DD, status, ratio).

    Required
    workspace_id
    Optional
    page, page_size, search, project_id, sku, branch_id, date_from, date_to, status, ratio

  • list_delivery_options

    ReadWorkspace tool

    List the deliveries that can be bundled into a batch package.

    Required
    workspace_id

  • list_delivery_batches

    ReadWorkspace tool

    List issued multi-delivery batch packages.

    Required
    workspace_id

  • create_delivery_batch

    WriteNeeds interactiveWorkspace tool

    Bundle up to 50 issued deliveries into one downloadable batch package.

    Required
    workspace_id, title, delivery_ids, request_key

Branches

6 tools

  • list_project_branches

    Read

    List the branches of a project (main + variants). project_id is the ROOT project of the branch family.

    Required
    project_id

  • create_project_branch

    WriteNeeds interactive

    Create a branch from a finished run: a copy of its plan with shot edits that answer open review comments. project_id is the ROOT project of the branch family. edits = [{shot, title?, visual?, narration?, subtitle?, overlay?}].

    Required
    project_id, parent_branch_id, parent_run_id, name, comment_ids, edits, request_key

  • rename_project_branch

    WriteNeeds interactive

    Rename a branch. project_id is the ROOT project of the branch family.

    Required
    project_id, branch_id, name, request_key

  • archive_project_branch

    WriteNeeds interactiveA person confirms

    Archive a branch (history is kept). project_id is the ROOT project of the branch family.

    Required
    project_id, branch_id, request_key, confirmed

  • restore_project_branch

    WriteNeeds interactive

    Restore an archived branch. project_id is the ROOT project of the branch family.

    Required
    project_id, branch_id, request_key

  • promote_project_branch

    WriteNeeds interactiveA person confirms

    Make a branch the primary one of its project family. project_id is the ROOT project of the branch family.

    Required
    project_id, branch_id, request_key, confirmed

Extend and translate

4 tools

  • prepare_extension

    WriteNeeds interactive

    Prepare an extension of a finished run: extracts the last frame of its final clip as the continuity boundary.

    Required
    project_id, parent_run_id, expected_content_hash, request_key

  • get_extension

    Read

    Read one prepared extension (intent) with its boundary frame metadata and result.

    Required
    project_id, intent_id

  • create_extension

    WriteNeeds interactive

    Create the extension project from a prepared intent: a new 3-10 s scene that continues from the boundary frame. boundary_confirmed is the human's check of the frame.

    Required
    project_id, intent_id, name, title, visual, duration_ms, video_model, continuity_notes, request_key
    Optional
    narration, boundary_confirmed

  • create_locale

    WriteNeeds interactive

    Create a localized version (translated narration/subtitles, new voice) of a finished run as a new project. shots = [{shot, narration, subtitle, speech_window?}].

    Required
    project_id, parent_run_id, expected_content_hash, name, language, shots, request_key
    Optional
    voice, voice_model, transcript_confirmed

Voices and spreadsheet import

6 tools

  • quote_voice_sample

    ReadWorkspace tool

    Price of one voice audition (fixed upper bound).

    Required
    workspace_id

  • create_voice_sample

    PaidNeeds executeWorkspace tool

    Generate a short TTS audition sample (<=240 chars).

    Required
    workspace_id, voice, text, request_key
    Optional
    language, style, pronunciations, cap_micros, confirmed

  • get_voice_sample

    ReadWorkspace tool

    Read one voice sample: state (QUEUED, READY, FAILED...) and, when READY, its audio path.

    Required
    workspace_id, sample_id

  • get_import_template

    ReadWorkspace tool

    Return the Excel template (columns + base64 .xlsx) for bulk video requests.

    Required
    workspace_id

  • preview_import

    ReadWorkspace tool

    Parse a filled Excel workbook (base64, <=4 MB, <=100 rows) into rows without creating anything.

    Required
    workspace_id, xlsx_base64

  • import_project_row

    WriteNeeds interactiveWorkspace tool

    Create one project from a previewed Excel row (fields as returned by preview_import) and download its public image_urls. rights_confirmed is the human's confirmation that they may use the text and images.

    Required
    workspace_id, fields, rights_confirmed, request_key
    Optional
    image_urls

Upload references

4 tools

  • create_asset_upload_intent

    WriteNeeds interactive

    Register an image/video upload for a project (no limit on the number of files; each image <=50 MB).

    Required
    project_id, filename, mime, size, sha256, request_key

  • upload_asset_content

    WriteNeeds interactive

    Upload the bytes (base64, exactly the registered size) of a registered asset.

    Required
    project_id, asset_id, content_base64, request_key

  • finalize_asset_upload

    WriteNeeds interactive

    Verify the uploaded bytes (checksum, size, decodable media) and mark the asset ready for use. attach=true also APPENDS it to the project's attached references (keeps the others; no expected_revision needed) and returns attached, project_revision and asset_ids.

    Required
    project_id, asset_id, request_key
    Optional
    attach

  • abandon_asset_upload

    WriteNeeds interactive

    Cancel an upload that is not attached to the project plan.

    Required
    project_id, asset_id, request_key

Image editing

2 tools

  • edit_image

    WriteNeeds interactive

    Free, instant edit of a project image (crop, rotate, flip, resize, split into a grid) that creates a new asset; the source is never overwritten.

    Required
    project_id, asset_id, operation, params, request_key

  • save_media_task_as_asset

    WriteNeeds interactiveWorkspace tool

    Register the finished image of a READY media task (get_media_task state=READY) as a new project asset.

    Required
    workspace_id, task_id, request_key
    Optional
    project_id, filename

Video editing

11 tools

  • edit_trim

    WriteNeeds interactive

    Keep only start_s..end_s of the video (seconds).

    Required
    project_id, request_key
    Optional
    asset_id, run_id, params, executor

  • edit_reframe

    WriteNeeds interactive

    Change the aspect ratio: fill crops around focus_x/focus_y (0..1), fit adds black bars.

    Required
    project_id, request_key
    Optional
    asset_id, run_id, params, executor

  • edit_color

    WriteNeeds interactive

    Colour look: preset plus exposure (-1..1), contrast (0.5..1.5), saturation (0..2).

    Required
    project_id, request_key
    Optional
    asset_id, run_id, params, executor

  • edit_loudness

    WriteNeeds interactive

    Normalise loudness to target_lufs with a true-peak ceiling (two-pass EBU R128).

    Required
    project_id, request_key
    Optional
    asset_id, run_id, params, executor

  • edit_speed

    WriteNeeds interactive

    Play the whole video faster or slower (0.5..2x), audio pitch kept.

    Required
    project_id, request_key
    Optional
    asset_id, run_id, params, executor

  • edit_fade

    WriteNeeds interactive

    Fade picture and sound in from black at the start and/or out at the end.

    Required
    project_id, request_key
    Optional
    asset_id, run_id, params, executor

  • edit_text_overlay

    WriteNeeds interactive

    Burn one line of text (top, center or bottom) for the whole video or start_s..end_s.

    Required
    project_id, request_key
    Optional
    asset_id, run_id, params, executor

  • measure_media

    WriteNeeds interactive

    Measure duration, size, loudness (LUFS, true peak) and black/silent stretches; makes no new file.

    Required
    project_id, request_key
    Optional
    asset_id, run_id, params, executor

  • get_edit_options

    ReadWorkspace tool

    List the video edit tools (params_schema, cost_class, executors) and which executors are online for you: cloud_ffmpeg is always online; craft_local lists your open Local Studio apps. queued_for_local counts your jobs waiting for an app.

    Required
    workspace_id

  • get_edit_job

    Read

    Read one edit job: state QUEUED|RUNNING|READY|FAILED, executor, error_code, and when READY result {asset_id, diff, before, after, previews}.

    Required
    project_id, job_id

  • list_edit_jobs

    Read

    List the project's latest 30 edit jobs, newest first.

    Required
    project_id

Clip batches

3 tools

  • create_media_batch

    PaidNeeds executeWorkspace tool

    Make many video clips from one table (CSV text, a base64 .xlsx, or rows = a list of {column: value} objects), at most 100 rows. template uses {{column}} variables; without a template each row's prompt column is the prompt.

    Required
    workspace_id, request_key
    Optional
    csv, xlsx_base64, rows, template, route, duration_seconds, ratio, resolution, reference_asset_id, project_id, start

  • get_media_batch

    ReadWorkspace tool

    Read one clip batch: status (draft, running, paused, completed, cancelled), per-state counts (pending, queued, running, ready, attention, cancelled), progress, the stored estimate and, once any clip is ready, a download_path to the ZIP.

    Required
    workspace_id, batch_id

  • list_media_batch_items

    ReadWorkspace tool

    List the items of a clip batch in row order: row, task_id, state (pending, queued, running, ready, needs_attention, cancelled), error_code, prompt and per-item price; a ready item also has download_path.

    Required
    workspace_id, batch_id
    Optional
    state, limit, offset