Martini

Preflight check before the first upload OR download in a session. It does not probe anything itself: it returns the probeUrl to test from the agent's environment, for PUT requests (upload_assets_prepare) and GET requests (get_asset_download_url's presigned URLs). Run the curl in howToTest: a response containing a `cf-ray` header means R2 is reachable, and nothing is wrong. Only a curl error, HTTP 000, an `X-Proxy-Error: blocked-by-allowlist` header, or a missing cf-ray means storage is blocked; then do not call upload_assets_prepare or fetch get_asset_download_url URLs, and print ifBlocked.message to the user verbatim so they can unblock. Never report storage as blocked without running the probe. Call once per session.

check_storage_reachability

Create an immutable R2 checkpoint of the selected sequence and its direct tracks/clips before a risky edit. Nested sequence contents are intentionally excluded so restoring a parent never erases newer child-sequence work. operationId makes retries safe.

checkpoint_timeline

Complete one or more image, video, or audio uploads started with upload_assets_prepare in a single call. Verifies each R2 object arrived, extracts image dimensions, or hands off to the video proxy/thumbnail or audio proxy/waveform pipeline based on the asset type set at prepare time. Per-asset completion failures (missing bytes, decode error, wrong MIME, already processed) return structured error entries without failing the rest of the batch. To use completed audio as a generation reference, pass its returned url to update_draft { audioReferences: [{ url }] } and cite it in draftPrompt as @Audio1; models such as Seedance 2.5 do not use uncited audio references.

upload_assets_complete

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

Push an HTML/CSS/JS composition (HyperFrames-compatible) — titles, lower thirds, motion graphics, animated overlays, explainers — and it appears in Martini as an editable Graphic on the canvas and timeline: users adjust its variables and retime its pieces without touching the code. Use this INSTEAD of rendering an MP4 locally whenever the user wants to keep editing in Martini. Rendering is charged for the compute it uses, at most the result's estimatedOlives (unused olives are returned when the render finishes); a take already rendered is not charged again. Undeclared text in index.html is still editable in Martini (one field per text element; give elements ids to keep edits across pushes). Shape: index.html at the root plus any CSS/JS/fonts/media; a root element carrying data-composition-id, data-width, data-height (pixels) and data-duration (seconds); motion on a seekable timeline (a paused GSAP timeline registered under the root composition id, window.__timelines[id] = tl, Anime.js on window.__hfAnime, or frames drawn from the hf-seek event). No network at render time: include every file (CDN GSAP/Anime.js script tags are swapped for pinned copies automatically). Media already in Martini binds through assetRefs. A page that seeks itself (window.renderAt(t), t in seconds, may return a Promise, called in any order) marks its root data-clock="renderAt" data-no-timeline (optionally data-clock-ready="ready" naming a promise to await first); Martini calls it for every frame at 24 fps and awaits it. three.js 0.182 from an importmap or jsdelivr/unpkg URL is swapped for a pinned copy. A claude.ai / ChatGPT artifact — plain HTML animated with CSS keyframes, framer-motion, requestAnimationFrame, timers, or a React component (App.jsx) — can be sent as it is: pass the same files plus artifact: { durationSeconds }. It renders frame by frame under a virtual clock, deterministically; network fonts and CDN scripts are refused with the fix, click-to-start and live-clock pages get warnings (autoStart clicks once at 0 s). Prefer converting to the HyperFrames shape when users should adjust text, colours or timing in Martini: an artifact has nothing to adjust. Minimal example (files: [{ path: "index.html", encoding: "utf8", content }]): <!doctype html><html><head><style>#root{width:1920px;height:1080px;background:#111;position:relative}#t{position:absolute;left:120px;top:460px;font:700 96px sans-serif;color:#fff}</style></head><body><div id="root" data-composition-id="main" data-width="1920" data-height="1080" data-duration="4"><div id="t">Hello</div></div><script src="https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/gsap.min.js"></script><script>const tl=gsap.timeline({paused:true});tl.from("#t",{y:80,opacity:0,duration:1});window.__timelines=window.__timelines||{};window.__timelines.main=tl;</script></body></html> Validation problems come back as a list (path, line, fix) with nothing created; fix them all and call again with the same idempotencyKey. Success returns the assetId, the render jobId (wait_for_jobs), a deep link, warnings, and next steps.

create_graphic

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. A personal project starts with link sharing on (anyone with its link can edit; the result reports it as visibility, visibilityLabel, and accessLabel) unless visibility says otherwise: pass visibility "private" for confidential material (it needs a Pro or Team plan), and say so when you leave the default. 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 or crop-adjust node at an earlier cropRevisions or editRevisions entry (find revision IDs with get_asset). Optional angle straightens before cropping; angle edits and recrops of crop-adjust nodes require expectedRevisionId from 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). A bin an Action reads or writes is refused too: remove it from the Action with update_actions first. 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

Find the shot cuts in a completed video: every cut timestamp, each shot's start, end and duration, and which detector ran. Read-only and creates no nodes. The first call on a clip runs detection (seconds; TransNetV2, a learned shot-boundary model that also catches dissolves, with ffmpeg's scene-change filter as the fallback, which misses dissolves) and caches the result on the asset, so later calls and the timeline's Split by Shot reuse it. sampleTimestampsSec holds one mid-shot timestamp per shot (at most 16, spread across the clip when there are more shots); pass it to inspect_video's timestampsSec for a contact sheet with one frame per shot.

detect_shots

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

Enhance a completed FLUX.3 or Seedance 2.5 draft to 1080p as a new version of the same node. Call without approval for eligibility and exact olive cost; present it, then re-call with approval and planHash to spend. FLUX drafts can be enhanced once. Seedance drafts can be enhanced until enhanceUntil (seven days from provider creation); check get_board_assets or get_asset. Creative settings are fixed by the draft. Seedance draft creation is available on the native BytePlus and fal routes (not on the US-hosted seedance-2.5-us models).

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; then wait with wait_for_jobs, not a get_jobs poll. 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

Trace where an asset came from and what was made from it. ledger says which record you got. 'story': the node's placement (how it got here), the origin of its bytes (operation, tool, how it is known — logged by Martini, stated by a person or an agent, matched, reconstructed), its inputs by content hash with the board placement of each, every other origin stated about the same bytes, where the bytes were used, their copies, and notes — walked up over inputs and down over uses inside this project (walk.up / walk.down list the nodes reached; stories holds each one's story); a placement in another project is a portal, listed, not walked — open that project to continue. 'derivations' (the old ledger): the latest derivation (operation, tool, actor, inputs with roles and regions, evidence), the copy chain (rootNodeId is the original a paste or duplicate descends from), and a bounded walk with the full derivations of every node listed. TO REPLACE AN ELEMENT THAT APPEARS IN A FINISHED VIDEO, DO NOT EDIT THE VIDEO: walk up to the nearest derivation whose inputs include the element (a reference still, an element sheet, a start frame), replace or regenerate THAT input, and re-fire the generations that consumed it (their refs.generationId names the recipe); trims, upscales and copies downstream re-derive from their recorded regions. Labels and thumbnails come from get_board_assets / get_asset for the nodeIds returned here.

get_asset_lineage

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

List the voices in the project team's connected ElevenLabs account. Use a returned voiceId as the voice parameter when generating with elevenlabs-tts-byok (its get_models voice options are empty because voices are per-team).

get_elevenlabs_voices

A short-lived download URL for one recipe archive of this project (the tar.gz a Graphic's pre-rendered clip was made from, named by sha256 in the Graphic's martini.graphic.json). Verify the downloaded bytes against sha256 before unpacking; the server does not. A Graphic copied from another project has no recipes here (RECIPE_NOT_FOUND). martini graphics pull --recipes does the download, check and unpack.

get_graphic_recipe_download_url

Pull a Graphic's current take. Without path: the manifest — revision, files (path, role, size), variables and pieces with the values and timings users set in Martini applied, the overrides summary, runtimes, render status, the previous take, and reviewNotes: the open comment threads that point at a moment in this Graphic (timecode, seconds, the pieces playing then, the note and its replies, threadId), written by collaborators in the player or on the canvas. With path: that file's content, one chunk per call (offset/nextOffset, and contentSha to pass back as expectedSha so every chunk comes from the same version), with Martini-side overrides written into index.html so you edit what users see. Media files answer with their assetId (use get_asset / view_asset). A take sent as a web page artifact (take.kind anypage-artifact) has no variables, pieces or overrides; its files are the built index.html plus the originals under source/. Pass the returned revision as baseRevision to update_graphic_source.

get_graphic_source

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