Edit an existing video

Primary agent path

Use beatra.videos.edit when the existing clip remains the source timeline. If the goal is to continue beyond its endpoint, use beatra.videos.extend.

Upload the local source video and any local reference images.
Call beatra.models.list with capability: "video_edit" for current input limits, duration semantics, audio behavior, controls, and prices.
State what must change and what must remain stable.
Submit once with one client_request_id; poll with beatra.tasks.get.

AI guide

MCP integration guide for AI

For custom API integrations, copy this guide into Claude, Codex, or another coding assistant.

Markdown

Tool arguments

{
  "instruction": "Replace the cup with the referenced blue bottle and keep the camera move",
  "source_video": { "type": "artifact", "artifact_id": "artifact_source_video" },
  "references": [
    {
      "kind": "image",
      "media": { "type": "artifact", "artifact_id": "artifact_blue_bottle" }
    }
  ],
  "audio_setting": "origin",
  "resolution": "720p",
  "client_request_id": "vid-edit-opaque-1"
}

audio_setting is auto or origin when supported. An explicit duration can mean truncating the source from time zero; omit it when the desired behavior is to preserve the full eligible input.

Models, controls, and cost

Common controls are prompt, negative_prompt, resolution, duration, aspect_ratio, seed, enhance_prompt, and watermark. Use each only according to the selected model's metadata.

Use beatra.models.list as the current source for selectable models, source duration and reference-image limits, output duration rules, resolution, aspect ratio, audio behavior, and price inputs. Editing may bill input-video and output seconds; use the returned billing unit rather than estimating from memory.

Task status and recovery

Poll the same task_id until terminal. A lost response can be recovered with identical arguments and the same client_request_id. Any new instruction, source, reference, audio choice, or output setting is a new request.

REST API

Direct protocol integrations use POST /v1/videos/edit. Follow the generated API operation for the complete request contract. Skill + MCP is the recommended integration; REST serves custom applications.