@volcengine/amk-editor

@volcengine/amk-editor

火山引擎 AI MediaKit 官方 Web 视频编辑器 SDK。

安装

npm install @volcengine/amk-editor

需要 React 18 或 19。使用本 SDK 须获得有效的火山引擎商业授权，条款见 LICENSE。 本 SDK 使用的第三方开源组件仍分别适用其各自的许可证。

快速开始

import { AmkEditor } from '@volcengine/amk-editor';
const editor = new AmkEditor({
  container,
  projectId: 'your-project-id',
  endpoint: 'https://your-backend.example.com',
  // 可选：自定义客户代理服务所需的请求头，SDK 不约定鉴权格式并会原样透传。
  auth: {
    getHeaders: async () => {
      const response = await fetch('/api/session-token');
      const { token } = await response.json();
      return {
        Authorization: `Bearer ${token}`,
        'X-Customer-Id': 'your-customer-id',
      };
    },
  },
  material: {
    onUploadMaterial: async files => {
      // 上传到业务存储后返回素材列表，每项必须带 source_material_id
      return [];
    },
    onUploadUrlMaterial: async urls => {
      return [];
    },
    onRefreshPlayInfo: async materials =>
      materials.map(item => ({
        material_id: item.material_id, // 仅用于匹配，不要改写
        url: '...',
        poster: item.poster,
        sprite: item.sprite,
      })),
  },
});

// 运行时替换鉴权逻辑，后续所有 AMK 请求立即使用新的 Header。
editor.setAuth({
  getHeaders: () => ({ Authorization: 'Custom new-token' }),
});
// 清除鉴权 Header。
editor.setAuth(null);

页面卸载时销毁：

editor.destroy();

接入说明

• projectId、endpoint 必填。endpoint 指向你的业务代理。
• auth 可选，用于浏览器访问客户代理时附加自定义请求头。SDK 不约定 Token 格式或 Header 名称，只会将 getHeaders 返回的内容原样合并到工程、素材、tools、tasks、导出等全部 AMK 请求中。运行期间可通过 setAuth() 替换，传入 null 或 undefined 可清除。
• 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 source_material_id，不必填写 material_id。
• 播放地址、封面、雪碧图可能有时效。通过 onRefreshPlayInfo 返回新的访问地址。
• 可选实现 onPersistExtractUrls：把抽帧得到的临时地址转存为业务长期地址，并随 materialPatch 写回自定义存储字段。
• 可选配置 export.qualityEnhancement: true 以在导出弹窗展示「视频画质增强」；默认不展示。