本文面向需要在 Web 页面中集成剪辑能力的前端开发者。通过 AI MediaKit Web 剪辑 SDK，你可以在业务页面中嵌入完整的剪辑编辑器，包括素材管理、轨道编辑、特效渲染和视频导出，无需自行拼装底层编辑器组件。

SDK 概述

AI MediaKit 提供一款一站式 Web 剪辑 SDK @volcengine/amk-editor，将编辑器界面、素材管理、轨道编辑、特效渲染和视频导出封装在一个包中，你只需提供剪辑工程标识和业务代理地址，即可在页面中快速嵌入完整的剪辑能力。

能力	说明
主题与布局	SDK 内置了一套开箱即用的专业剪辑界面，你可以轻松将编辑器切换为亮色或暗色主题，以适配你的业务页面风格。同时，SDK 内置了素材面板的收起/展开等布局管理能力，无需额外开发。
剪辑工程管理	你可以将一个剪辑工程理解为一个独立的剪辑任务或草稿，包含了本次剪辑所用到的所有素材（视频、音频、图片）以及它们在时间轴上的排列、应用的特效和字幕等所有编辑信息。SDK 通过唯一的工程 ID projectId 来自动加载和保存你的所有工作。
素材库管理	SDK 提供了完整的素材管理面板。你可以通过它上传本地文件、通过 URL 添加网络资源，或从你自己的业务资产库导入素材（这需要你实现对应的回调函数），SDK 会自动为素材发起抽帧任务生成预览图。所有素材都属于当前剪辑工程，并显示在素材面板中，方便你随时拖拽到轨道上使用。
预设资源	SDK 自带了丰富的预设资源库，包括字体、花字、文字动画、转场、滤镜和特效等。你可以通过配置项决定开启哪些资源面板，为用户提供多样的创作能力。
视频导出	SDK 内置了导出弹窗和相应的参数配置（如分辨率、帧率、格式等）。用户完成配置后，SDK 会将整个剪辑工程提交到服务端进行异步渲染合成，最终输出一个完整的视频文件。用户可在右上角任务列表查看和下载。
ASR 字幕	用户可以在编辑器中一键为视频或音频素材发起语音转字幕（ASR）任务。任务完成后，SDK 会自动将生成的字幕文本和时间戳添加到时间轴的字幕轨道上。

架构与核心概念

在开始集成之前，你需要了解 AI MediaKit Web 剪辑 SDK 的一个核心设计原则：为保障密钥（API Key）安全，浏览器不能直接请求 AI MediaKit 服务，必须通过你自己的业务代理服务来中转。这个代理服务需要由你自己在服务端实现，主要负责两件事：

安全地附加密钥：将存储在你自己服务器上的 AI MediaKit API Key 添加到请求中。

转发请求：将来自 SDK 的请求安全地转发给 AI MediaKit 服务端。

基于此架构，以下两个概念是你接入 SDK 时必须理解并在代码中配置的：

概念	说明
projectId	剪辑工程的唯一标识。SDK 使用此 ID 关联工程的素材库和编辑数据。你需要在初始化 SDK 前通过服务端 API 创建剪辑工程并获取此 ID。
endpoint（业务代理）	业务代理的基础地址，负责注入 AI MediaKit API Key、校验用户权限，并将请求安全地转发到 AI MediaKit 上游。例如，若传入 xxx.xxx.com/api/amk-proxy，SDK 的实际请求路径将是 xxx.xxx.com/api/amk-proxy/{targetPath}/...。

简单来说，你的职责是创建工程、实现代理和配置回调函数，SDK 会负责其余的一切——从界面渲染到数据保存，从素材管理到视频导出。架构图参考如下：

准备工作

在正式开始集成编码前，请确保已完成以下一次性的前置准备，为你后续创建工程、实现代理服务提供必要的权限和凭证。

开通 AI MediaKit 服务：确保你的火山引擎账号已开通 AI MediaKit 服务。

获取并妥善保管 API Key：API Key 是你在服务端调用 AI MediaKit API 进行身份认证的唯一凭证。它与你的账号绑定，具有高权限，必须妥善保管。你可以前往 AI MediaKit 控制台的 API Key 管理页面创建并获取专用 API Key。获取后，可将其配置为你服务端（即业务代理）的环境变量。

完成以上准备后，你已经具备了从服务端安全调用 AI MediaKit API 的所有条件。接下来的快速开始章节将引导你完成具体的编码工作，包括：

调用服务端 API 创建一个剪辑工程，并获得 projectId。

在你的后端项目中，实现用于安全转发请求的业务代理服务。

在你的前端页面中，初始化 SDK 并配置相关回调。

快速开始

本节将引导你完成一个端到端的集成流程。

步骤 1：安装 SDK（前端）

在你的前端项目根目录中执行以下命令，将 SDK 包添加到你的前端项目中。

步骤 2：创建剪辑工程（服务端）

你需要在服务端调用 AI MediaKit OpenAPI API 为用户的每次剪辑创建一个云端草稿箱，获取其唯一标识 projectId，并将返回的 project_id 传递给前端。这个 ID 是后续所有操作的基础。

响应示例：

步骤 3：搭建业务代理（服务端）

搭建一个业务代理，让前端的 SDK 可以通过你的后端服务，间接地调用 AI MediaKit 的 API，从而避免在浏览器中暴露敏感的 API Key。以下是一个基于 Node.js + Express 的最小化实现示例，你可以根据它来构建自己的代理。在实际项目中，你还需要补充用户身份验证、接口限流和操作审计等逻辑。

步骤 4：初始化 SDK（前端）

在你的前端页面中，引入并初始化 SDK，从而在网页的指定位置渲染出剪辑器界面，并加载指定 projectId 的工程数据。你需要为 SDK 提供一个 DOM 容器和从后端获取的 projectId，同时完成实际的上传和媒资管理的回调配置。

步骤 5：批量创建素材（服务端）

如果你需要在用户打开编辑器前，就为工程预置一批素材（例如，从已有的媒资库选择），可以通过服务端 API 进行批量创建素材。

此 API 每次最多支持批量创建 100 条素材。该操作是原子性的，即如果其中任一素材校验失败，则整批操作都会失败，不会写入任何数据。

步骤 6：验证集成效果

完成以上步骤后，启动你的 Web 应用并打开包含编辑器的页面，进行以下验证：

界面渲染：编辑器界面能否正常加载并显示工程名称。

素材加载：若通过 API 预置了素材，检查它们是否显示在素材库面板中。

本地导入：尝试通过“导入”按钮上传本地视频或图片，检查上传成功后是否出现在素材库。

轨道编辑：将素材从素材库拖拽到时间轴轨道上，并进行预览播放。

自动保存：在轨道上进行一些操作（如裁剪、移动）后，刷新页面，检查编辑状态是否被成功恢复。

如果以上步骤均验证通过，恭喜你已成功完成 SDK 的基本集成。

进阶使用

本章介绍更多进阶配置，帮助你根据具体的业务需求深度定制 SDK 的行为和外观。

业务代理设计

在生产环境中，一个健壮的业务代理除了实现基本的请求转发外，还应重点关注安全性和稳定性。以下指南将帮助你构建一个生产级的代理服务。

接口白名单

为了确保你的代理服务不被滥用，只响应来自 SDK 的合法请求，建立一套严格的 API 路径白名单至关重要。SDK 运行时会访问以下路径，请确保你的代理只允许这些路径通过：

方法	路径	用途
GET	/api/v1/editing/projects/{projectId}	读取工程信息
PATCH	/api/v1/editing/projects/{projectId}	修改工程名称
GET	/api/v1/editing/projects/{projectId}/materials	分页读取素材库
POST	/api/v1/editing/projects/{projectId}/materials	新增/批量新增素材
PUT	/api/v1/editing/projects/{projectId}/materials	更新素材信息
DELETE	/api/v1/editing/projects/{projectId}/materials	删除素材
GET	/api/v1/editing/projects/{projectId}/editor	读取编辑数据
PUT	/api/v1/editing/projects/{projectId}/editor	保存编辑数据
POST	/api/v1/editing/projects/{projectId}/tasks	更新工程任务台账
GET	/api/v1/editing/projects/{projectId}/tasks	读取工程任务台账
GET	/api/v1/editing/preset-library	获取花字、转场等资源
GET	/api/v1/editing/preset-library	获取预设资源（字体、特效等）
POST	/api/v1/tools/vibe-editing-common	提交视频导出任务
POST	/api/v1/tools/asr-subtitles	提交 ASR 字幕生成任务
POST	/api/v1/tools/extract-frames	提交抽帧任务（封面/雪碧图）
POST	/api/v1/tools-sync/probe-image-metadata	获取图片元信息（同步）
POST	/api/v1/tools/probe-video-metadata	提交视频元信息获取任务
POST	/api/v1/tools/probe-audio-metadata	提交音频元信息获取任务
GET	/api/v1/tasks/{taskId}	查询异步任务状态

安全要点

API Key 隔离：确保 API Key 始终仅在你的代理服务内部注入，绝不出现在发往代理的浏览器请求中。

权限强校验：务必在代理层校验当前会话的用户是否有权限访问其请求的 projectId，这是防止数据越权的关键。

响应透传：应原样透传 AI MediaKit 服务端返回的 HTTP 状态码和响应体，以便 SDK 能够正确处理成功、失败和任务状态。

日志与监控：建议记录请求 ID、工程 ID、用户 ID 和请求耗时等信息用于问题排查，但日志中绝不能记录 API Key。

素材回调

素材回调是你业务逻辑与 SDK 连接的桥梁。通过实现这些函数，你可以完全控制素材的上传、管理和刷新机制。

导入入口的展示逻辑

SDK 提供灵活的本地上传机制。您可以通过实现 onUploadFile 回调来接管上传流程。作为一种更便捷的选择，如果您使用了火山引擎对象存储（TOS），也可以通过配置 storage.getUploadSTS 来启用 SDK 内置的 TOS 直传功能。上传方式的优先级如下：

TOS 直传：如果配置了 storage.getUploadSTS，SDK 将激活内置的 TOS 上传流程，此时 onUploadFile 和 onUploadMaterial 回调将不会被触发。

自定义上传 onUploadFile：如果没有配置 TOS 直传，SDK 会调用您实现的 onUploadFile 函数来处理每个文件的上传。

旧版自定义上传 onUploadMaterial（已废弃）：为兼容旧版本，如果仅实现了此回调，SDK 仍会调用它。建议您尽快迁移至 onUploadFile。

根据您实现的 material 回调函数，素材面板中“导入”按钮的行为会相应调整：

你配置的回调情况	“导入”按钮的 UI 展示
未配置任何 onUpload 相关回调	不展示“导入”按钮。
只配置一个回调（如 onUploadFile）	直接展示该功能的入口（如“本地导入”）。
配置两个或以上回调	收敛为一个“导入”下拉菜单，包含所有已实现功能对应的子菜单项。

关键回调函数说明

以下是几个核心回调的用途和实现要点：

回调函数	触发时机	你需要做什么
onUploadFile	用户在 UI 上选择了本地文件后。	将单个 File 上传到你的存储服务，然后返回符合 SDK 标准的 MaterialItem 对象。如果配置了 storage.getUploadSTS，此回调不会被触发。
onUploadMaterial	用户在 UI 上选择了本地文件后。	（已废弃）将 File[] 上传到你的存储服务，然后返回 MaterialItem[] 数组。自 v0.0.6 起，建议迁移至 onUploadFile。
onUploadUrlMaterial	用户在 UI 上输入了 URL 链接后。	处理 URL 导入逻辑（如转存、获取元信息），然后返回 MaterialItem[]。
onUploadFromSystem	用户点击“从资产库导入”后。	打开你的业务资产选择器（Modal/Popup），待用户选择完毕后，返回选中的 MaterialItem[] 或 null（如果用户取消选择）。
onRefreshPlayInfo	SDK 初始化时或素材播放地址被判定为过期时。	根据传入的 source_material_id 列表，获取最新的播放地址并返回一个补丁数组。
onPersistExtractUrls	SDK 自动抽取封面/雪碧图完成后。	将抽帧产出的临时 URL 转存为长效地址，并返回新的 URL 和用于后续刷新的存储标识。

播放地址刷新

为保证用户在任何时候都能访问和编辑素材（尤其是使用带时效签名 URL 的场景），您需要实现 onRefreshPlayInfo 回调。

抽帧结果转存

SDK 自动抽取的封面图和雪碧图地址可能是临时的。通过实现 onPersistExtractUrls 回调，你可以将这些产物转存到自己的存储中变为永久资源，并将新的存储标识（如 Object Key）保存回素材对象，以便后续刷新。

UI 配置与资源面板

你可以灵活配置编辑器的外观和功能，使其与你的应用风格保持一致，并提供恰当的功能集。

主题与标题栏

你可以定制编辑器的主题，并定义标题栏中返回、关闭按钮的行为。

资源面板开关

SDK 内置了字体、花字、转场等丰富的预设资源面板。为了简化界面或根据业务需要，你可以选择性地关闭某些面板。

配置项	说明	默认值
font	字体面板	true
wordArt	花字面板	true
textAnimation	文字动画（入场/出场/循环）面板	true
transition	转场面板	true
filter	滤镜面板	true
effect	特效面板	true

将配置项设为 false 后，SDK 将不会在 UI 中展示对应的面板入口，也不会请求相关资源，从而优化加载性能。例如，要禁用花字和转场功能，可以这样配置：

左侧面板布局

SDK 已内置左侧素材面板的收起与展开功能，无需你额外配置。用户点击收起按钮后，预览区域会自动扩展至全宽，并在左侧边缘显示一个“素材”入口用于重新展开面板。

导出与异步任务

当用户点击标题栏的“导出视频”按钮时，SDK 会弹出一个内置的导出配置表单，支持用户设置视频名称、分辨率、帧率、格式、编码方式以及画质增强选项。导出是一个异步过程，后台任务的执行不会影响用户继续编辑。导出时，SDK 会在内部复制一份当前的编辑数据用于提交渲染任务，这不会影响用户当前的工程状态或预览画面。

参考

本章节提供集成 Web 剪辑 SDK 时所需的详细参考信息，包括服务端 API、SDK 初始化配置、实例方法和事件。

服务端 API 参考

以下 API 是你在服务端与 AI MediaKit 后端服务交互时可能需要调用的接口。

基础信息

项目	说明
Host	https://mediakit.cn-beijing.volces.com
Base Path	/api/v1/editing
鉴权方式	Authorization: Bearer <YOUR_AMK_API_KEY>

响应约定

所有接口在 HTTP 层面统一返回 200 OK，具体的业务成功与失败通过响应体内容来区分。

响应体包含	含义
data 字段	表示请求成功。
error 字段	表示请求失败。error.code 字段标明了具体的错误类型。

常见错误码：

error.code	含义
invalid_request	请求参数校验失败。
unauthorized	认证失败或无权访问资源。
not_found	请求的资源不存在。
conflict	资源冲突（例如，尝试创建同名工程）。
internal_error	服务端内部错误。

素材标准格式

所有与素材相关的 API 和回调函数都遵循此标准格式。

字段	类型	说明
material_id	string	工程内素材的唯一 ID。此 ID 由 AI MediaKit 在素材创建成功后自动生成并返回。
source_material_id	string	你必须在创建素材时提供此字段，即业务侧素材的唯一主键（例如 VOD 中的 Vid 或 TOS 中的 Object Key），最长 255 字符，用于素材的更新、删除和刷新等关联操作。
name	string	你必须在创建素材时提供此字段。素材的显示名称，最长 255 字符。
type	string	你必须在创建素材时提供此字段。素材的类型，必须为 video、audio 或 image 之一。
source	string	（供服务端合成使用）素材原片的资源标识符，你必须在创建素材时提供此字段，供服务端在导出合成时使用。如果您将资源托管在火山引擎对象存储 TOS 或者视频点播 VOD 服务，可以使用tos://bucket/xxx 或 vid://xxx 形式的资源标志符，当您开通 MediaKit 服务并进行跨服务授权后，可内网访问您的资源，安全且高效。如果您的资源未托管在火山引擎对象存储 TOS 或者视频点播 VOD 服务，或者您需要主动签发资源访问地址，您需要使用公网可访问的 HTTP/HTTPS 地址。
url	string	（供客户端预览使用）素材在 SDK 中预览播放所用的 URL。你必须在创建素材时提供此字段，此地址必须是浏览器可直接访问的公网 HTTPS 地址。场景区分：性能与画质兼顾（推荐）：为 url 提供低码率版本用于流畅预览，为 source 提供原始高分辨率文件以保证导出质量。简单场景：如果无需区分预览与导出画质，source 和 url 可设为同一个公网地址。
duration	number	当 type 为 video 或 audio 时，此字段为必填项。表示素材的时长，单位为秒。
width	number	当 type 为 video 或 image 时，此字段为必填项。表示素材的宽度，单位为像素。
height	number	当 type 为 video 或 image 时，此字段为必填项。表示素材的高度，单位为像素。
poster	string	可选。视频的封面图地址。如果未提供，SDK 可能会在需要时自动触发抽帧任务来生成。
sprite	object	可选。雪碧图对象，用于在时间轴上快速预览视频内容。通常包含 storeurls (地址数组) 和 capturenum (总帧数) 等字段。

创建工程

POST /api/v1/editing/projects

创建一个新的剪辑工程，并返回其唯一标识 project_id。

请求参数

参数	类型	是否必填	说明
name	string	是	工程名称，最长 255 个字符。
description	string	否	工程的详细描述。

请求示例

响应示例

批量创建素材

POST /api/v1/editing/projects/{projectId}/materials

向指定工程中批量添加素材。此操作是原子性的，任一素材校验失败，整批操作都将失败。

请求参数

参数	类型	是否必填	说明
materials	MaterialItem[]	是	素材对象数组，每个对象需符合素材标准格式。单次请求最多支持 100 条素材。

请求示例

响应示例

批量更新素材

PUT /api/v1/editing/projects/{projectId}/materials

向指定工程中批量更新或插入素材。此操作具有原子性，即请求中的任何一条素材处理失败，整个批次都将回滚，不会写入部分数据。该 API 根据 source_material_id 自动判断执行更新还是插入操作：

更新现有素材：如果请求中某素材的 source_material_id 在工程中已存在，则会更新该素材。此时，你只需提供需要修改的字段。例如，仅传入 name 即可重命名该素材，其他字段将保持不变。

插入新素材：如果 source_material_id 在工程中不存在，则会创建一条新的素材记录。在这种情况下，你必须提供创建素材所需的所有必填字段（如 type, url, source 等）。

请求参数

参数	类型	是否必填	说明
materials	Partial<MaterialItem>[]	是	素材对象数组，每个对象需符合 @素材标准格式。单次请求最多支持 100 条素材。

请求示例

响应示例

SDK 初始化配置

以下是 new AmkEditor() 时可传入的完整配置项列表。

配置项	类型	必填	说明
container	HTMLElement	是	SDK 挂载的 DOM 容器。
projectId	string	是	已创建的剪辑工程 ID。
endpoint	string	是	业务代理服务的地址。
getHeaders	() => Record<string, string>	否	动态获取请求头的函数。该函数会在每次请求业务代理前调用，可用于传递动态认证 Token。
theme	'light' \| 'dark'	否	编辑器主题，默认为 'light'。
header	object	否	标题栏配置，包含 show (boolean), onBack (function), onClose (function)。
material	object	否	素材导入、刷新、转存等相关回调函数的集合。
getLicenseUrl	string \| function	否	用于获取加密视频播放 License 的地址或函数。
storage	object	否	TOS 直传与私有 URL 重签相关配置。
i18n	object	否	国际化语言和自定义文案覆盖。
font ... effect	boolean	否	各资源面板的开关，详见UI 配置与资源面板。
layout, track, toolbar, shortcut	object	否	底层编辑器的布局、时间轴、工具栏和快捷键配置，按需透传。
source	string	否	用于数据埋点的业务来源标识。
accountId	string	否	业务账号或租户 ID，写入埋点参数 AccountID。

SDK 实例方法

AmkEditor 实例上暴露了以下常用方法。

方法	返回值	说明
whenReady()	Promise<this>	返回一个 Promise，在工程加载和编辑器挂载完成后 resolve。
getEditor()	VeVeditor 实例	获取底层的 VeVeditor 编辑器实例，用于调用更丰富的底层能力或监听事件。
refreshPlayInfo(ids?)	Promise<void>	手动触发对指定 material_id 列表或全部素材的播放信息刷新。
destroy()	void	销毁编辑器实例，释放所有资源、事件监听和定时器。

SDK 事件监听

你可以通过 editor.getEditor().on(eventName, handler) 来监听底层编辑器触发的各类事件。

事件名	说明
editParam:changed	轨道或画布参数发生变化。注意：SDK 已实现自动保存，通常无需在此事件中手动提交数据。
element:selected	用户在轨道或画布上选中了某个元素。
track:changed	时间轴轨道上的元素发生了增、删、改。
material:changed	素材面板中的列表内容发生变化。
playback:play / playback:pause	播放器状态在播放和暂停之间切换。
playback:seek	预览播放的时间点发生变化。
history:stackChanged	撤销/重做（Undo/Redo）的历史栈发生变化。
timeline:scaleChanged	用户缩放了时间轴。
crashed	编辑器实例发生崩溃。

监听与销毁示例：

内置资源参考

为了方便你快速构建功能，SDK 内置了丰富的预设资源库，覆盖花字、字体、特效、转场、滤镜和文字动画等多个类别。你可以通过 UI 配置与资源面板按需开启或关闭。

类别	支持效果
花字	黄紫立体黄白突出落日彩虹橙环字节跳动蓝色阴影泛光蓝色泛光银河渐变阴影绿色泛光
字体	思源黑体 Bold 思源黑体 Medium 思源宋体 Bold 阿里巴巴普惠体 Bold 站酷仓耳渔阳体站酷高端黑站酷酷黑体站酷快乐体站酷文艺体站酷小薇 LOGO 体兜底字体
特效	镜像对称九分屏六分屏四分屏三分屏二分屏
转场	叶片翻转百叶窗风吹水滴交替出场旋转放大风车多色混合遮罩转场六角形心型打开故障转换飞眼梦幻放大开门展现对角擦除立方转换透镜变换晚霞转场圆形打开圆形擦开圆形交替时钟扫开
滤镜	质感：清晰、午后、MUJI、白皙、胡桃木、自然复古：香港、童年、老友记、迈阿密、Vintage、美式清新：奶油、初见、鲜亮、梦境、济州、清透美食：日食、赏味、暖食、可口、深夜食堂风景：樱花、柠绿、京都、晚霞、绿妍、春日序
文字动画	入场动画：圆形扫开、溶解显示、向右擦开、向左擦开、向下擦开、向上擦开、向左滑入、向右滑入、向下滑入、向上滑入、渐显、放大、羽化向下擦开、羽化向左擦开、羽化向上擦开、羽化向右擦开循环动画：波浪、翻转出场动画：向右擦除、向左擦除、向下擦除、向上擦除、渐隐、圆形扫除、溶解消失、缩小消失、向右滑出、向左滑出、向下滑出、向上划出、羽化向下擦出、羽化向左擦除、羽化向右擦除、羽化向上擦除

SDK 发布历史

日期	版本号	说明
2026 年 9 月 15 日	0.0.6	优化素材导入、资源加载及编辑器交互体验，修复若干已知问题。
2026 年 8 月 31 日	0.0.3	首次发布。