Martini

Create multiple planned shot nodes and run approved generations for them. Requires one user approval for the whole batch. When the new shots should match existing shots, first read their full prompts and model with get_asset and mirror their prompt structure across the batch. To position, prefer per-node placement (rightOf/below/near an anchor, or bin "new:<name>" to group a set) over computing coordinates.

create_nodes_and_generate

Create a new Martini project for the authenticated user. Optionally pass a teamId to create a private team project. After creating an empty project, use create_canvas before adding board content.

create_project

Create one canvas text note without starting generation or spending credits. Send exactly one full content representation: content for plain text, or richContent when formatting matters. Position uses absolute canvas coordinates.

create_text_note

Create a reusable text variable on a canvas. Variables are prompt text snippets, not visual labels for board organization. Reference it in prompts as @{variableId:variableName}; it expands to its value at generation time. Names are unique within the project — a numeric suffix is auto-appended on collision.

create_variable

Crop operations on completed images — deterministic pixel extraction, no generation, no credits. Action "create" authors 1-16 cropped child image nodes from a source image (rects in natural pixels of the source; read its width/height with get_asset first); crops land on the board as completed image nodes (operation "crop") parented to the source. Action "recrop" re-points an existing crop node at a new rect of its PARENT image; the previous crop is kept in the node's cropRevisions history. Action "restore" re-points a crop node at an earlier cropRevisions entry (find revision IDs with get_asset).

crop_image

Delete empty DRAFT nodes (never generated or uploaded media) from the board: the draft record, its position, draft settings, and display name are removed, bin membership and variation stacks are tidied. Nodes with media are refused — remove those in the Martini app. Yjs-only; stored media files are never touched. Use dryRun to preview.

delete_nodes

Delete empty canvas bins. A bin that still contains nodes is refused with its member list — move members out first (move_nodes / move_node_to_bin). Nested empty bins can be deleted with their parent in the same call. Use dryRun to preview.

delete_bins

Delete text notes from the board (the note record and its position; bin membership is tidied). Use dryRun to preview.

delete_text_notes

Read-only diagnostics for a camera-control draft or rendered node. Returns validation status, expected guide branch, related media HEAD checks, guide failure metadata, raw cameraMotion metadata, and draft settings.

diagnose_camera_motion_guide

Duplicate asset nodes by reference: new nodes pointing at the SAME stored media (nothing is re-generated, re-uploaded, or copied in storage — exactly like project duplication). Fresh shot numbers; draft settings and display names are copied; parent/variation lineage is not. Use for "same assets, different arrangement" views, e.g. mirroring shots onto a second canvas sorted another way. targetCanvasId defaults to the source canvas; placement (incl. bin "new:<name>" + columns) applies to every copy.

duplicate_nodes

THE library write tool — applies an ordered batch of library commands (the same seam the Martini UI uses). Everything except bulk file ingestion (import_library_assets) goes through here. Commands (each { type, ...fields }; creates auto-fill ids/slugs/revs/timestamps — pass only what you know): - collection.create {collection:{name, type?, folder?, tags?}} — a collection is one reusable subject (character, prop, location, style) - collection.rename {id,name} · collection.delete {id} (soft, cascades to assets) · collection.restore {id} · collection.move {id,folder} (folder path or null=unfiled) · collection.setTags {id,tags} · collection.setHero {id,assetId|null} · collection.setDescription {id,description} (free-form notes shown under the title) - folder.create {path} ('Night Shift' or nested 'Night Shift/Cast') · folder.rename {path,next} · folder.delete {path} (collections become unfiled) - asset.create {asset:{collectionId, kind:'image'|'video'|'audio'|'model3d'|'text', name, src (https URL; '' for text), textValue? (text fragments)}} — prefer import_library_assets for bulk/external files - asset.rename {id,name} · asset.move {ids,collectionId} · asset.delete {ids} · asset.restore {ids} - asset.setValue {id,key,value} — set a property value (key from get_library; select values are option IDs; null clears) - asset.update {id,patch:{src?,textValue?,...}} — patch.src replaces media and appends a version to history automatically - asset.setCurrentVersion {id,versionId} — restore an older version (pointer move, never rewrites history) - property.create {property:{label, type:'select'|'text'|'number'|'checkbox', options?:[{value,color?}], config?:{multiline?,precision?}}} - property.rename {key,label} · property.delete {key} · property.restore {key} · property.addOption {key,option:{value,color?}} · property.removeOption {key,optionId} (hard delete) · property.renameOption {key,optionId,value} - tag.addToVocab {tags} · view.save {view:{name,definition:{collectionId,layout,filters?,groupBy?,sort?,axes?}}} · view.update {id,name?,definition?} · view.delete {id} - link.setProject {projectId,collectionIds} — FULL REPLACEMENT of the project's enabled set; prefer link_library_to_project for add/remove - batch {label, commands:[…]} groups sub-commands under one label · asset.move accepts perAssetTarget {assetId→collectionId} for per-asset destinations · folder.delete accepts restoreCollections {collectionId→path|null} to re-file displaced collections - Cross-referencing within one batch: supply your OWN ids (any unique short string) on creates instead of relying on autofill — e.g. collection.create {collection:{id:"cast0001", name:…}} then asset.create {asset:{collectionId:"cast0001", …}} in the same commands array. createdIds in the response lists the ids assigned to your creates; a create that hits an existing live id is a no-op revive (nothing overwritten) — confirm with a read when reusing ids. - Value semantics: asset.setValue with a value whose type mismatches the property is a SILENT no-op (revs unchanged); unknown property keys are written as-is (legacy attrs) — read get_library properties first. property.removeOption hard-deletes the option but does NOT clear asset attrs still holding its id — re-set or clear those yourself. Rules: never modify collections with sample:true (community samples — copy what you need instead). Deletes are soft and restorable except property options. collection.delete cascades to its assets but collection.restore does NOT restore them — get_library_collection on the deleted collection returns the asset.restore command to pair with it. collection.setHero should point at an image or video asset. Unknown ids are no-op successes: `applied` counts commands executed, `revs` lists rows that actually changed — check revs to confirm a mutation landed.

edit_library

Start a durable Premiere Pro XMEML bundle export from current collaborative timeline state. The ZIP contains XML plus original media. Returns immediately with an exportId; poll get_timeline_delivery_status. operationId makes identical retries safe, but an interrupted worker requires a new operationId.

export_timeline_xml

Extract a durable PNG still from a completed video asset. By default this creates only a reusable R2-backed frame file, not a visible canvas node. Optionally attach the frame to a draft start/end slot or create a visible video-frame image node.

extract_video_frame

Generate media for an existing shot after the user has approved the model, prompt, target shot, count, and estimated cost. When the result should match existing shots, first read their full prompts and model with get_asset and mirror their prompt structure.

generate

Generate existing draft nodes from their staged settings (model, prompt, frames, references). First call without batchApproval: Martini returns a server-computed olive estimate and generates nothing. Present the plan and total to the user, then re-call with batchApproval and the returned planHash. Submission has per-node error isolation; poll with get_jobs. Board variables expand at submit time.

generate_nodes

Get one asset with full stored metadata, deep links, and its canvas position. Use this after get_board_assets or get_canvas when you need deep detail on a specific node — e.g. reading reference shots' full prompts and model before generating shots that should match them (promptPreview in list results is truncated). asset.modelId is the model that generated the asset; draftModelId/draftModelName are the node's currently configured draft model — use those for assets without modelId. Set includeDraftSettings true only when you need the complete generation configuration. Use the imageUrl field for referenceImages — do not construct URLs from the id.

get_asset

Return a short-lived presigned URL for downloading a completed asset file. Use this when the user wants to save an asset to disk or needs a direct file URL for export/download workflows. Fetch the returned URL promptly before it expires.

get_asset_download_url

Primary board context reader for agents. Resolves a project by projectId or projectQuery, then returns canvases with deep links, Library collections enabled for the project, board variables (with truncated value previews), and direct canvas children for one canvas. Prefer this before separate canvas, Library, or variable lookup tools.

get_board_overview

Get one canvas with its deep link, canvas-scoped asset summaries, and positions. Older projects may also return legacy subject and collection summaries; use get_library or get_library_collection for current reusable Library media. Use get_asset for full per-asset detail. If canvasId is omitted, returns a deterministic canvas.

get_canvas

Get direct spatial children of a canvas or bin. Canvas parent responses include the canvas deep link. Results can include bins, asset/job nodes, legacy subject or collection nodes, and text notes. There are TWO independent grouping systems: "bins" (spatial canvas bins, membership via a node's binId) and "libraryBins" (left-panel media folders, membership via an asset node's folderId). When include has "bins", the canvas response returns both; each asset node also carries folderId. Use get_library_collection for the semantic membership and assets of a current Library collection.

get_canvas_children

List review comment threads on a project (canvas pins + timeline markers). Threads are flat: the root carries the anchor and resolved state; replies share its threadId. Threads mentioning you (mentions:"me") are your work queue — read them, do the work, reply with add_comment, then resolve_comment. Timeline anchors are in ticks (48000/s); clip anchors ride edits via stable clip ids and fall back to fallbackTicks when the clip is gone.

get_comments

Get one generation job by jobId, or list all generation jobs for a project by projectId. Provide exactly one of jobId or projectId.

get_jobs

One library collection in depth: its assets (with property values and version history), text fragments as ready-to-paste @{id:name} prompt chips, and which projects have it enabled.

get_library_collection

The workspace library: reusable collections (characters, props, locations, styles — each holding image/video/text variant assets), folders, typed properties, saved views, and tags. Call this first to orient before any library work. Pass projectId to also see which collections that project has enabled for prompt references. Use get_library_collection for one collection's assets.

get_library

List models, resolve a natural-language model/provider name, or inspect one exact model. Use query for requests like "GPT image" or "Kling"; use modelId when you already know the exact ID; omit both to list models.

get_models

Read one canvas text note. content is a plain-text convenience value; richContent preserves supported note styling (block size/alignment and span emphasis/color). When copying or editing a styled note, preserve richContent and send only richContent back. Nested list or quote structure is flattened to soft line breaks. Discover nodeId with get_board_overview or get_canvas_children include ["textNotes"].

get_text_note

Hear the selected cut through measurements: composes the current original-media audio mix without video encoding, then returns an annotated waveform, dead-air intervals, integrated loudness, true peak, and loudness range. The browser uses AAC proxies, so use browser playback to confirm audibility/sync and this tolerance-based report for mix QA.

get_timeline_audio_report

Read compact sequence, track, clip, gap, and relevant asset context for timeline edits. Prefer this before apply_timeline_edit, then pass the returned revisionToken as ifRevision so a concurrent human edit produces a clean conflict instead of a stale overwrite.

get_timeline_context

Poll a durable timeline render or Premiere XML export. Completed responses include a short-lived download URL and stable artifactId. WORKER_INTERRUPTED means resubmit the original tool call with a new operationId.

get_timeline_delivery_status

Get full detail for a single variable: name, value, color, bin, and absolute canvas position.

get_variable

Create a root-level bin around existing root-level asset/job nodes. Nodes keep their current visual canvas positions; stored positions become bin-relative. To organize the children into a tidy grid, call layout_bin_children after grouping.

group_nodes_into_bin

Bulk-ingest media into a library collection: external file URLs (from any asset-management system — images are mirrored into Martini storage) and/or existing Martini project assets (captured by reference with provenance, no copy). Creates the collection in the same call when newCollection is given. Set names and property values per item as you ingest. Per-item failures are reported without failing the batch. For local file BYTES (no URL), upload into a project first with upload_asset_from_base64, then capture it here via projectId+assetId.

import_library_assets

Place a completed render on a project canvas as a normal video node. Martini performs a server-side object copy, then creates the poster and playback proxy; the durable render artifact is never moved or deleted. Reuse the caller-generated assetId on network retries.

import_timeline_artifact

Inspect a completed render directly from its durable artifact: returns an evenly sampled, timecode-labeled contact sheet plus duration, fps, and dimensions. Use this after a draft render and before spending time on final quality.

inspect_timeline_artifact

See a completed video AS VIDEO in one round-trip: samples N frames evenly across the clip into a single labeled contact sheet (timecodes burned in), plus duration, fps, and pixel dimensions in the metadata block. Use this to judge motion, continuity, and whether the intended action actually happened across a generation — instead of guessing timestamps and firing extract_video_frame N times. Read-only and creates no nodes; reads from R2 on every call, so call it when you actually need to look. For a durable single still or a start/end frame, use extract_video_frame instead.

inspect_video

Arrange direct asset/job/subject children of a root-level canvas bin into a grid, and switch the bin to grid layout mode. Positions are stored and returned in bin coordinate space, with absolute positions included for visual verification. Use dryRun first when reorganizing an existing user board.

layout_bin_children

Enable or disable library collections for a project ('loading' library content into it). Enabled collections become referenceable in that project's prompts — as generation elements ({libraryCollectionId}), and their text fragments as @{id:name} chips. Add/remove semantics; existing enablements are preserved.

link_library_to_project

Get summarized asset nodes, deep links, and their canvas positions for a project. Use filters for shot-number lookup, empty-draft discovery, or smaller operational reads. Use get_asset when you need full per-asset detail.

get_board_assets

Get canvases with deep links, canvas bins, and text annotations for a project.

get_board_canvases

List variables on a project board. Variables are reusable named text snippets referenced in prompts via @{variableId:variableName} and expanded to their value at generation time; a value may embed other variables. Optionally filter by canvas.

get_board_variables