Martini

Create Action cards on a Martini canvas. An Action is a plain-language brief that reads assets, notes, variables, or bins and writes into output bins; the brief IS the wiring — its @-refs decide the input and output edges, and how many times it runs is decided by a plan pass at run time, not configured here. An Action may read and write the same bin for generate-then-review, seeing existing takes as inputs and adding new takes there; make such an Action idempotent: check what already exists before generating. Prefer BIN inputs over fixed asset refs: create an input bin (create_bin) so the user can drag material in and re-run — an asset ref pins the Action to one specific item forever. This authors the Actions but does not run them or spend olives. To change an existing Action, use update_actions instead of re-creating it — get_canvas_children (actions section) lists the existing cards with their ids.

create_actions

Create a canvas bin, optionally inside another bin. Nested bins organize variations while workflow inputs include their descendants.

create_bin

Create a new canvas in the project and return its deep link.

create_canvas

Upload JSON as a File on the canvas. Accepts an ordinary JSON value; embedded images are preserved in immutable storage, never in the canvas document. Does not start generation. Use a binId to add the File to a bin.

create_json_file

Create an empty draft asset-backed node on the board. This seeds editable draft settings but never starts generation or spends credits. To position, prefer placement (rightOf/below/near an anchor node, or bin to group) over computing coordinates; use position only for exact pixels. The prompt field is draftPrompt (not prompt). Drafts persist reference image URLs/names (including resolved libraryReferences), video/audio references, a v2v sourceVideo, elements, aspectRatio, resolution, durationSeconds, videoInputMode, start/end frames, FLUX.3 controls (flux3RenderQuality, flux3DurationMode, flux3Keyframes), and model-scoped generation settings (seed, negativePrompt, cfgScale, audioEnabled, quality, outputFormat, mode, bitrateMode, and the TTS voice settings); use update_draft to change draft fields later. Model-scoped values are validated against the draft model — check get_models for its options. Library identity/usage tracking is not persisted on drafts.

create_node

Create a planned shot node and run an approved generation for it. Requires user approval of the model, prompt, target shot, count, and estimated cost. When the new shot should match existing shots, first read their full prompts and model with get_asset and mirror their prompt structure. To position, prefer placement (rightOf/below/near an anchor node, or bin to group) over computing coordinates.

create_node_and_generate

Create multiple empty asset-backed nodes in one server-owned layout pass. For nodes without explicit positions, Martini uses rendered node widths and default canvas spacing instead of source asset pixel dimensions. Prefer per-node placement (rightOf/below/near an anchor, or bin to group) over computing coordinates; for a large batch of related shots, placement.bin "new:<name>" groups them in a new bin (nodes sharing one "new:<name>" in a call share ONE bin; add columns for an immediate grid). Prefer verbosity "summary" for batches. Per node: The prompt field is draftPrompt (not prompt). Drafts persist reference image URLs/names (including resolved libraryReferences), video/audio references, a v2v sourceVideo, elements, aspectRatio, resolution, durationSeconds, videoInputMode, start/end frames, FLUX.3 controls (flux3RenderQuality, flux3DurationMode, flux3Keyframes), and model-scoped generation settings (seed, negativePrompt, cfgScale, audioEnabled, quality, outputFormat, mode, bitrateMode, and the TTS voice settings); use update_draft to change draft fields later. Model-scoped values are validated against the draft model — check get_models for its options. Library identity/usage tracking is not persisted on drafts.

create_nodes

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 unless includeMedia is true (board-only removal, clips included; files stay in storage). 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

Re-render a completed FLUX.3 Draft take at full 1080p quality — the same pixels the draft promised, without the draft compression. Call without approval to get the exact server-computed olive cost and eligibility; present it, then re-call with approval to spend. The result attaches as a NEW VERSION of the same node (the draft stays in Versions and the enhanced take becomes active) — it does not create a second node. One enhancement per draft: find eligible takes with get_board_assets (flux3DraftEnhanceEligible) or get_asset. Prompt, resolution, and audio are fixed by the draft and cannot be changed here; to change them, generate a new draft instead.

enhance_draft

Start a durable Premiere Pro XMEML bundle export from current collaborative timeline state. The ZIP contains XML plus original media; clip levels and fades and track pan travel as Audio Levels / Audio Pan filters. 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. FLUX.3 drafts staged with flux3RenderQuality "draft" are estimated and billed at draft rates, and auto-duration drafts are quoted at their full hold with the unused seconds refunded on completion.

generate_nodes

Inspect one durable Action run: the derived plan for each Action (units, planned outputs, olive estimate, ambiguity), per-Action progress, item-level provenance, measured agent cost, generation cost, and errors. `billing`, when present, is the separately metered agent-work receipt (model, active compute and paid tools); failed/cancelled usage is charged and funding pauses preserve progress. `olives` sums generation and agent spend against the budget (total, remaining, overBudget, policy). With waitSeconds it long-polls: one held call replaces a sleep-and-poll loop. The per-Action diagnostics trace (every session, tool call, judge verdict, and note — by far the largest field, 100–250 KB on a long run) is left out by default: poll without it, and pass include: ['trace'] when diagnosing a failure.

get_run

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. Generated assets add generation.jobId and effectiveSettings (the request as it actually ran, after normalization); includeDraftSettings adds the node's editable draft. imageUrl is the asset's ORIGINAL file and is the only URL to pass as a generation input (referenceImages, startFrameUrl, sourceVideo, video/audio references) — never construct URLs from the id, and never use thumbnails or proxies.

get_asset

Return a short-lived presigned URL for downloading a completed asset file. Use this ONLY 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. The returned downloadUrl is never a generation input: for referenceImages, startFrameUrl, endFrameUrl, imageUrl, or any other tool that takes an asset URL, pass the asset's imageUrl / uri from get_asset or get_board_assets instead.

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. Each node carries ref — the exact @[kind-id:label] string to paste into add_comment bodies. Unsupported node kinds carry ref: null.

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. Bin parents include direct child bins; follow their binId to inspect nested material. Canvas parent responses include the canvas deep link. Results can include bins, asset/job nodes, legacy subject or collection nodes, text notes, and Action cards (`actions`, ids for update_actions). 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. Each node carries ref — the exact @[kind-id:label] string to paste into add_comment bodies. Unsupported node kinds carry ref: null.

get_canvas_children

List review comment threads on a project (canvas pins + timeline markers). Each comment includes parsed refs (each with the exact ref token to paste into add_comment) and an authorRef, and top-level me identifies you using the @[kind-id:label] reference grammar. 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. Timecodes are MM:SS:FF at 24 fps. A timecode in a body belongs to the nearest preceding asset ref with a clock (video/audio), else the thread anchor: time/clip anchors mean sequence time, node anchors on a video/audio mean time inside that file. 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, several by jobIds (one call, one read), or list a project's jobs by projectId. Running jobs carry estimatedTimeSeconds (remaining, from the model's timing table) — size a wait_for_jobs timeout from it instead of polling on a fixed interval. With jobId or jobIds, projectId scopes the lookup: a job from another project reads as not found.

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 (compact, paged), resolve a model/provider name, or inspect one exact model in full. query resolves names like "GPT image" or "Kling"; modelId inspects one exact ID (guidance and inputs live there); omit both to list.

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. Reports compare measurements with an optional delivery target and can measure an optional sequence time range. Each new report consumes one daily draft-render quota slot for the project. 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. Render responses include effective videoBitrateKbps and bitrate derivation, including draft-ignore or infeasible-size notes. 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

List the image and video upscale presets available to this project. Presets are created and edited in the Martini app.

get_upscale_presets

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

get_variable