本文档面向需要在 Web 应用中集成 AI 智能剪辑能力的前端及服务端开发者。通过 AI MediaKit Web 智能剪辑 SDK（@volcengine/amk-editor-assistant），您可以在业务页面中嵌入一套 AI 驱动的视频创作工具，实现从素材管理、智能编排、特效渲染到高清导出的完整剪辑流程，而无需自行集成多个剪辑组件和 AI 模型。

SDK 概述

@volcengine/amk-editor-assistant 是一款面向浏览器环境的一站式智能视频剪辑 SDK，将 AI 助手与剪辑器集成在同一界面中，用户可以通过自然语言完成视频创作。

核心能力	说明
AI 助手	用户可通过自然语言对话完成复杂编辑操作，如“理解视频内容，剪辑出高光片段，并添加字幕”、“使用我提供的素材生成一条结构完整的混剪 vlog”，AI 助手会自动理解意图并调用相应工具执行。
Web 剪辑器	内置功能完备的剪辑器，支持多轨道编辑、精确裁剪、实时预览、文本与字幕添加、特效、转场、滤镜等专业能力，满足精细化调整需求。
丰富的云端 AI 工具	内置多种 AI MediaKit 工具，如语音识别（ASR）、视频抽帧、视频理解、高光识别等，AI 助手可根据用户指令自动选择并调用。
场景化智能剪辑工具	提供多种可直接使用的场景方案，如高光剪辑（通用/短剧）、AI 短漫剧粗剪、多素材智能混编和 vlog 视频混剪，能自动完成素材筛选、内容编排和后期效果处理，提升成片效率。

架构与核心概念

集成 Web 智能剪辑 SDK 时，您的应用前端（浏览器）将与您的业务服务端（代理服务）以及 AI MediaKit 服务端进行交互。

请求流程

浏览器中的请求分为剪辑器和 AI 助手两类。两类请求共用顶层 endpoint 指定的业务代理入口，SDK 会分别追加对应的 AI MediaKit 服务路径：

请求类型	SDK 配置入口	主要职责
剪辑器（Editing API）	顶层 endpoint、getHeaders	加载与保存剪辑工程、管理素材、调用编辑工具（如转码、拼接）、查询任务状态和访问预设资源库。
AI 助手（Assistant Runtime API）	顶层 endpoint（自动生成 AI 助手服务地址）、assistant.runtime.getHeaders	进行大模型推理、管理对话历史、调用 AI 助手工具（包括云端剪辑工具和前端工具）。

业务代理

为保障密钥（API Key）安全，浏览器不能直接请求 AI MediaKit 服务。所有请求都必须通过您自己实现的业务代理服务进行中转。该服务主要负责：

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

校验业务权限：验证当前登录用户是否有权访问其正在操作的 projectId，防止用户访问不属于自己的数据。

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

费用说明

使用 Web 智能剪辑 SDK 可能产生三类费用：火山方舟大模型调用费、AI MediaKit 视频工具费和 AI MediaKit 剪辑工具费。费用遵循日结后付费模式，次日 6:00 生成前一日的账单并进行结算。

火山方舟大模型调用费

AI 助手在进行自然语言对话（推理模型）和多模态内容理解（多模态理解模型）时，会调用您在 SDK 中配置的火山方舟大模型。此部分费用由火山方舟根据模型调用过程中实际消耗的 Token 数量（包括输入和输出 Token）进行计费。关于不同模型的 Token 计费标准，请查阅火山方舟最新官方定价说明。

AI MediaKit 工具费用

在 AI 助手自动执行任务或用户手动编辑的过程中，可能会调用多种 AI MediaKit 工具。这些工具将按照各自的计费规则进行计费，主要包括以下两类：

视频工具：当 AI 助手需要理解视频内容或执行特定处理时，会调用字幕识别、视频抽帧、视频理解、高光识别等视频工具。这些工具将按照各自的计费规则进行计费，详细规则请参阅视频工具计费。

剪辑工具：当您或您的用户执行“导出视频”操作时，会产生剪辑费用。该费用基于最终输出的视频时长和分辨率进行计费。详细规则请参阅剪辑工具计费。

准备工作

在开始编码前，请确保已完成以下准备：

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

获取 API Key：在 AI MediaKit 控制台的 API Key 管理页面创建并获取 API Key。此凭证将用于您的服务端代理。

获取模型 Endpoint ID：前往火山方舟控制台开通管理页面，开通所需的大模型服务并获取其 Endpoint ID。Web 智能剪辑 SDK 依赖以下两类模型协同工作：

推理模型（必需）：负责处理用户在对话中输入的自然语言指令及流程规划。您必须在 SDK 初始化时通过 assistant.model 参数配置一个推理模型的 Endpoint ID。您可以根据回复准确度、响应耗时和综合成本等因素选择以下模型之一：

doubao-seed-2.1-pro

doubao-seed-2.1-turbo

doubao-seed-2.0-pro

多模态理解模型：负责理解视频、音频、图片等媒体内容。在 SDK 初始化时通过 assistant.preferMultiModalModels 参数进行配置。

视觉理解（推荐）：建议从 doubao-seed-2-1-turbo-260628 或 doubao-seed-2-1-pro-260628 中选择一个配置，以支持视频画面、图片等视觉内容的理解。

音频理解（按需）：当您需要 AI 助手理解音频内容时，可配置一个具备音频理解能力的多模态模型 Endpoint ID，例如 doubao-seed-2-0-lite-260428。

进行跨服务授权：前往 AI MediaKit 控制台基础配置 > 授权管理页面，为 AI MediaKit 授予访问您的火山方舟资源的权限。

快速开始

本节将引导您完成一次完整集成，快速运行一个基本的智能剪辑应用。

步骤 1：安装前端 SDK

在您的前端项目根目录中执行以下命令：

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

在您的服务端，为用户的每次创作会话调用 AI MediaKit API 创建一个云端剪辑工程，并将其唯一标识 project_id 传递给前端。

请求示例

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

响应示例

保存 data.project_id，并将其作为 projectId 传递给前端。

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

剪辑器和 AI 助手共用一个业务代理入口（例如 /api/amk-proxy）。SDK 会在该入口后分别追加 Editing API 和 Assistant Runtime API 的完整路径。以下 Node.js + Express 示例已同时限定两组 API 可以访问的路径，并实现请求转发；在实际项目中，您还需补充用户身份验证、剪辑工程权限校验、接口限流和操作审计。

SDK 发往业务代理的请求会固定携带 X-Amk-Task-Source: vibe-editing 请求头。如果您的业务页面与代理服务跨域部署，请在代理的 CORS 配置中允许该请求头。

步骤 4：在前端初始化 SDK

在您的前端页面中，引入 SDK 及其样式，准备一个 DOM 容器，然后调用 createAmkEditorAssistant 方法创建实例并将其渲染到容器中。

准备容器

创建实例

步骤 5：验证集成效果

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

界面渲染：左侧 AI 助手面板与右侧剪辑器界面能否正常加载，并且能看到工程的标题、素材与时间轴。

请求认证：检查浏览器网络请求，确认所有对 /api/amk-proxy 的请求都携带了业务 Token，并且浏览器代码中没有硬编码的长期 API Key。

对话与联动：向 AI 助手发送一条指令（如“帮我剪一个 15 秒的视频”）。检查 AI 是否能响应，并在运行期间编辑器是否变为只读状态。

素材导入：尝试上传一个媒体文件，检查上传成功后素材是否出现在素材库并被自动加入对话。如果使用自定义上传，再检查 onUploadFile 是否被调用。

恢复：刷新页面，检查同一 projectId 是否能恢复剪辑工程及其绑定的 AI 对话历史。

资源释放：离开页面时，检查 sdk.destroy() 是否被调用，确保没有内存或事件监听器泄漏。

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

进阶使用

本章介绍完成基本集成后可按需配置的素材上传与存储方案。

素材导入与存储

本节先帮助您选择素材上传方式，再说明 SDK 内置 TOS/VOD 存储的配置方法。

选择接入方式

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

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

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

如果同时配置 material.onUploadFile 和 storage，SDK 优先使用 material.onUploadFile。两种方式均未配置时，SDK 不展示本地上传入口。

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 的访问权限检查、接口限流和日志审计。

为了能被 SDK 内置的 TOS 上传模块正确识别，接口响应体必须包含以下字段：

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

步骤 4：在前端 SDK 初始化时配置 storage

在前端初始化 createAmkEditorAssistant 时，传入 storage 配置项，即可启用 SDK 内置的 TOS 上传功能。

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

配置 SDK 内置 VOD 素材存储

除对象存储（TOS）外，您还可以将火山引擎视频点播（VOD）的点播空间作为本地素材的上传目标。您只需在初始化 SDK 时通过 storage 指定目标空间，并提供一个获取临时凭证的回调；文件上传、媒资发布以及播放地址的获取与刷新都由 SDK 自动完成，您无需自行对接 VOD 的上传或播放接口。

核心概念

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

概念	说明
点播空间（Space）	VOD 中承载媒资的顶层容器，由空间名（spaceName）唯一标识。本地上传的素材会提交到该空间进行存储与发布。
vod:// 地址	表示上传目标空间的固定地址，格式为 vod://<space>，只填写空间名，不带 Vid、子目录、查询参数或 URL 片段。它用于声明上传目标，不是浏览器可直接播放的 HTTP 地址。
STS 临时凭证	由服务端为当前登录用户签发的、具有时效性的点播访问凭证。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

接口需返回以下五个字段，供前端 getUploadSTS 原样返回给 SDK：

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

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

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

步骤 3：在前端 SDK 初始化时配置 storage

您在前端初始化 createAmkEditorAssistant 时，通过 storage 配置点播空间目标和临时凭证回调，即可启用 SDK 内置的 VOD 上传功能。

上述 /api/vod-upload-sts 为业务自行实现的接口，不是 SDK 固定地址。storage 中的 media_output_destination 与 getUploadSTS 必须同时配置；同一 storage 配置只能指定一个当前上传目标，TOS 或 VOD，二者不可混用。

参考

本章节提供集成 Web 智能剪辑 SDK 时所需的 SDK 初始化配置、实例方法和核心数据结构。

SDK 初始化配置

以下为 createAmkEditorAssistant(options) 的完整配置项。本章节仅列出各配置项的表格说明；完整的初始化示例请参见快速开始、配置 SDK 内置 TOS 素材存储和配置 SDK 内置 VOD 素材存储。

顶层配置

配置项	类型	是否必填	默认值	说明
container	HTMLElement	是	-	已存在且有明确宽高的容器节点。
projectId	string	是	-	当前剪辑工程 ID，同时用于绑定 AI 助手会话和工程上下文。
endpoint	string	是	-	剪辑器与 AI 助手共用的业务代理基础地址；SDK 会在其后自动追加对应的服务路径。
getHeaders	() => Record<string, string> \| Promise<Record<string, string>>	否	-	每次请求 Editing API 前动态获取请求头，适合短期 Token 场景。
assistant	AmkEditorAssistantConfig	是	-	AI 助手相关配置，包括模型、对话服务、对话展示、工具扩展和回调。详见AI 助手配置（assistant）。
layout	AmkEditorAssistantLayoutOptions	否	-	AI 助手与剪辑器的双栏布局配置。详见双栏布局配置（layout）。
theme	'light' \| 'dark'	否	-	剪辑器主题。
header	object	否	-	剪辑器顶部标题栏配置。
export	object	否	-	剪辑器导出功能相关配置与回调。
storage	object	否	-	媒体产物存储与上传相关配置（如 TOS 直传、VOD 上传）。详见存储配置（storage）。
material	object	否	-	素材导入、刷新、转存等相关回调函数的集合。详见素材配置（material）。
getLicenseUrl	function	否	-	加密视频播放 License 地址或异步获取函数。
decode	object	否	-	前端音视频解码（如波形图生成）配置。
i18n	object	否	-	语言与文案覆盖，包含 locale（界面语言）。详见语言与文案配置（i18n）。
toolbar	object	否	-	内置剪辑器工具栏配置。详见工具栏配置（toolbar）。

语言与文案配置（i18n）

配置项	类型	是否必填	默认值	说明
i18n.locale	string	否	'zh-CN'	界面语言，内置 'zh-CN' 与 'en-US' 两种；不会自动跟随浏览器语言。

用于配置内置剪辑器工具栏。

配置项	类型	是否必填	默认值	说明
toolbar.asr.provider	'asr-subtitles' \| 'maas'	否	'asr-subtitles'	选择字幕识别服务，火山引擎支持这两个取值。该配置仅控制内置剪辑器的字幕识别，不影响 AI 助手的对话模型。
toolbar.builtInVisibility	object	否	-	控制内置按钮是否显示：false 表示隐藏，true 表示显示；不传字段时使用默认设置。隐藏按钮不影响快捷键或对应功能。
toolbar.builtInVisibility.undo	boolean	否	true	撤销按钮。
toolbar.builtInVisibility.redo	boolean	否	true	重做按钮。
toolbar.builtInVisibility.cut	boolean	否	true	剪切按钮。
toolbar.builtInVisibility.copy	boolean	否	true	复制按钮。
toolbar.builtInVisibility.delete	boolean	否	true	删除按钮。
toolbar.builtInVisibility.asrSubtitle	boolean	否	true	字幕识别入口，与 asr.provider 配合使用。

存储配置（storage）

storage 对象整体可选。一旦配置 media_output_destination，就必须同时配置 getUploadSTS。

配置项	类型	是否必填	默认值	说明
storage.media_output_destination	string	条件必填	-	媒体上传目标。TOS 使用 tos://<bucket>[/<prefix>]；VOD 使用 vod://<space>，只填写空间名，不带 Vid、子目录、查询参数或 URL 片段。TOS 模式下 SDK 不会自动追加 projectId，需您在前缀中明确加入剪辑工程目录。
storage.getUploadSTS	() => Credentials \| Promise	条件必填	-	返回与目标存储匹配的短期凭证。接口应直接返回凭证对象；如响应包含 data 包装层，需在回调中取出 data。TOS 返回 accessKeyId、accessKeySecret、stsToken、expiration；VOD 返回 AccessKeyId、SecretAccessKey、SessionToken、ExpiredTime、CurrentTime（均为非空字符串，注意大小写）。

AI 助手配置（assistant）

配置项	类型	是否必填	默认值	说明
assistant.model	string \| 模型列表 \| 分组列表	是	-	推理模型 Endpoint ID，负责自然语言指令理解与流程规划；也支持传入模型列表或分组列表（传入单个字符串时不展示模型选择器）。火山推荐模型见准备工作。
assistant.preferMultiModalModels	readonly string[]	否	-	多模态理解模型 Endpoint ID 数组，负责理解视频、音频、图片等媒体内容。音频理解（按需）：需要时配置对应 Endpoint ID，例如 doubao-seed-2-0-lite-260428。视觉理解（推荐二选一）：doubao-seed-2-1-turbo-260628、doubao-seed-2-1-pro-260628。
assistant.runtime	AssistantRuntimeConfig	否	-	AI 助手服务的请求地址与请求头配置。
assistant.runtime.headers	Record<string, string>	否	-	AI 助手请求使用的固定请求头。顶层 getHeaders 不会自动应用到 AI 助手请求。
assistant.runtime.getHeaders	() => Record<string, string> \| Promise<Record<string, string>>	否	-	每次请求 AI 助手服务前动态获取请求头，适合短期 Token 场景。
assistant.runtime.runtimeUrl	string	否	${endpoint}/api/v1/studio/agents	Assistant Runtime API 服务地址。仅当 Assistant Runtime API 与 Editing API 使用不同域名或服务路径时配置。
assistant.agentId	string	否	mediakit-editor-sdk-agent	AI 助手 ID。
assistant.composer.actions	数组或转换函数	否	-	在输入区底部追加业务自定义 React 控件，用于实现特殊交互。
assistant.onModelChange	(event) => void	否	-	模型选择变化回调。请保持模型列表引用稳定，避免选择被反复重置。
assistant.onIntegrationError	(error) => void	否	-	接收剪辑工程会话初始化、资源加载和通过代码控制 AI 助手时发生的错误。
assistant.mcp.tools	readonly string[]	否	-	按工具名称选择 AI 助手可以使用的 AI MediaKit 工具。可配置的 12 项工具：video_understand_router（媒体内容理解）、asr_subtitles（语音识别及字幕生成）、probe_audio_metadata（音频元信息）、probe_video_metadata（视频元信息）、probe_image_metadata（图像元信息）、erase_video_subtitle_pro（视频字幕擦除）、separate_voice（人声与背景音分离）、matte_greenscreen_video（视频绿幕抠图）、erase_image（图像擦除修复）、remove_image_background（图像背景移除）、extract_frames（视频抽帧）、call_maas_proxy（MaaS 生成及语音识别入口）。该配置还需在服务端的 MCP 服务和 AI 助手配置中启用相应工具，仅升级前端 SDK 不会生效。
assistant.mcp.editDenyTools	readonly string[]	否	-	禁用指定的剪辑 MCP 工具，使 AI 助手无法查看或调用这些工具。可配置项包括工程类（create_project、list_projects、update_project、read_project）、素材类（sync_materials、update_materials、list_materials、inspect_materials）、时间线类（preview_timeline、inspect_elements、edit_element、split_element、edit_track）、资源类（list_resources）、场景工具类（list_scenario_skills、read_scenario_skill）、导出类（export_project）及任务查询（query_task）。
assistant.maasModel	string \| readonly string[]	否	-	生成模型实际使用的 modelId，通常由 maasModel 模型分组的选择结果自动提供。未选择模型时，不应默认调用生成模型。

双栏布局配置（layout）

配置项	类型	是否必填	默认值	说明
layout.defaultHiddenPanel	'assistant' \| 'editor'	否	-	初始状态下隐藏 AI 助手或剪辑器面板；不传时两栏都显示。
layout.initialWidthPercent	number	否	37.5	AI 助手面板的初始宽度百分比。
layout.minAssistantWidth	number	否	320	AI 助手面板的最小像素宽度。
layout.minEditorWidth	number	否	640	剪辑器面板的最小像素宽度。
layout.resizable	boolean	否	true	是否允许用户拖拽分隔条调整宽度。
layout.onPanelVisibilityChange	(state: AmkEditorAssistantLayoutState) => void	否	-	用户手动打开或关闭任一面板后的回调。

素材配置（material）

您提供的原始音频、视频和图片 URL 必须允许跨域访问（CORS）。首次请求和失败重试均不能改用 no-cors 模式。

配置项	类型	是否必填	默认值	说明
material.uploadAccept	string	否	-	本地文件选择器的 accept 字符串。
material.uploadConcurrency	number（正整数）	否	-	单文件上传、SDK 内置上传和临时文件转存共享的并发数。不传时本地上传不限并发，临时文件转存默认最多同时处理 5 条。URL 导入仍整批调用 onUploadUrlMaterial；业务资产库导入的并发由业务自行控制。
material.onUploadFile(file)	(file: File) => MaterialItem \| Promise	否	-	上传单个本地文件并返回一条待添加到素材库的素材；配置后优先级高于 SDK 内置的 TOS 或 VOD 上传。
material.onUploadUrlMaterial(urls)	(urls: string[]) => MaterialItem[] \| Promise<MaterialItem[]>	否	-	URL 导入回调；配置后 SDK 将自动启用 AI 助手的 URL 批量导入工具。
material.onUploadFromSystem()	() => SystemMaterialItem[] \| Promise<SystemMaterialItem[]>	否	-	打开业务资产库并返回所选素材。
material.onRefreshPlayInfo(materials)	(materials: MaterialItem[]) => Partial[] \| Promise<Partial[]>	否	-	刷新业务自定义存储中的短期播放地址。使用 SDK 内置 TOS/VOD 存储时无需配置。
material.onPersistExtractUrls(params)	(params: { kind; urls; material }) => PersistExtractUrlsResult \| string[]	否	-	将 SDK 抽取的封面、雪碧图等临时文件转存到长期有效的地址。长效地址写入 poster 或 sprite 后，建议清除对应的 poster_task_id 或 sprite_task_id。

SDK 实例方法

方法	返回值	说明
whenReady()	Promise	等待剪辑工程加载和剪辑器渲染完成。
getEditor()	AmkEditor	获取剪辑器实例；应在 whenReady() 完成后调用。
getAssistantController()	AssistantController	获取用于通过代码控制 AI 助手的控制器；AI 助手完成渲染后可用。
setLayoutChromeVisibility(...)	void	动态显示或隐藏顶部标题栏与浮动分栏按钮。
addTimelineElementToConversation(...)	Promise	将时间线元素作为结构化实体追加到对话草稿。
addMaterialToConversation(...)	Promise	将工程素材作为结构化实体追加到对话草稿。
destroy()	void	移除所有实例、监听器和计时器，释放资源。

服务端 API 参考

您的业务代理服务通过同一个代理入口，将前端 SDK 的调用转发到 AI MediaKit 同一服务域名下的两组路径：Editing API 和 Assistant Runtime API。

Editing API

这套 API 负责管理剪辑工程的核心数据，如工程信息、素材库、时间轴和异步任务。

基础信息

项目	说明
服务域名	https://mediakit.cn-beijing.volces.com
基础路径	/api/v1/editing
认证方式	Authorization: Bearer <YOUR_AMK_API_KEY>

响应约定

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

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

创建工程

POST /projects

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

请求参数

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

批量创建或更新素材

POST /projects/{projectId}/materials（创建）

PUT /projects/{projectId}/materials（更新或插入）

向指定工程中批量添加或更新素材。PUT 操作会根据 source_material_id 判断是更新现有素材还是插入新素材。如果任一素材未通过校验，本批次中的所有新增和更新都不会生效。

请求参数

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

Assistant Runtime API

这套 API 负责处理所有与大模型交互的请求，包括自然语言理解、对话管理和 AI 助手工具调用。

基础信息

项目	说明
浏览器侧代理前缀	SDK 基于顶层 endpoint 自动生成，例如 /api/amk-proxy/api/v1/studio/agents。
AI 助手服务地址	https://mediakit.cn-beijing.volces.com/api/v1/studio/agents
服务端认证	由您的代理服务添加 Authorization: Bearer <YOUR_AMK_API_KEY> 请求头。
响应类型	普通查询接口返回 JSON；AI 助手执行接口可能返回 text/event-stream 流式响应。

必须允许访问的接口

您的代理服务应至少放行以下 SDK 必需的路径和方法：

方法	浏览器请求路径（示例）	用途
GET	/api/amk-proxy/api/v1/studio/agents/copilotkit	建立或检查 AI 助手服务连接。
POST	/api/amk-proxy/api/v1/studio/agents/copilotkit	提交对话请求并执行 AI 助手任务，可能返回 SSE 事件流。
GET	/api/amk-proxy/api/v1/studio/agents/threads/{threadId}/messages	读取会话历史消息。
GET	/api/amk-proxy/api/v1/studio/agents/agents/{agentId}/conversations	查询会话列表，用于恢复与工程绑定的会话。

SDK 发布历史

日期	版本号	说明
2026 年 10 月 20 日	1.0.3	新增内置 TOS / VOD 存储接入，支持将本地素材上传至指定存储桶或点播空间。
2026 年 9 月 15 日	0.0.1	首次发布。