本文面向需要在 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。获取后，可将其配置为你服务端（即业务代理）的环境变量。

API Key 是高权限凭证，必须严格保管在服务端。严禁将其硬编码在前端代码中或通过任何方式传递到浏览器。浏览器端的所有请求都应只访问你自己的业务代理地址。

快速开始

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

步骤 1：安装前端 SDK

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

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

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

$AMK_API_KEY：替换为你从 AI MediaKit 控制台的 API Key 管理页面获取并安全存储在服务端的 AI MediaKit API Key。

响应示例：

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

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

步骤 4：在前端初始化 SDK

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

回调返回的素材对象必须符合 SDK 的标准格式，具体字段请参考素材标准格式。

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

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

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

步骤 6：验证集成效果

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

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

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

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

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

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

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

进阶使用

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

素材导入与存储

本节先帮助你选择素材接入方式，再分别说明自定义素材接入和 SDK 内置素材存储的配置方法。

选择接入方式

用户从本地导入素材时，你可以选择以下任一方式将文件上传到存储服务：

自定义上传：通过 material.onUploadFile 将文件上传到你的存储服务。适用于已经具备素材上传服务，或需要自行控制上传流程的业务。

SDK 内置上传：通过 storage 配置 TOS 存储桶或 VOD 点播空间。SDK 负责上传文件并获取编辑器预览所需的播放地址，适用于希望直接使用火山引擎存储服务的业务。具体操作请参见配置 SDK 内置 TOS 素材存储或配置 SDK 内置 VOD 素材存储。

本地文件上传方式按以下顺序选择：

配置 material.onUploadFile 时，SDK 使用该回调上传每个文件。

未配置 material.onUploadFile，并且 storage 的两个字段均已配置时，SDK 使用内置 TOS 或 VOD 上传。

如果以上上传方式均未配置，SDK 不展示本地上传入口。

导入入口的展示逻辑

根据你实际启用的导入能力，素材面板中“导入”按钮的展示会相应调整：

已启用的导入能力	“导入”入口展示
没有任何本地上传、URL 导入或资产库导入能力	不展示“导入”按钮。
仅一种能力（含 SDK 内置本地上传）	直接展示对应入口（如“本地导入”）。
两种及以上能力	收敛为“导入”下拉菜单，列出所有已启用的入口。

配置上传并发

material.uploadConcurrency 接受正整数（例如 3），用于限制单文件上传、SDK 内置上传和临时文件转存的并发数。上传成功的文件会正常添加到素材库，单个文件失败不会影响其他文件。URL 导入仍整批调用 onUploadUrlMaterial(urls)；临时文件转存按单条 URL 调用，未配置时最多同时处理 5 条。业务资产库导入的并发需由你的业务自行控制。

配置自定义素材接入

你可以通过素材回调接入自有存储或资产库，并按需更新素材的播放地址、封面和雪碧图。

关键回调函数说明

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

回调函数	触发时机	你需要做什么
onUploadFile	用户在界面中选择本地文件后。	将单个 File 上传到你的存储服务，并返回一条符合 SDK 标准的 MaterialItem。返回值必须包含唯一且不变的 source_material_id。
onUploadUrlMaterial	用户输入素材 URL 后。	根据 URL 获取或转存素材，并返回 MaterialItem[]。
onUploadFromSystem	用户选择从资产库导入后。	打开你的资产选择界面，并返回用户选中的 MaterialItem[]；用户取消选择时返回 null。
onRefreshPlayInfo	使用业务自定义存储，并且 SDK 初始化或素材播放地址过期时。	返回需要更新的播放地址等素材字段。使用 SDK 内置 TOS/VOD 存储时无需配置。
onPersistExtractUrls	SDK 完成封面或雪碧图抽取后。	将生成的临时文件保存到你的存储服务，并返回新的访问地址和存储标识。长效地址写入 poster 或 sprite 后，建议清除对应的 poster_task_id 或 sprite_task_id。

播放地址刷新

以下示例展示如何为业务自定义存储刷新具有有效期的素材地址：

抽帧结果转存

SDK 自动生成的封面图和雪碧图地址可能具有有效期。通过实现 onPersistExtractUrls 回调，你可以将这些文件保存到自己的存储中，并将新的访问地址和存储标识（如对象键）保存到素材信息中。

从业务代码触发素材导入

调用 requestMaterialImport(type, { onMaterialsImported }) 可打开 local、url 或 system 对应的导入入口，其中的 onMaterialsImported 回调只对本次调用生效。你也可以通过 material.onMaterialsImported 统一监听素材导入结果。

SDK 内置素材存储的通用配置

启用 SDK 内置上传时，需在顶层 storage 中同时配置以下两个字段；缺少任一字段都会导致 SDK 初始化失败。

配置项	类型	是否必填	默认值	说明
storage.media_output_destination	string	条件必填	-	素材上传和媒体处理产物的存储目标。TOS 使用 tos://<bucket>[/<对象前缀>]，VOD 使用 vod://<空间名>。outputDestination 不是有效配置项。
storage.getUploadSTS	() => Credentials \\| Promise<Credentials>	条件必填	-	从你的业务服务端获取短期访问凭证。接口应直接返回凭证对象；如响应包含 data 包装层，需在回调中取出 data。TOS 与 VOD 的返回字段不同，详见对应章节。

同一份 storage 配置只能指定 TOS 或 VOD 中的一种上传目标。

配置 SDK 内置 TOS 素材存储

为了长期保存和管理素材、控制访问权限与存储成本，你可以将 AI MediaKit Web 剪辑 SDK 与你的火山引擎对象存储（TOS）进行集成。本章节将引导你完成从创建存储桶、配置权限到代码接入的全过程。

核心概念

在开始之前，请先了解以下与 TOS 相关的核心概念：

概念	说明
存储桶（Bucket）	TOS 中存放对象的顶层容器。存储桶名称、地域（Region）、访问权限和跨域资源共享（CORS）规则都在存储桶级别配置。当前 SDK 内置的上传功能固定使用 cn-beijing 地域，因此请务必创建位于“华北 2（北京）”地域的存储桶。
对象（Object）	存储桶中的文件，例如视频、音频、图片、封面或雪碧图。
对象键（Key）	对象在存储桶内的唯一名称，例如 amk-editor/project-123/uuid-demo.mp4。其中的“目录”只是对象键的前缀，并非真实的文件夹结构。
tos:// 地址	表示 TOS 资源位置的固定地址，例如 tos://example-bucket/amk-editor/demo.mp4。该地址用于在剪辑工程、素材库和任务结果中记录素材位置，但浏览器不能直接播放。
签名 URL	由临时 STS 凭证对私有对象生成的、具有时效性的 HTTP(S) GET 地址。播放器实际使用的是此 URL。任何持有者都可在有效期内访问，因此切勿在数据库中记录或长期缓存。

最佳实践：为了数据安全，建议将存储桶访问权限设为“私有”。在你的数据库和剪辑工程中，始终使用固定的 tos://bucket/key 地址保存素材位置。仅在前端页面需要播放或展示时，才通过 STS 服务动态生成临时的签名 URL。

工作流程

以下为浏览器、你的业务服务端与火山引擎云服务（TOS、STS、IAM）之间的完整交互流程：

用户在浏览器中选择本地文件准备上传，或打开一个包含 tos:// 素材的已有工程。

前端 SDK 调用你在初始化时提供的 getUploadSTS 回调函数，向你的业务服务端请求临时上传凭证。

你的业务服务端在验证用户身份和权限后，使用其安全存储的长期 AK/SK 调用火山引擎 STS 服务的 AssumeRole 接口。

STS 服务返回一组有时效性的临时凭证，业务服务端将这些凭证返回给前端。

SDK 使用临时凭证上传文件或为已有文件生成临时播放地址。

上传成功后，SDK 将 tos://bucket/key 地址保存到剪辑工程，并使用临时播放地址展示素材。

步骤 1：创建并配置 TOS 存储桶

创建存储桶：前往火山引擎对象存储 TOS 控制台创建一个存储桶（例如 example-bucket）：

地域（Region）：必须选择华北2（北京）。

访问权限：建议选择私有。

建议为每个剪辑工程规划独立的对象前缀，例如 amk-editor/<projectId>/，以便分别控制访问权限和统计存储成本。

配置跨域访问（CORS）：在存储桶的权限管理 > 跨域访问设置中，添加一条规则：

来源（Origin）：填写你的业务页面域名。

允许的请求方法（Methods）：至少包含 PUT、GET、HEAD。

允许的请求头（Allow-Headers）：为方便调试，可先设置为 *。在生产环境中，应仅保留浏览器实际发出的请求头，如 Content-Type、x-tos-content-md5。

允许浏览器访问的响应头（Expose-Headers）：建议包含 ETag 和 x-tos-request-id，便于排查问题。

为确保安全，请勿在生产环境中使用通配符 * 作为来源。请始终配置准确的业务域名。

步骤 2：配置 IAM 角色与权限策略

遵循最小权限原则，推荐使用一个专用的 IAM 子账号来调用 STS 服务，并创建一个仅允许访问特定 TOS 资源的角色。切勿在业务服务端硬编码主账号的长期密钥，更不能将任何长期密钥下发给浏览器。

创建 STS 调用者（IAM 子账号）：

前往火山引擎访问控制（IAM）控制台 > 用户页面创建一个用户。

为其创建并保存访问密钥（AK/SK），此密钥将部署在你的业务服务端。

为该子用户授予 STSAssumeRoleAccess 权限，或创建一个仅允许对特定角色执行 sts:AssumeRole 操作的更严格的自定义策略。

创建用于上传的 IAM 角色：在 IAM 控制台的角色管理页面中创建一个角色。信任身份选择当前账号，策略选择 STSAssumeRoleAccess。

为角色绑定 TOS 权限策略：创建一个自定义策略，仅授予必要的 TOS 操作权限，然后将其绑定到角色上。切勿直接授予 TOSFullAccess。以下示例仅允许对 example-bucket 下 amk-editor/ 前缀内的对象执行上传和读取操作，请将桶名和前缀替换为你的配置。

{
"Statement": [
{
"Effect": "Allow",
"Action": [
"tos:PutObject",
"tos:GetObject"
],
"Resource": [
"trn:tos:::example-bucket/amk-editor/*"
]
}
]
}

记录角色 TRN：在角色详情页面，复制并保存其 TRN（火山引擎资源名称），格式为 trn:iam::<AccountId>:role/<RoleName>。此 TRN 将用于服务端的 AssumeRole 调用。

步骤 3：实现 STS 临时凭证签发接口

在你的业务服务端创建一个接口，例如 /api/tos-upload-sts，用于接收前端的凭证请求并返回 STS 临时凭证。以下 Node.js 示例仅演示核心逻辑。生产环境的接口必须包含完整的用户登录状态校验、剪辑工程 projectId 访问权限检查、接口限流和日志审计。

storage.getUploadSTS 最终返回的对象必须包含以下字段：

字段	类型	是否必填	默认值	说明
accessKeyId	string	是	-	临时 Access Key ID。
accessKeySecret	string	是	-	临时 Secret Access Key。
stsToken	string	是	-	临时 Session Token。
expiration	string \\| number	是	-	凭证过期时间，支持 ISO 8601、秒级时间戳或毫秒级时间戳。SDK 根据该字段按需更新凭证；生成的签名 URL 最长有效 24 小时，且不会超过凭证的剩余有效期，请勿长期缓存。

步骤 4：配置 SDK

示例中的 /api/tos-upload-sts 是你自行实现的业务接口。

如果需要将视频导出、抽帧等 AI MediaKit 任务的产物保存到该 TOS 存储桶，还需前往 AI MediaKit 控制台的基础配置 > 授权管理页面，完成访问 TOS 的跨服务授权。getUploadSTS 返回的临时凭证仅供浏览器上传和访问素材使用，不能替代该授权。

配置 SDK 内置 VOD 素材存储

你可以将 SDK 接入自有的火山引擎视频点播（VOD）空间。配置完成后，SDK 会将用户选择的视频、音频或图片上传至指定空间，并获取编辑器预览素材所需的播放地址。

核心概念

概念	说明
点播空间（Space）	VOD 中承载媒体文件的顶层容器，由空间名（spaceName）唯一标识。本地上传的素材会保存到该空间。
vod:// 地址	表示上传目标空间的固定地址，格式为 vod://<space>。只填写空间名，不包含 Vid、子目录、查询参数或 URL 片段。该地址用于声明上传目标，不是浏览器可直接播放的 HTTP 地址。
STS 临时凭证	由业务服务端为当前登录用户签发的短期 VOD 访问凭证。SDK 使用该凭证上传文件、发布媒体文件并查询播放信息，浏览器无需持有长期 AK/SK。

工作流程

以下为浏览器、你的业务服务端与火山引擎 VOD 服务之间的交互流程：

用户在浏览器中选择本地文件。

前端 SDK 调用 getUploadSTS，向你的业务服务端请求临时凭证。

你的业务服务端校验用户和剪辑工程的访问权限后，使用安全存储的长期 AK/SK 为目标点播空间签发 STS 临时凭证。

SDK 使用临时凭证完成文件上传、媒体文件发布和播放信息查询。

后续加载工程或播放地址过期时，SDK 再次调用 getUploadSTS 获取临时凭证并更新播放地址。

步骤 1：创建点播空间

在火山引擎视频点播控制台创建点播空间并记录空间名。storage.media_output_destination 应配置为 vod://<空间名>，不要填写播放域名、Vid 或 HTTP(S) 地址。

步骤 2：实现 VOD STS 临时凭证签发接口

在业务服务端创建一个接口，为当前登录用户签发目标点播空间的 STS 临时凭证。该接口应先校验用户和剪辑工程的访问权限；长期 AK/SK 只能保留在服务端，不能下发到浏览器。

临时凭证应仅包含以下权限：

Vod:ApplyUploadInfo

Vod:CommitUploadInfo

Vod:UpdateMediaPublishStatus

Vod:GetPlayInfo

storage.getUploadSTS 最终返回的对象必须包含以下字段，且字段名区分大小写：

字段	类型	是否必填	默认值	说明
AccessKeyId	string	是	-	临时 Access Key ID。
SecretAccessKey	string	是	-	临时 Secret Access Key。
SessionToken	string	是	-	临时 Session Token。
ExpiredTime	string	是	-	凭证过期时间，建议使用 ISO 8601 格式。SDK 获取的播放地址有效期不会超过凭证的剩余有效期和 24 小时上限，且可能受点播域名鉴权配置影响，请勿长期缓存。
CurrentTime	string	是	-	服务端签发凭证时的当前时间。

你需在服务端安装 @volcengine/openapi，并配置具备目标点播空间访问权限的 AK/SK。

示例中的 Resource: [] 未限定可访问的目标空间资源。生产环境应按照点播授权规则，仅授予必需的权限。

步骤 3：配置 SDK

示例中的 /api/vod-upload-sts 是你自行实现的业务接口。同一份 storage 配置只能指定一个上传目标，不能同时配置 TOS 和 VOD。

业务代理安全加固

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

接口白名单

为了确保你的代理服务不被滥用，只响应来自 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	保存编辑数据
GET	/api/v1/editing/preset-library	获取预设资源（字体、花字、转场等）
POST	/api/v1/tools/multi-track-edit	提交视频导出任务
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，以便 SDK 正确处理成功、失败和任务状态。

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

CORS 与动态请求头

SDK 发往 AI MediaKit 的请求会固定携带 X-Amk-Task-Source: vibe-editing 请求头，请确保代理的 CORS 配置允许该请求头通过。getHeaders 可返回对象或 Promise，并在每次请求前重新获取，适合传递短期业务 Token。存储直传、成片 CDN 与业务代理需要分别配置各自的 CORS。

UI 配置与资源面板

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

主题与标题栏

你可以定制编辑器的主题，并定义标题栏中返回、关闭按钮的行为。header.mount 可挂载外部顶栏，header.onTitleUpdateSuccess 会在标题保存成功后触发。

资源面板开关

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

配置项	类型	是否必填	默认值	说明
font	boolean	否	true	是否显示字体面板。
wordArt	boolean	否	true	是否显示花字面板。
textAnimation	boolean	否	true	是否显示文字入场、出场和循环动画面板。
transition	boolean	否	true	是否显示转场面板。
filter	boolean	否	true	是否显示滤镜面板。
effect	boolean	否	true	是否显示特效面板。

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

左侧面板布局

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

配置字幕识别服务（ASR）

字幕识别默认使用 AI MediaKit 的 asr-subtitles 工具。如果希望改为通过 AI MediaKit 代理调用大模型（MaaS）来完成识别，可以将工具栏的 asr.provider 设为 maas：

设为 maas 后，用户仍从工具栏的字幕识别入口发起任务，但 SDK 会改为通过 AI MediaKit 代理调用大模型。使用此方式前，请先在火山方舟控制台开通所需模型，或在豆包语音控制台开通语音识别能力；然后前往 AI MediaKit 控制台的基础配置 > 授权管理页面完成相应的跨服务授权。仅配置 provider: maas 不会自动开通服务或授予权限。此外，业务代理还需允许访问 extract-audio、transcode-audio、call-maas-proxy 和任务查询相关路径。识别期间，源媒体 URL 必须可被服务端访问；处理过程中生成的临时音频不会添加到素材库。

关于能力开通与接入的更多说明，请参考代理调用大模型（call-maas-proxy）接口文档。

导出与异步任务

当用户点击标题栏的“导出视频”按钮时，SDK 会弹出一个内置的导出配置表单，支持用户设置视频名称、分辨率、帧率、格式、编码方式以及画质增强选项。导出是一个异步过程，后台任务的执行不会影响用户继续编辑。

header.exportTaskList: false 可关闭导出记录入口及其查询；export.qualityEnhancement: true 可展示画质增强选项。当前导出记录列表仅属于本次页面会话，刷新后不会恢复历史列表。

提交导出任务不会改变用户当前的工程状态或预览画面。如果用户选择的导出分辨率与画布分辨率不同，SDK 会自动适配导出内容。

SDK 支持的异步任务类型及其对应的 Tool 接口如下：

任务类型	Tool 接口	说明
视频导出	multi-track-edit	将剪辑工程的编辑数据渲染合成为一个视频文件。
ASR 字幕	asr-subtitles	对指定的视频或音频素材进行语音识别，生成字幕文本。
抽帧	extract-frames	为视频素材生成封面图或雪碧图。

所有异步任务都通过 GET /api/v1/tasks/{taskId} 接口轮询状态。其中，ASR 字幕任务在 SDK 中表现为阻塞式体验：提交后会显示进度弹窗，并每 3 秒查询一次任务状态，任务成功后结果会自动写入当前工程的字幕轨道；如果用户在此过程中取消或关闭弹窗，本次任务结果将被丢弃。

参考

本章节提供集成 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，由 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/key 或 vid://<Vid>；其他资源需使用服务端可访问的 HTTP(S) 地址。
url	string	是	-	SDK 预览素材使用的公网 HTTPS 地址。建议使用低码率版本保证预览流畅，并在 source 中保留原始资源；无需区分时可与 source 相同。
duration	number	条件必填	-	当 type 为 video 或 audio 时必填，单位为秒。
width	number	条件必填	-	当 type 为 video 或 image 时必填，单位为像素。
height	number	条件必填	-	当 type 为 video 或 image 时必填，单位为像素。
poster	string	否	-	视频封面图地址。未提供时，SDK 可能按需提交抽帧任务。
sprite	object	否	-	雪碧图对象，用于在时间轴上预览视频内容，通常包含 storeurls（地址数组）和 capturenum（总帧数）。
waveform	object	否	-	音频波形数据，用于在时间轴上展示音频。
业务自定义字段	任意	否	-	可添加 my_custom_field 等业务字段，服务端 API 会在存储和返回时原样保留。

创建工程

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> \\| Promise<Record<string, string>>	否	-	每次请求业务代理前动态获取请求头，适合传递短期认证 Token。
theme	'light' \\| 'dark'	否	'light'	编辑器主题。
header	object	否	-	标题栏配置，包含 show、onBack 和 onClose。
material	object	否	-	素材导入、刷新、转存等相关回调函数的集合。
export	object	否	-	导出弹窗及导出参数配置。
getLicenseUrl	string \| function	否	-	用于获取加密视频播放 License 的地址或函数。
storage	object	否	-	SDK 内置 TOS/VOD 上传配置。storage.media_output_destination 与 storage.getUploadSTS 必须同时配置。详见配置 SDK 内置 TOS 素材存储和配置 SDK 内置 VOD 素材存储。
i18n	object	否	-	国际化语言和自定义文案覆盖。
font ... effect	boolean	否	true	字体、花字、文字动画、转场、滤镜和特效等资源面板的开关，详见UI 配置与资源面板。
layout, track, toolbar, shortcut	object	否	-	编辑器布局、时间轴、工具栏和快捷键配置。
interaction.readonly	boolean	否	false	是否启用只读模式。
frameRate	object	否	-	帧模式和帧率配置。
timeDisplayFormat	'hms' \\| 'msms' \\| 'msf'	否	-	时间轴的时间显示格式。
debug	boolean	否	false	是否输出调试日志。
source	string	否	-	用于区分 SDK 接入业务的来源标识。
accountId	string	否	-	业务账号或租户标识。

SDK 实例方法

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

方法	返回值	说明
whenReady()	Promise<this>	返回一个 Promise，在工程加载和编辑器挂载完成后 resolve。
getEditor()	VeVeditor 实例	获取底层的 VeVeditor 编辑器实例，用于调用更丰富的底层能力或监听事件。
getI18n()	i18n 实例	获取国际化实例，可用于动态切换语言。
requestExport()	Promise<result>	以编程方式触发并打开导出弹窗。
requestMaterialImport(type, options?)	boolean	以编程方式打开 local、url 或 system 类型的素材导入入口。options.onMaterialsImported 仅对本次调用生效。
getProject()	object	同步获取当前工程的数据快照，包括工程名称、素材和编辑数据。
fetchProjectMaterials()	Promise<MaterialItem[]>	从服务端拉取并返回最新素材列表。此方法只返回数据，不会自动更新素材面板。
refreshPlayInfo(ids?)	Promise<void>	手动触发对指定 material_id 列表或全部素材的播放信息刷新。
invokeTool(options)	Promise<T>	调用 AI MediaKit 通用 Tool 接口。
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 配置与资源面板按需开启或关闭对应面板。各类别的预设项如下：

类别	数量	预设项
字体	11	思源黑体 Medium、思源黑体 Bold、思源宋体 Bold、阿里巴巴普惠体 Bold、站酷高端黑、站酷酷黑体、站酷快乐体、站酷文艺体、站酷小薇 LOGO 体、站酷仓耳渔阳体、兜底字体
花字	12	基础文字、落日、彩虹、银河、橙环、黄白突出、黄紫立体、绿色泛光、蓝色泛光、蓝色阴影泛光、渐变阴影、字节跳动
特效	6	二分屏、三分屏、四分屏、六分屏、九分屏、镜像对称
转场	72	画笔擦除、黑屏闪入、闪烁、交叉溶解、闪白、圆形擦开、冰霜扩散、风吹、对角擦除、六角形、黑烟、六边形散景、漫画纸效果、星光叠化、纸团、切片闪切、泼溅、手持摇移、吊臂弧线、胶片滚动、旋转放大、梦幻放大、快门 II、风车、时钟扫开、左挥扫、圆形交替、向右擦除、滑动、心型打开、立方转换、开门展现、交替出场、下落展开、圆形打开、梦幻光斑、偏振虹彩、彩胶叠影、晚霞转场、多色混合、绸光柔影、泛光、霓彩网格、闪动光斑、霓虹描边、极光光幕、抖动缩放、波动、水滴、漩涡、飞眼、右扭转、涂鸦放大、鱼眼 III、压缩、迷幻震动、透镜变换、故障模糊、快门残影、像素化、信号故障、模糊、雪花故障、故障转换、胶片故障、径向脉冲、帧拉取、圆形分割 II、遮罩转场、分割对比、百叶窗、叶片翻转
滤镜	29	清晰、午后、MUJI、白皙、胡桃木、自然、香港、童年、老友记、迈阿密、Vintage、美式、奶油、初见、鲜亮、梦境、济州、清透、日食、赏味、暖食、可口、深夜食堂、樱花、柠绿、京都、晚霞、绿妍、春日序
文字入场动画	16	渐显、放大、溶解显示、圆形扫开、向上擦开、向下擦开、向左擦开、向右擦开、向上滑入、向下滑入、向左滑入、向右滑入、羽化向上擦开、羽化向下擦开、羽化向左擦开、羽化向右擦开
文字循环动画	2	波浪、翻转
文字出场动画	16	渐隐、缩小消失、溶解消失、圆形扫除、向上擦除、向下擦除、向左擦除、向右擦除、向上划出、向右滑出、向左滑出、向下滑出、羽化向上擦除、羽化向下擦出、羽化向左擦除、羽化向右擦除

SDK 发布历史

日期	版本号	说明
2026 年 10 月 20 日	0.0.10	新增内置 TOS / VOD 存储接入，支持将本地素材上传至指定存储桶或点播空间；支持通过 MaaS 模型代理 API 生成字幕；优化素材上传和剪辑工程更新体验。
2026 年 9 月 15 日	0.0.6	优化素材导入、资源加载及编辑器交互体验，修复若干已知问题。
2026 年 8 月 31 日	0.0.3	首次发布。