# 编辑已有视频
> 通过指令或参考图片修改现有片段。

通过指令或参考图片修改现有片段。

## Agent 主路径

当已有片段仍是源时间线时，使用 `beatra.videos.edit`；如果目标是从片尾继续
生成，应使用 `beatra.videos.extend`。

1. 上传本地源视频和所有本地参考图片。
2. 用 `capability: "video_edit"` 调用 `beatra.models.list`，读取输入限制、
   时长语义、音频行为、控制项与价格。
3. 清楚说明要修改和必须保持的内容。
4. 使用一个 `client_request_id` 提交一次，再用 `beatra.tasks.get` 轮询。

## AI 指南

AI integration guide: https://docs.beatra.ai/llms/videos-video-edit.md

## 工具参数

```json
{
  "instruction": "把杯子替换成参考图中的蓝色瓶子，并保留原镜头运动",
  "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` 可用 `auto` 或 `origin`。显式设置
`duration` 可能表示从零时刻开始截断；若希望保留完整可用输入，
应先确认模型规则再决定是否省略。

## 模型、控制与成本

通用控制项包括 `prompt`、`negative_prompt`、`resolution`、
`duration`、`aspect_ratio`、`seed`、`enhance_prompt` 和 `watermark`；
每一项都应按所选模型的元数据使用。

可选模型、源视频时长、参考图片数量、输出时长、分辨率、宽高比、音频行为
和价格输入均以 `beatra.models.list` 为准。编辑可能同时按输入与输出视频
秒数计费，不要凭记忆估算。

### Wan 3.0

设置 `model: "wan3.0-video"` 或 `wan3.0-video-prime`。时长跟随源视频（省略 `duration`，源视频最长 15 秒）。
最多 10 张参考图，不接受参考视频/音频。片源秒与成片秒均计费。`480p` 为每秒 225 / 335 积分（标准版 / 高阶版）。

## 任务状态与恢复

轮询同一 `task_id` 直到终态。响应丢失时可用相同参数和同一
`client_request_id` 恢复；新指令、新源视频、新参考、新音频选择或输出设置
都属于新请求。

## 通过 REST 调用

直接协议集成使用 `POST /v1/videos/edit`。完整请求契约请参阅生成的
[API 操作定义](https://docs.beatra.ai/zh/docs/api-reference/operations/videos/videos_edit_v1_videos_edit_post)。
推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。