# Beatra Skill + MCP — Edit an existing video

> Apply an instruction or reference-guided change to an existing clip.
> Self-contained workflow guide for AI agents.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/video-edit

- Primary surface: the Universal Beatra Skill with authenticated MCP.
- Install or reconnect: https://beatra.ai/install.md
- MCP endpoint: `https://mcp.beatra.ai/mcp`
- Billable action: `beatra.videos.edit`
- Dynamic model facts: call `beatra.models.list` with `capability: "video_edit"` only when model constraints, controls, or prices matter.
- Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal.
- Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response.

REST/OpenAPI is the fallback protocol path, not the primary agent packaging.

---

## 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`.

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

## Tool arguments

```json
{
  "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](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_edit_v1_videos_edit_post)
for the complete request contract. Skill + MCP is the recommended integration; REST serves custom applications.

---

## Appendix: shared Skill + MCP contract

### Retry identity

One logical generation has one `client_request_id`. If the create response is
lost, retry the exact same arguments with that ID. If any prompt, media, model,
or output control changes, use a new ID. Never create another paid task merely
because the first task is `queued` or `running`.

### Polling and billing truth

Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`,
`failed`, or `canceled`. Only the task response is authoritative for the
resolved model, artifacts, charged credits, and refunded credits.

### Recovery

Preserve structured Beatra error codes. Reconnect on authentication failure;
stop and request a balance action on insufficient balance; refresh current
constraints with `beatra.models.list` after model validation; request a new
upload grant after expiration or MIME/length mismatch. Changed generation
arguments always require a new `client_request_id`.