@volcengine/amk-editor

@volcengine/amk-editor

AMK 场景官方接入包：发布构建会内联底层编辑器运行时 UMD 与样式。公网业务方/demo 只需安装本包，无需安装或访问内部编辑器包。弹层挂载使用 React 18/19 的 createRoot（兼容 React 19，不再使用已弃用的 ReactDOM.render）。

License

AMK Editor SDK 是火山引擎 AI MediaKit 的商业配套软件。使用本 SDK 需要获得有效的火山引擎商业授权，具体条款参见 LICENSE。商业授权咨询请联系 [e-mail]。

本 SDK 使用的第三方开源组件仍分别适用其各自的许可证，第三方许可证不因本商业许可证而被替代。

import { AmkEditor } from '@volcengine/amk-editor';

const editor = new AmkEditor({
  container,
  projectId: 'xxx',
  endpoint: 'https://your-proxy.example.com',
  getLicenseUrl: 'https://license.example.com',
  material: {
    // 本地上传：入参 File[]，返回 MaterialItem[]；每项必须带 source_material_id，不必传 material_id
    onUploadMaterial: async files => [],
    // URL 上传：入参 string[]（弹窗内逗号/换行分隔），返回契约同上
    onUploadUrlMaterial: async urls => [],
    onRefreshPlayInfo: async materials =>
      materials.map(item => ({
        material_id: item.material_id, // 仅用于匹配，不要改写
        url: '...', // 业务方按自己字段映射
        // 以下 key 名只是推荐示例；使用自定义字段时读取自己的字段即可。
        poster: item.poster_storage_key ? 'https://signed-poster-url' : item.poster,
        sprite: item.sprite_storage_keys
          ? { ...item.sprite, storeurls: ['https://signed-sprite-url'] }
          : item.sprite,
      })),
    // 抽帧临时链转存成长效地址（可选）；URL 和 key 会一起写回素材
    onPersistExtractUrls: async ({ kind, urls, material }) => {
      const result = await persistToBusinessStorage({ kind, urls, material });
      return {
        urls: result.urls,
        // SDK 会把 materialPatch 原样合并并写回素材；字段名由业务决定。
        materialPatch:
          kind === 'poster'
            ? { poster_storage_key: result.storageKeys[0] }
            : { sprite_storage_keys: result.storageKeys },
      };
    },
  },
});

// 两种上传返回素材后，SDK 统一：
// 1. addSketchItems → 素材面板
// 2. createAmkMaterials → POST 远端仓库，并把服务端返回的 material_id 记到面板
// 3. ensureMaterialExtractTasks → 缺/过期 poster/sprite 时抽帧；临时链上屏后可后台转存再 PUT

// 转存完成后素材会保存：
// - poster + poster_storage_key（推荐字段，可自定义）
// - sprite.storeurls + sprite_storage_keys（推荐字段，可自定义）
// 下一次 onRefreshPlayInfo 会收到这些 key，业务可据此重新生成有时效的访问 URL。
// SDK 不读取上述两个 key，也不把它们当作固定 Schema。业务也可以返回：
// materialPatch: {
//   biz_storage: { poster_key: '...', sprite_keys: ['...'] },
// }
// 只需在 onRefreshPlayInfo 中按同一套自定义结构读取即可。

// 导出：invokeTool('vibe-editing-common', { edit_param, callback_args? })
// 开启画质增强时附带 callback_args（JSON 字符串），供代理后续调增强：
// - standard/professional → { tool:"enhance-video", tool_version, resolution, fps }
// - large-model → { tool:"enhance-video-generative", resolution, fps }
// SDK 不负责增强任务本身。

// 工程会从 {endpoint}/api/v1/editing/projects/{projectId} 加载并自动保存。
// 通用 MediaKit 工具仍通过 POST {endpoint}/api/v1/tools/{toolName} 调用。
await editor.invokeTool({
  toolName: 'asr-subtitles',
  params: {
    input: {
      type: 'video',
      url: 'https://example.com/demo.mp4',
    },
  },
});

构建

先构建 SDK，再构建本包：

pnpm build-veveditor
pnpm --filter @volcengine/amk-editor run build

产物位于 dist/index.js（含 veveditor 运行时）与 dist/veveditor.css（样式 side-effect）。

• projectId / endpoint 均为必传；鉴权密钥留在业务服务端，由 endpoint 代理注入
• 发布包不声明底层编辑器为运行时依赖；底层编辑器和 video-editor 已在构建阶段内联到 dist/index.js，类型声明也不依赖内部包。
• 发布前必须使用 npm pack --dry-run 检查 tarball；公网用户只需要能访问 npm 公网源和业务方提供的 endpoint。

Editing API 对接

初始化时，AMK Editor 会组合以下接口：

• GET /api/v1/editing/projects/:project_id
• GET /api/v1/editing/projects/:project_id/materials
• GET /api/v1/editing/projects/:project_id/editor

编辑过程中按资源分别写回：

• 标题变更：PATCH /projects/:project_id
• 素材变更：PUT/DELETE /projects/:project_id/materials
• 剪辑参数变更：PUT /projects/:project_id/editor

Editor 保存携带服务端 revision，SDK 内部串行提交保存请求，避免同一页面内的并发保存互相覆盖。素材身份字段分工：

• source_material_id：业务必填主键。POST / PUT 请求体、DELETE 都用它；DELETE body 为 { source_material_ids: string[] }
• material_id：Editing API 自己生成的服务端 id。业务方不用传，传了也不会入库；SDK 只在 POST 成功后把返回值记到面板，供轨道内部关联
• source：VeVEditor 轨道 Source / 加密 vid 等资源标识。Editing API 请求体里的 source 是 origin url，与面板 source 不是同一语义

服务端响应缺少 source 时，加载工程仅使用 material_id 作为 source fallback。

浏览器不应持有 AMK API Key。endpoint 应指向业务代理，由代理向 Editing API 注入：

Authorization: Bearer <AMK_API_KEY>

amkeditordemo 默认使用与 Editing API 契约一致的内存 mock。联调真实服务时，在启动 demo 的服务端环境设置：

EDITING_API_UPSTREAM='https://your-editing-api.example.com' \
AMK_API_KEY='<your-api-key>' \
VITE_AMK_PROJECT_ID='<existing-project-id>' \
pnpm --dir packages/amkeditordemo/fe dev

卸载时销毁：

editor.destroy();