novo agents
start free

Managed media editing

Set workspace.mediaEditing: true on a managed workspace and the agent can edit real image, audio, and video files inside its managed workspace: crop, resize, convert formats, trim, concatenate, adjust levels, extract frames, overlay, transcode, and more. One flag covers all three modalities. Novo provisions and operates the editing toolchain inside the managed workspace; you host nothing. It is a managed capability, so the agent loop and your provider keys stay inside Novo and only the editing work runs in the managed workspace.

const agent = await novo.agents.create({
  context: 'You produce and polish marketing media.',
  band: 'core',
  workspace: { type: 'managed', shell: true, mediaEditing: true },
});

This is an explicit opt-in. Unlike managed document processing, it is not defaulted on for managed workspaces; you enable it deliberately, and a workspace that never edits media is unaffected.

What it does

The agent edits media the way a person would at a terminal: it operates on actual files in the workspace, guided by a Novo-authored skill that teaches it the supported operations and the quality loop. The editing toolchain is provisioned lazily the first time the agent edits media in that workspace, so there is no warm-up cost for workspaces that never touch it.

Supported work spans the common image, audio, and video tasks: resizing and cropping images, format conversion (for example PNG ⇄ JPEG/WebP, WAV ⇄ MP3, MOV ⇄ MP4), trimming and concatenating clips, extracting audio or frames, adjusting levels and dimensions, compositing overlays, and re-encoding. Novo describes the ability, not a specific binary; the agent picks the right operation for the file in front of it. For straightforward edits, the agent is guided to use compact shell commands that transform, probe, and produce previews in one pass. For ambiguous inputs, complex compositions, risky edits, or quality tuning, it can naturally split the work into discovery, edit, debug, and QA steps.

Requires a managed workspace with shell

Media editing runs in the managed workspace, so it needs a managed workspace with the shell enabled:

workspace: { type: 'managed', shell: true, mediaEditing: true }, // shell is required, off by default

Enabling mediaEditing without that (a remote workspace, no workspace at all, or a managed workspace with shell: false) fails agent creation with a 400 invalid_request_error (code invalid_workspace_config). The message names exactly what is missing, for example:

workspace.mediaEditing requires a managed workspace (workspace.type: 'managed')
with shell enabled (workspace.shell !== false).

This is a configuration error you fix in the request, not a provisioning request. See errors. Agent responses also include a read-only capabilityResolution array for capabilities with explicit requirements, so granted and soft-omitted capabilities are visible from agents.get / agents.list.

If Novo's pinned media-editing toolchain is not configured for the deployment, agent creation returns 400 invalid_request_error with code managed_media_editing_unconfigured before the thread can start. That is a Novo provisioning issue, not something to fix in the run prompt.

Flow: generate → edit → embed → view

Media editing is the join between Novo's generation capabilities and its document tools. A generated or imported asset lands as a real workspace file, the agent edits it in place, embeds it into a document, renders, and looks at the result. A typical run:

  1. Generate or import. generate_image({ output_path: 'hero.png' }) writes base64 image output into the workspace when a workspace file courier is available. workspace_import_artifact brings an existing managed artifact (an earlier generation, an upload, a browser screenshot, or URL-backed generation result) into the workspace as a file to edit.
  2. Edit. The agent crops, resizes, recolors, transcodes, or trims the file via the shell, writing the result back to a workspace path (in place, or to a new file to preserve the original).
  3. Embed. The edited file is referenced from a document, for example an image added to a .pptx or .docx via document tools.
  4. Render and view. document_render (or render: true on the edit) rasterizes the result and the agent re-ingests the previews with view_media to confirm placement, scale, and quality before handing off. For video and audio deliverables, the agent should verify codec/duration with ffprobe and inspect small previews (thumbnail/contact sheets, short clips, or waveform images) instead of reading full media bytes back into model context unless full-media inspection is needed.
const agent = await novo.agents.create({
  context:
    'You build slide decks. Generate any imagery you need, edit it to fit the layout, embed it, render, and check it before you finish.',
  band: 'core',
  workspace: {
    type: 'managed',
    resources: 'large',
    shell: true,
    mediaEditing: true,
    // documents is on by default for managed workspaces
  },
  capabilities: {
    media: { image: true },
  },
});

To enable the same flow for audio or video, pair workspace.mediaEditing with the matching media generators: media: true for all of them, or a subset like media: { video: true, speech: true, music: true, soundEffect: true }.

Outputs and artifacts

Edited media is workspace-first:

  • A workspace file. The edited output is written back to a path in the managed workspace, so downstream shell, document, and editing steps in the same thread operate on it directly. Files persist across the thread's runs like any other workspace file.
  • Managed artifacts when another managed tool stores them. Generation tools, document outputs, document previews, browser screenshots, and imported uploads are managed artifacts. Shell-edited media stays a workspace file until a later managed tool stores it as part of its own output.

The agent works on real bytes throughout; there is no separate upload step and no model round-trip of the file contents to edit it.

Billing

Media editing runs inside the managed workspace, so it bills as managed-workspace compute: the same metering as any other shell work in the workspace, debited from the same wallet with standard Novo-managed runtime pricing. There is no per-operation price: an edit is just workspace compute and transfer while the work runs.

Because it is managed-workspace work, it is not bounded by a run's budgetCents or maxDurationMs. Those bound model inference, while the workspace is thread-scoped and can outlive any single run, including across approval and input pauses. The workspace idle timeout is the real bound. Provisioning the editing toolchain on first use is part of that workspace compute; there is no separate enablement charge. Usage appears in /v1/usage, /v1/usage/events, and the Billing console alongside other workspace cost. See pricing.

The model inference that decides what to edit bills as normal tokens within the turn, like any other tool-driven work. Verification strategy affects token use: reading a final image is usually cheap, while reading a full video or long audio file can carry the media bytes forward in the thread context. Prefer ffprobe plus small preview artifacts for routine video/audio QA.

Limits

  • Managed workspace with shell only. No remote workspace, no shell-less workspace. Enabling it elsewhere is a 400 at config time, not a soft no-op.
  • Best-effort, not a render farm. Editing shares the workspace's CPU and memory. Large transcodes and long videos run within the workspace's resource preset and idle window: raise resources for heavier work, and expect long jobs to be bounded by the idle timeout rather than budgetCents.
  • First-use provisioning latency. The editing toolchain is installed lazily the first time the agent edits media in a workspace; the first edit in a fresh workspace pays a one-time setup cost before it runs.
  • Verify before handoff. The agent should always inspect an edited result before declaring it done, because automated edits can land at the wrong scale, crop, or codec. For still images, reading the final image is usually appropriate. For video/audio, prefer ffprobe plus extracted thumbnails/contact sheets, short clips, or waveform images; read full media only when the task needs it. Pair the workspace shell with a tool approval hook if you don't want unattended file edits.
  • No managed format guarantees beyond the common set. Exotic or DRM-protected containers may not be editable; the agent reports when an operation isn't supported rather than silently producing a broken file.