@volcengine/amk-editor-assistant

火山引擎 AI MediaKit Web 智能剪辑 SDK，集成对话式 Agent 与多轨道编辑器，支持自然语言剪辑和手动编辑。

接入文档

完整接入流程、模型配置、服务端代理与鉴权说明请参阅 Web 智能剪辑 SDK 集成指南。

安装

npm install @volcengine/amk-editor-assistant react react-dom

快速开始

import { createAmkEditorAssistant } from '@volcengine/amk-editor-assistant';
import '@volcengine/amk-editor-assistant/styles.css';

const sdk = createAmkEditorAssistant({
  container: document.getElementById('editor')!,
  projectId: 'your-project-id',
  endpoint: '/api/amk-proxy',
  i18n: { locale: 'zh-CN' },
  assistant: {
    model: 'your-inference-model-id',
    preferMultiModalModels: ['your-audio-model-id', 'your-visual-model-id'],
  },
});

await sdk.whenReady();

// 页面或组件卸载时调用 sdk.destroy() 释放实例。

请在浏览器端初始化，为容器设置明确宽高，并替换工程和模型 ID。接入前按正式文档完成服务开通、跨服务授权及业务代理配置；API Key 和长期密钥仅保存在服务端。

界面布局、主题、素材接入及自定义能力请参阅正式接入文档。

自定义 material.menuItems 支持可选 renderIcon({ container, theme })，同步向 SDK 提供的 16×16 容器挂载原生 DOM，可返回清理函数；不提供 icon 字段。菜单关闭、主题或回调引用变化时执行清理并清空容器，主题/回调变化后重新挂载。保持回调引用稳定，每次挂载创建独立节点。原生 DOM 不依赖用户 React；若自行挂载 React root，需在清理中 unmount，不返回 JSX/ReactNode。此能力需新版 AMK Editor，旧 Editor 仅显示自定义菜单文字。Assistant 内置“添加到对话”已使用此接口，并为尚未升级的内置 Editor 保留原图标兼容样式。

轨道右键添加到对话

支持轨道菜单的 Editor（1.0.1-beta.3 或后续版本）会自动注入“添加到对话”。单选/多选追加的是时间线片段引用，包含当前 timeline_id、元素 ID 和片段范围，不替换草稿、不自动发送。旧 Editor 保留原工具栏入口。当前锁定的 beta.2 尚无轨道菜单能力，升级依赖或在 Demo 启用本地新版 Editor 后生效。

assistant: {
  model: 'your-model',
  trackMenu: { position: 'beforeCopy' }, // beforeCopy / afterCopy / beforeDelete（默认）
  // trackMenu: { enabled: false }, // 只关闭内置轨道菜单项
}

track.menuItems 保留宿主自定义项及其 position。同一位置按数组顺序，删除仍在底部；双语复用 assistant.timelineLabels.addToConversation/addSelectedToConversation 及 i18n，多选文案支持 {count}。插入失败调用 onIntegrationError 并保留菜单便于重试；草稿桥接未就绪时禁用。

Demo 的本地上传与存储切换

不传参数时，火山 Demo 默认 tos，BytePlus Demo 默认 vod。两个版本都可在工程选择页切换，或使用 URL：

• ?projectId=...&upload=tos：内置 TOS 本地文件上传。
• ?projectId=...&upload=vod：内置当前品牌 VOD 本地文件上传。
• ?projectId=...&upload=custom：关闭内置 storage，保留业务自定义入口。
• storage=tos|vod|custom 是 URL 参数别名；同时传入时 upload 优先。

环境变量使用 VEVEditor 同名配置 VITE_AMK_STORAGE_MODE=tos|vod|custom；BP 可单独设置 VITE_BP_AMK_STORAGE_MODE。优先级为 URL → BP 专用环境变量（仅 BP）→ 通用环境变量 → 品牌默认值。修改 .env.local 后重启 Vite。

TOS 目标配置 VITE_AMK_TOS_DESTINATION=tos://bucket/path，兼容旧 VITE_MEDIA_OUTPUT_DESTINATION，自动追加当前 projectId；BP 可显式覆盖 VITE_BP_TOS_DESTINATION。当前内置 TOS 上传使用 cn-beijing，必须配置匹配的桶及 TOS STS，不将 BP VOD 凭证当作 TOS 凭证。

VOD 目标配置 VITE_AMK_VOD_DESTINATION=vod://space；BP 优先 VITE_BP_VOD_DESTINATION。国内凭证接口默认 /api/vod-upload-token，使用服务端 VOD_ACCESS_KEY/VOD_SECRET_KEY（不自动复用 TOS 的 VOLC_* 凭证）；BP 默认 /api/bp-vod-upload-sts，仅使用 BP_VOD_ACCESS_KEY/BP_VOD_SECRET_KEY。这些长期凭证不能使用 VITE_ 前缀。

SDK 接入方可直接开启 storage；无需自己实现本地导入按钮或上传回调：

storage: {
  media_output_destination: 'tos://your-bucket/your-path', // 或 vod://your-space
  getUploadSTS: async () => {
    const response = await fetch('/your-upload-sts', { method: 'POST' });
    if (!response.ok) throw new Error('Upload STS request failed');
    return response.json();
  },
},

两项须同时配置，且凭证类型与目标协议一致。自定义 material.onUploadFile/onUploadMaterial 配置时仍优先使用自定义上传。URL 链接导入是独立的 onUploadUrlMaterial 回调，以上切换主要控制内置本地文件上传及产物存储；不会自动把已有 URL 上传回调改成 VOD 链接转存。

Demo 凭证仅从当前仓库 components/amk-editor-assistant/demo/.env* 或显式注入的进程环境变量读取，不再读取同级 VEVEditor 仓库。首次运行先将 demo/.env.example 复制为 demo/.env.local，配置 AMK 鉴权、TOS 的 VOLC_*/Role、国内 VOD 的 VOD_*、BP 的 BP_AMK_API_KEY 和 BP_VOD_*；凭证缺失时会明确报出变量名。.env.local 不提交仓库。可选的 AMK_DEMO_LOCAL_EDITOR=1 只用于主动选择本地 Editor 产物联调，与上传凭证无关；独立下载时不要启用它。

本地 Demo 按上传模式选择 AMK 接口账号：TOS 使用 AMK_TOS_API_KEY，VOD 使用 AMK_VOD_API_KEY，未配置时兼容 AMK_API_KEY；BP 始终使用 BP_AMK_API_KEY。这些 Key 只由 Vite 服务端代理注入，不进入浏览器构建。上传 AK/SK、目标 space 与 AMK API Key 对应账号必须匹配。不同账号的旧工程不能仅靠切换参数迁移；需用对应模式创建或打开该账号的工程。生产服务端也须使用相同账号选择规则。