本文档面向需要在 Web 应用中集成 AI 智能剪辑能力的前端及服务端开发者。通过 AI MediaKit Web 智能剪辑 SDK（`@volcengine/amk-editor-assistant`），您可以在业务页面中嵌入一套 AI 驱动的视频创作工具，实现从素材管理、智能编排、特效渲染到高清导出的全链路剪辑流程，而无需自行拼装复杂的底层组件和 AI 算法。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/cb556bc1f6e04a1cb3560cbd0d5a9ea7) ## SDK 概述 `@volcengine/amk-editor-assistant` 是一款面向浏览器环境的、一站式的智能视频剪辑SDK，将强大的 AI 助手与专业的剪辑器无缝整合，为用户提供自然语言驱动的全新视频创作体验。 |核心能力 |说明 | |---|---| |AI 助手 |用户可通过自然语言对话完成复杂编辑操作，如“理解视频内容，剪辑出高光片段，并添加字幕”、“把我提供的素材混剪成片，理解素材内容，生成一条结构完整的混剪 Vlog”，AI 助手会自动理解意图并调用相应工具执行。 | |Web 剪辑器 |内置功能完备的剪辑器，支持多轨道编辑、精确裁剪、实时预览、文本与字幕添加、特效、转场、滤镜等专业能力，满足精细化调整需求。 | |丰富的云端 AI 原子能力 |内置多种 AI MediaKit 原子能力，如 ASR 字幕识别、视频抽帧、视频理解、高光识别等，可被 AI 助手自动编排调用。 | |场景化智能剪辑工具 |提供多种开箱即用的场景化方案，如高光剪辑（通用/短剧）、AI 短漫剧粗剪、多素材智能混编和 Vlog 视频混剪，能自动完成从素材筛选、逻辑编排到效果包装的全流程，极大提升成片效率。 | ## 架构与核心概念集成 Web 智能剪辑 SDK 时，您的应用前端（浏览器）将与您的业务后端（代理服务）以及 AI MediaKit 服务端进行交互。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/085ceaefd1454dec8793a885e9f3e45c) ### 请求链路浏览器中同时存在剪辑器和 AI 助手两条逻辑请求链路。两条链路共用顶层 endpoint 指向同一个业务代理入口，由 SDK 分别追加对应的上游路径： |链路 |SDK 配置入口 |主要职责 | |---|---|---| |剪辑器（Editing API） |顶层 endpoint、getHeaders |加载与保存剪辑工程、管理素材、调用原子编辑工具（如转码、拼接）、查询任务状态和访问预设资源库。 | |AI 助手（Assistant Runtime） |顶层 endpoint（自动派生 Runtime 地址）、assistant.runtime.getHeaders |进行大模型推理、管理对话历史、调用 Agent 工具（包括云剪辑工具和前端工具）。 | ### 核心设计：业务代理为保障密钥（API Key）安全，浏览器不能直接请求 AI MediaKit 服务。所有请求都必须通过您自己实现的业务代理服务进行中转。该服务主要负责： 1. **安全地附加密钥**：将安全存储在您服务器上的 AI MediaKit API Key 添加到请求头中。 2. **校验业务权限**：验证当前登录用户是否有权访问其正在操作的 projectId，防止数据越权。 3. **转发请求**：将来自 SDK 的请求安全地转发给对应的 AI MediaKit 上游服务。 ## **费用说明** 使用 Web 智能剪辑 SDK 会涉及三部分费用，分别由 AI MediaKit 和火山方舟进行计费。费用遵循日结后付费模式，次日 6:00 生成前一日的账单并进行结算。 ### **火山方舟大模型调用费** AI 助手在进行自然语言对话（推理模型）和多模态内容理解（多模态理解模型）时，会调用您在 SDK 中配置的火山方舟大模型。此部分费用由火山方舟根据模型调用过程中实际消耗的 Token 数量（包括输入和输出 Token）进行计费。关于不同模型的 Token 计费标准，请查阅[火山方舟最新官方定价说明](https://www.volcengine.com/docs/82379/1544106)。 ### **AI MediaKit 原子能力费用** 在 AI 助手自动编排或用户手动编辑过程中，可能会调用 AI MediaKit 的多种原子能力。这些能力将按照各自的计费规则进行计费，主要包括以下两类： * **视频工具**：当 AI 助手需要理解视频内容或执行特定处理时，会触发视频工具的调用，包含字幕识别、视频抽帧、视频理解、高光识别等。这些能力将按照各自的计费规则进行计费，详细规则请参阅[视频工具计费](https://docs.volcengine.com/docs/6448/2486473)。 * **剪辑工具**：当您或您的用户最终执行“导出视频”操作时，会产生剪辑费用。该费用基于最终输出的视频时长和分辨率进行计费。详细规则请参阅[剪辑工具计费](https://docs.volcengine.com/docs/6448/2486459)。 ## 准备工作在开始编码前，请确保已完成以下准备： * **开通服务**：确保您的火山引擎账号已开通 [AI MediaKit 服务](https://console.volcengine.com/imp/ai-mediakit)。 * **获取 API Key**：在 AI MediaKit 控制台的 [API Key 管理页面](https://console.volcengine.com/imp/ai-mediakit/settings)创建并获取 API Key。此凭证将用于您的服务端代理。 * **获取模型 Endpoint ID**：前往[火山方舟控制台开通管理页面](https://console.volcengine.com/ark/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=model&projectName=default)，开通所需的大模型服务并获取其 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-0-lite-260428`，以支持音频相关的理解能力。 * 视觉理解（推荐）：建议从 `doubao-seed-2-1-turbo-260628` 或 `doubao-seed-2-1-pro-260628` 中选择一个配置，以支持视频画面、图片等视觉内容的理解。 * **进行跨服务授权**：前往 AI MediaKit 控制台[基础配置 > 授权管理](https://console.volcengine.com/imp/ai-mediakit/settings?tab=authorization&projectName=default)页面，为 AI MediaKit 授予访问您 **ARK 火山方舟**资源的权限。 ## 快速开始本节将引导您完成一个从零到一的端到端集成，快速运行一个最基本的智能剪辑应用。 ### 步骤 1：安装 SDK（前端）在您的前端项目根目录中执行以下命令： ```Bash # 使用 npm npm install @volcengine/amk-editor-assistant react react-dom # 或使用 pnpm pnpm add @volcengine/amk-editor-assistant react react-dom ``` ### 步骤 2：创建剪辑工程（服务端）在您的服务端，为用户的每次创作会话调用 AI MediaKit API 创建一个云端剪辑工程，并将其唯一标识 project_id 传递给前端。 **请求示例：** ```Bash # 请在您的服务端发起此请求 curl -X POST https://mediakit.cn-beijing.volces.com/api/v1/editing/projects \ -H "Authorization: Bearer $AMK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "my-smart-project" }' ```

说明

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

**响应示例：** ```JSON { "data": { "project_id": "proj_smart_abc123", // <-- 这是您需要保存并传给前端的 ID "name": "my-smart-project", "created_at": "2024-01-01T00:00:00Z" } } ``` ### 步骤 3：搭建业务代理（服务端）剪辑器和 AI 助手共用一个业务代理入口（例如 /api/amk\-proxy）。SDK 会在该入口后分别追加 Editing API 和 Assistant Runtime 的完整上游路径。以下 Node.js + Express 示例已同时包含 Editor 与 Assistant 的路径白名单及转发逻辑；在实际项目中，您还需补充用户身份验证、工程权限校验、接口限流和操作审计。 ```JavaScript // 适用于 Node.js 18+ import express from 'express'; import { Readable } from 'node:stream'; import { pipeline } from 'node:stream/promises'; const app = express(); app.use(express.json({ limit: '10mb' })); // --- 需要您配置的部分 --- const PROXY_PREFIX = '/api/amk-proxy'; const UPSTREAM_BASE_URL = 'https://mediakit.cn-beijing.volces.com'; const API_KEY = process.env.AMK_API_KEY; // 从环境变量读取您的 API Key if (!API_KEY) { throw new Error('AMK_API_KEY is not set in environment variables.'); } // 剪辑器 API 路径白名单 const ALLOWED_EDITOR_PATHS = [ /^\/api\/v1\/editing\//, /^\/api\/v1\/tools\//, /^\/api\/v1\/tools-sync\//, /^\/api\/v1\/tasks\/[^/]+\/?$/, ]; // AI 助手 Runtime 的 API 路径白名单 const ALLOWED_ASSISTANT_PATHS = [ ['GET', /^\/api\/v1\/studio\/agents\/copilotkit\/?$/], ['POST', /^\/api\/v1\/studio\/agents\/copilotkit\/?$/], ['GET', /^\/api\/v1\/studio\/agents\/threads(?:\/|$)/], ['GET', /^\/api\/v1\/studio\/agents\/agents(?:\/|$)/], ]; // --- 配置结束 --- app.use(PROXY_PREFIX, async (req, res) => { // SDK 已在请求中包含完整的 /api/v1/... 上游路径； // 代理只移除本地前缀，不要再次拼接 /api/v1/editing。 const upstreamPath = req.originalUrl.slice(PROXY_PREFIX.length); const pathname = upstreamPath.split('?')[0]; const assistantRequest = pathname.startsWith('/api/v1/studio/agents/'); if (assistantRequest) { // 1. 【安全】AI 助手路径白名单校验 const allowed = ALLOWED_ASSISTANT_PATHS.some( ([method, pattern]) => req.method === method && pattern.test(pathname) ); if (!allowed) { return res.status(403).json({ error: 'Assistant Runtime path is not allowed' }); } } else { // 1. 【安全】剪辑器路径白名单校验 const allowed = ALLOWED_EDITOR_PATHS.some(pattern => pattern.test(pathname)); if (!allowed) { return res.status(403).json({ error: 'Editing API path is not allowed' }); } } // 2. 【安全-需要您自行实现】业务权限校验 // 在这里校验当前登录用户是否有权访问其请求的 projectId，防止数据越权。 const controller = new AbortController(); const timeoutMs = assistantRequest ? 30 * 60_000 : 60_000; const timeoutId = setTimeout(() => controller.abort(), timeoutMs); const onClose = () => { if (!res.writableFinished) controller.abort(); }; res.on('close', onClose); try { const headers = { 'Authorization': `Bearer ${API_KEY}`, 'Accept': assistantRequest ? req.headers.accept ?? 'application/json' : 'application/json', }; if (!['GET', 'HEAD'].includes(req.method)) { headers['Content-Type'] = 'application/json'; } if (assistantRequest && typeof req.headers['x-endpoint-id'] === 'string') { headers['X-Endpoint-Id'] = req.headers['x-endpoint-id']; } const upstreamResponse = await fetch(`${UPSTREAM_BASE_URL}${upstreamPath}`, { method: req.method, headers, body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body ?? {}), signal: controller.signal, redirect: 'manual', }); // 3. 原样透传响应头和状态码 res.status(upstreamResponse.status); res.setHeader( 'Content-Type', upstreamResponse.headers.get('content-type') ?? 'application/json' ); res.setHeader('Cache-Control', 'no-cache'); res.setHeader('X-Accel-Buffering', 'no'); // Nginx 禁用缓冲 // 4. 流式透传响应体（关键） if (upstreamResponse.body) { await pipeline(Readable.fromWeb(upstreamResponse.body), res); } else { res.end(); } } catch (error) { if (res.destroyed) return; if (!res.headersSent) { res.status(502).json({ error: 'AI MediaKit request failed' }); } else { res.destroy(); // 如果流已开始，只能异常关闭 } } finally { clearTimeout(timeoutId); res.off('close', onClose); } }); ``` ### 步骤 4：初始化 SDK（前端）在您的前端页面中，引入 SDK 及其样式，准备一个 DOM 容器，然后调用 createAmkEditorAssistant 方法创建并挂载实例。 **准备挂载容器：** ```HTML

``` ```CSS /* 确保容器有明确的尺寸 */ #amk-container { width: 100%; height: 100vh; } ``` **创建实例：** ```TypeScript import { createAmkEditorAssistant, type AmkEditorUploadSTSCredentials, type MaterialItem, } from '@volcengine/amk-editor-assistant'; import '@volcengine/amk-editor-assistant/styles.css'; // 示例：从业务后端获取用于访问代理的短期凭证。 async function getShortLivedToken(): Promise { return 'your_business_auth_token'; } const getAmkHeaders = async (): Promise> => ({ Authorization: `Bearer ${await getShortLivedToken()}`, }); // 从业务服务端获取最小权限、短有效期的 TOS 临时凭证。 // 浏览器端不得保存或使用客户的长期 AK/SK。 async function getUploadSTS(): Promise { const response = await fetch('/api/amk-upload-sts', { method: 'POST', headers: await getAmkHeaders(), }); if (!response.ok) { throw new Error(`Get upload STS failed: HTTP ${response.status}`); } return (await response.json()) as AmkEditorUploadSTSCredentials; } // 自定义存储上传的备选实现。仅在不使用 storage.getUploadSTS 时配置。 async function uploadFileToBusinessStorage( file: File, ): Promise { const item = await uploadFileToYourStorage(file); return { source_material_id: item.id, // 业务素材唯一 ID，必填 name: item.name, type: item.type, // 'video'、'audio' 或 'image' url: item.playUrl, // 浏览器可访问的 HTTP(S) 地址 source: item.source, // 服务端合成使用的 HTTP(S) 原始资源地址 duration: item.duration, // 视频、音频需要 width: item.width, // 视频、图片需要 height: item.height, // 视频、图片需要 }; } const container = document.getElementById('amk-container'); if (!container) { throw new Error('Container element not found'); } const sdk = createAmkEditorAssistant({ // 必填配置 container, projectId: 'proj_smart_abc123', // 步骤 2 创建的工程 ID endpoint: '/api/amk-proxy', // Editor 与 Assistant 共用的业务代理入口 getHeaders: getAmkHeaders, // 动态获取剪辑器请求头 // AI 助手配置 assistant: { // 推理模型 Endpoint ID，用于处理自然语言指令。 // 推荐：doubao-seed-2.1-pro、doubao-seed-2.1-turbo、doubao-seed-2.0-pro model: 'ep-inference-model', // 多模态理解模型 Endpoint ID。 // 音频理解：doubao-seed-2-0-lite-260428 // 视觉理解：doubao-seed-2-1-turbo-260628 或 doubao-seed-2-1-pro-260628 preferMultiModalModels: ['ep-understanding-model'], runtime: { // Runtime 地址由 SDK 根据顶层 endpoint 自动生成。 getHeaders: getAmkHeaders, }, onIntegrationError: error => { console.error('AMK Editor Assistant integration failed', error); }, }, // 本地上传方案一：使用 SDK 内置 TOS 上传。 // media_output_destination 同时作为媒体处理产物的存储目标； // 格式为 tos:///<可选目录>。 storage: { media_output_destination: 'tos://your-bucket/amk-output', getUploadSTS, }, // 素材导入与播放地址维护 material: { uploadAccept: 'video/*,audio/*,image/*', // 本地上传方案二：由业务自行上传文件并返回标准素材。 // 如需使用该方案，请移除上面的 storage.getUploadSTS，再启用下一行。 onUploadFile: uploadFileToBusinessStorage, // 多选文件时，SDK 会并发逐个调用 onUploadFile 并分别入库。 // 可选：批量导入 URL。可以直接引用，也可以先转存到业务存储。 onUploadUrlMaterial: async ( urls: string[], ): Promise => { return importUrlsToYourStorage(urls); }, // 刷新短期播放地址、封面和雪碧图地址。 // 对于 tos:// 资源，SDK 会先使用 getUploadSTS 自动重新签名； // 该回调可继续处理业务自定义存储或 VOD 素材。 onRefreshPlayInfo: async ( materials: MaterialItem[], ): Promise[]> => { const result = await refreshMaterialPlayInfo( materials.map(item => ({ materialId: item.material_id, sourceMaterialId: item.source_material_id, posterStorageKey: item.poster_storage_key, spriteStorageKeys: item.sprite_storage_keys, })), ); return result.map(item => ({ // material_id 仅用于匹配原素材，不会改写 SDK 内部 ID； // 未返回 material_id 时，可通过 source_material_id 匹配。 material_id: item.materialId, source_material_id: item.sourceMaterialId, url: item.playUrl, poster: item.poster, sprite: item.sprite, })); }, // 将 SDK 抽帧产生的临时 URL 转存为业务长效地址。 // 使用 TOS 作为 media_output_destination 时，SDK 会保存真实 tos:// key // 并通过 getUploadSTS 自动续签，通常不需要再配置该回调。 onPersistExtractUrls: async ({ kind, urls, material }) => { const result = await persistExtractResults({ kind, urls, sourceMaterialId: material.source_material_id, }); return { // 返回数组必须与入参 urls 等长、顺序一致。 urls: result.urls, materialPatch: kind === 'poster' ? { poster_storage_key: result.storageKeys[0] } : { sprite_storage_keys: result.storageKeys }, }; }, }, decode: { enableAudioFrontendDecode: true, // 音频波形前端解码 enableVideoFrontendDecode: true, // 视频缩略图前端解码 }, }); // 等待实例挂载完成。 await sdk.whenReady(); console.log('SDK is ready!'); // 组件卸载或页面关闭时，务必释放资源。 // 例如在 React useEffect 的清理函数中： // return () => sdk.destroy(); ``` ### 步骤 5：验证集成效果完成以上步骤后，启动您的 Web 应用并打开包含编辑器的页面，进行以下验证： * **界面渲染**：左侧 AI 助手面板与右侧剪辑器界面能否正常加载，并且能看到工程的标题、素材与时间轴。 * **鉴权**：检查浏览器网络请求，确认所有对 /api/amk\-proxy 的请求都携带了业务 Token，并且浏览器代码中没有硬编码的长期 API Key。 * **对话与联动**：向 AI 助手发送一条指令（如“帮我剪一个 15 秒的视频”）。检查 AI 是否能响应，并在运行期间编辑器是否变为只读状态。 * **素材导入**：尝试上传一个媒体文件，检查 onUploadFile 是否被调用，以及上传成功后素材是否出现在素材库并被自动加入对话。 * **恢复**：刷新页面，检查同一 projectId 是否能恢复剪辑工程及其绑定的 AI 对话历史。 * **销毁**：离开页面时，检查 sdk.destroy() 是否被调用，确保没有内存或事件监听器泄漏。如果以上步骤均验证通过，恭喜您已成功完成 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`。其中的“目录”只是 Key 的前缀，并非真实的文件夹结构。 | |tos:// 地址 |表示资源身份的稳定 URI，例如 `tos://example-bucket/amk-editor/demo.mp4`。用于在工程、素材库和任务结果中持久化存储，但浏览器不能直接播放。 | |签名 URL |由临时 STS 凭证对私有对象生成的、具有时效性的 HTTP(S) GET 地址。播放器实际使用的是此 URL。任何持有者都可在有效期内访问，因此切勿在数据库中记录或长期缓存。 |

说明

最佳实践：为了数据安全，建议将 Bucket 访问权限设为“私有”。在您的数据库和剪辑工程中，始终使用稳定的 tos://bucket/key 格式来记录和持久化素材。仅在前端页面需要播放或展示时，才通过 STS 服务动态生成临时的签名 URL。

### 工作流程以下为浏览器、您的业务服务端与火山引擎云服务（TOS, STS, IAM）之间的完整交互流程： 1. 用户在浏览器中选择本地文件准备上传，或打开一个包含 `tos://` 素材的已有工程。 2. 前端 SDK 调用您在初始化时提供的 `getUploadSTS` 回调函数，向您的业务服务端请求临时上传凭证。 3. 您的业务服务端在验证用户身份和权限后，使用其安全存储的长期 AK/SK 调用火山引擎 STS 服务的 `AssumeRole` 接口。 4. STS 服务返回一组有时效性的临时凭证（AccessKeyId, SecretAccessKey, SessionToken），业务服务端将其透传给前端。 5. SDK 使用这组临时凭证初始化一个 TOS Browser.js SDK 实例，执行文件上传（`PutObject`）或为已有文件生成预签名 URL（`getPreSignedUrl`）。 6. 上传成功后，SDK 将 `tos://bucket/key` 作为素材的 `source_material_id` 进行持久化，并将新签发的播放地址填入 `url` 字段供 SDK 使用。 ### 操作步骤 #### 步骤 1：创建并配置 TOS Bucket 1. 创建存储桶：前往[火山引擎对象存储 TOS 控制台](https://console.volcengine.com/tos/)创建一个存储桶（例如 `example-bucket`）： * **地域（Region）** ：必须选择**华北2（北京）** 。 * **访问权限**：建议选择**私有**。

说明

建议为每个剪辑工程规划独立的对象前缀，例如 amk-editor//，以便后续进行精细化的权限控制和成本分摊。

2. 配置跨域访问（CORS）：在 Bucket 的**权限管理** \> **跨域访问设置** 中，添加一条规则： * **来源 Origin**：填写您的业务页面域名。 * **操作 Methods**：至少包含 PUT、GET、HEAD。 * **Allow\-Headers**：为方便调试，可先设置为 `*`。在生产环境中，应根据浏览器实际发出的请求头（如 `Content-Type`, `x-tos-content-md5` 等）进行收窄。 * **Expose\-Headers**：建议包含 `ETag` 和 `x-tos-request-id`，便于排查问题。

注意

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

#### 步骤 2：配置 IAM 角色与权限策略遵循最小权限原则，推荐使用一个专用的 IAM 子账号来调用 STS 服务，并创建一个仅允许访问特定 TOS 资源的角色。切勿在业务服务端硬编码主账号的长期密钥，更不能将任何长期密钥下发给浏览器。 1. 创建 STS 调用者（IAM 子账号）： * 前往[火山引擎访问控制（IAM）控制台 > 用户页面](https://console.volcengine.com/iam/identitymanage/user)创建一个用户。 * 为其创建并保存好访问密钥（AK/SK），此密钥将部署在您的业务服务端。 * 为该子用户授予 `STSAssumeRoleAccess` 权限，或创建一个仅允许对特定角色执行 `sts:AssumeRole` 操作的更严格的自定义策略。 2. 创建用于上传的 IAM 角色：在 IAM 控制台的[角色管理页面](https://console.volcengine.com/iam/identitymanage/role)中创建一个角色。信任身份选择当前账号，策略选择 STSAssumeRoleAccess。 3. 为角色绑定 TOS 权限策略：角色的权限策略决定了临时凭证的最终权限。请创建一个自定义策略，仅授予必要的 TOS 操作权限，然后将其绑定到角色上。切勿直接授予 `TOSFullAccess`。以下是一个最小权限策略示例，仅允许对 `example-bucket` 下`amk-editor/` 前缀内的对象执行上传和读取操作。请务必将桶名和前缀替换为您自己的配置。 ```JSON { "Statement": [ { "Effect": "Allow", "Action": [ "tos:PutObject", "tos:GetObject" ], "Resource": [ "trn:tos:::example-bucket/amk-editor/*" ] } ] } ``` 4. 记录角色 TRN：在角色详情页面，复制并保存其 TRN（火山引擎资源名称），格式为 `trn:iam:::role/`。此 TRN 将用于服务端的 `AssumeRole` 调用。 #### 步骤 3：实现 STS 临时凭证签发接口在您的业务服务端，创建一个 API 端点，例如 `/api/tos-upload-sts`，用于接收前端的凭证请求并返回 STS 临时凭证。

注意

以下 Node.js 示例仅为核心逻辑演示。生产环境的接口必须包含完整的用户登录态校验、剪辑工程 projectId 的访问权限检查、接口限流和日志审计。

```JavaScript // 服务端代码 (Node.js 示例) import { sts } from '@volcengine/openapi'; async function createTosUploadCredentials(roleSessionName) { // 1. 初始化 STS 服务，AK/SK 从服务端安全读取 const service = new sts.StsService({ region: 'cn-beijing' }); service.setAccessKeyId(process.env.VOLC_ACCESS_KEY); service.setSecretKey(process.env.VOLC_SECRET_KEY); // 2. 调用 AssumeRole const response = await service.AssumeRole({ RoleTrn: process.env.VOLC_STS_ROLE_TRN, // 步骤 2.4 中保存的角色 TRN RoleSessionName: roleSessionName, // 建议使用与业务相关的唯一标识 DurationSeconds: 3600, // 凭证有效期，单位秒，范围 900~43200 }); // 3. 构造对前端友好的响应格式 const c = response.Result.Credentials; return { accessKeyId: c.AccessKeyId, secretAccessKey: c.SecretAccessKey, // 注意：此处字段名为 secretAccessKey stsToken: c.SessionToken, expiration: c.ExpiredTime, }; } ```

说明

为了能被 SDK 内置的 TOS 上传模块正确识别，您的接口响应体必须包含 accessKeyId, secretAccessKey, stsToken 和 expiration 四个字段。

#### 步骤 4：在前端初始化 SDK 在前端初始化 `createAmkEditorAssistant` 时，传入 `storage` 配置项，即可启用 SDK 内置的 TOS 上传功能。 ```TypeScript import { createAmkEditorAssistant } from '@volcengine/amk-editor-assistant'; import '@volcengine/amk-editor-assistant/styles.css'; const projectId = 'proj_smart_abc123'; // 当前剪辑工程 ID async function getUploadSTS() { const response = await fetch('/api/tos-upload-sts', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ projectId }), // 携带业务参数供服务端校验 }); if (!response.ok) { throw new Error(`获取 TOS 临时凭证失败: ${response.status}`); } return response.json(); } const sdk = createAmkEditorAssistant({ // ... 其他必填配置，如 container, projectId, endpoint, getHeaders, assistant // 启用内置 TOS 上传 storage: { // 配置 TOS 产物存储目标，同时也是上传的目标。 // SDK 自身不会自动追加 projectId，为保证目录隔离，业务层应显式拼接。 media_output_destination: `tos://example-bucket/amk-editor/${projectId}`, // 提供获取临时凭证的回调函数 getUploadSTS, }, }); ```

说明

配置 storage 后，从本地上传文件将默认使用 SDK 内置的 TOS 上传流程，您无需再实现 material.onUploadFile 回调。

当您完成上述配置后，SDK 内部将按以下机制自动处理 TOS 资源的上传与访问： * 上传与持久化：用户上传文件成功后，SDK 会将稳定的 `tos:///` 地址保存到素材的 `source` 和 `source_material_id` 字段中，并同步到剪辑工程。 * 访问与刷新：当加载工程、或素材的临时播放地址即将过期时，SDK 会自动调用 `getUploadSTS` 获取新的临时凭证，并为 `tos://` 格式的源文件、封面和雪碧图重新生成带签名的短期播放 URL。 * 任务产物：当 AI MediaKit 的原子能力（如抽帧、转码）或最终的导出任务返回 `tos://` 格式的产物地址时，SDK 同样会自动将其转换为可供预览和下载的短期 HTTP(S) URL。 ## 参考本章节提供集成 Web 智能剪辑 SDK 时所需的详细参考信息，包括服务端 API、SDK 初始化配置、实例方法和核心数据结构。 ### SDK 初始化配置 createAmkEditorAssistant(options) 的完整配置项。 #### 顶层配置 |配置项 |类型 / 默认值 |必填 |说明 | |---|---|---|---| |container |HTMLElement |是 |已存在且有明确宽高的挂载节点。 | |projectId |string |是 |当前剪辑工程 ID，同时用于绑定 AI 助手会话和工程上下文。 | |endpoint |string |是 |Editor 与 Assistant 共用的业务代理基础地址；SDK 会在其后自动追加相应的上游路径。 | |getHeaders |() =\> object \| Promise |否 |每次请求剪辑器 API 前动态获取请求头，适合短期 Token 场景。 | |assistant |AmkEditorAssistantConfig |是 |AI 助手相关配置，包括模型、Runtime、对话展示、工具扩展和回调。详见 AI 助手配置 AmkEditorAssistantConfig。 | |layout |AmkEditorAssistantLayoutOptions |否 |智能剪辑器特有的 Assistant / Editor 双栏布局配置。详见双栏布局配置 AmkEditorAssistantLayoutOptions。 | |theme |'light' \| 'dark' |否 |剪辑器主题。 | |header |object |否 |剪辑器顶部标题栏配置。 | |export |object |否 |剪辑器导出功能相关配置与回调。 | |storage |object |否 |媒体产物存储与上传相关配置（如 TOS 直传）。 | |material |object |否 |素材导入、刷新、转存等相关回调函数的集合。 | |getLicenseUrl |function |否 |加密视频播放 License 地址或异步获取函数。 | |decode |object |否 |前端音视频解码（如波形图生成）配置。 | #### 存储配置 storage 该配置项用于启用 SDK 内置的存储方案，例如直传到您的火山引擎对象存储（TOS）。storage 对象整体可选；但一旦配置，其内部的 `media_output_destination` 和 `getUploadSTS` 必须同时提供。 |配置项 |类型 |必填 |说明 | |---|---|---|---| |media_output_destination |string |是 |媒体上传和处理产物的目标位置。TOS 格式为 tos://[/]；VOD 格式为 vod://。 | |getUploadSTS |() =\> Promise |是 |一个异步回调函数，用于从您的业务服务端获取短期的存储访问凭证，供 SDK 上传和刷新播放地址。 | #### AI 助手配置 AmkEditorAssistantConfig |配置项 |必填 |说明 | |---|---|---| |model |是 |推理模型 Endpoint ID。负责处理用户在对话中输入的自然语言指令。推荐模型：doubao\-seed\-2.1\-pro、doubao\-seed\-2.1\-turbo、doubao\-seed\-2.0\-pro。 | |preferMultiModalModels |否 |多模态理解模型 Endpoint ID 数组。负责理解视频、音频、图片等媒体内容。

* 音频理解（必需）：doubao\-seed\-2\-0\-lite\-260428

* 视觉理解（推荐二选一）：doubao\-seed\-2\-1\-turbo\-260628、doubao\-seed\-2\-1\-pro\-260628 | |runtime |否 |配置 AI 助手 Runtime 的静态 headers 或动态 getHeaders；Runtime 地址由 SDK 根据顶层 endpoint 自动生成，无需单独配置 runtimeUrl。 | |agentId |否 |Assistant Agent ID；默认 mediakit\-editor\-sdk\-agent。 | |composer.actions |否 |在输入区底部追加业务自定义 React 控件，用于实现特殊交互。 | |onModelChange |否 |模型切换时的回调函数。 | |onIntegrationError |否 |接收工程会话初始化、资源加载和命令式联动错误。 | #### 双栏布局配置 AmkEditorAssistantLayoutOptions |配置项 |默认值 |说明 | |---|---|---| |defaultHiddenPanel |无 |首屏隐藏 assistant 或 editor 面板；不传时两栏都显示。 | |initialWidthPercent |37.5 |AI 助手面板的初始宽度百分比。 | |minAssistantWidth |320 |AI 助手面板的最小像素宽度。 | |minEditorWidth |640 |剪辑器面板的最小像素宽度。 | |resizable |true |是否允许用户拖拽分隔条调整宽度。 | |onPanelVisibilityChange |无 |用户手动打开或关闭任一面板后的回调。 | #### 素材配置 (material) |配置项 |触发时机与要求 | |---|---| |uploadAccept |本地文件选择器的 accept 字符串。 | |onUploadFile(file) |上传单个本地文件并返回一条待入库素材。SDK 会并发处理多文件上传，单项失败不影响其他。 | |onUploadUrlMaterial(urls) |URL 导入回调。配置后 SDK 将自动启用 AI 助手的 URL 批量导入工具。 | |onUploadFromSystem() |打开业务资产库并返回所选素材。 | |onRefreshPlayInfo(materials) |刷新素材的短期播放地址。 | |onPersistExtractUrls(...) |将 SDK 抽取的封面、雪碧图等临时产物转存为长效地址。 | ### SDK 实例方法 |方法 |返回值 |说明 | |---|---|---| |whenReady() |Promise |等待工程加载和编辑器挂载完成。 | |getEditor() |AmkEditor |获取底层编辑器实例；应在 whenReady() 后调用。 | |getAssistantController() |AssistantController |获取 AI 助手的命令式控制器；在 Assistant 渲染后可用。 | |setLayoutChromeVisibility(...) |void |运行时动态显示或隐藏 Header 与浮动分栏按钮。 | |addTimelineElementToConversation(...) |Promise |将时间线元素作为结构化实体追加到对话草稿。 | |addMaterialToConversation(...) |Promise |将工程素材作为结构化实体追加到对话草稿。 | |destroy() |void |销毁所有实例、监听器和计时器，释放资源。 | ### 服务端 API 参考您的业务代理服务（BFF）通过同一个代理入口，将前端 SDK 的调用转发到 AI MediaKit 同一 Host 下的两组路径：剪辑器 API 和 AI 助手 API。 #### 剪辑器 API (Editing API) 这套 API 负责管理剪辑项目的核心数据，如工程、素材库、时间轴和异步任务。 **基础信息** |项目 |说明 | |---|---| |Host |https://mediakit.cn\-beijing.volces.com | |Base Path |/api/v1/editing | |鉴权方式 |Authorization: Bearer | **响应约定** 所有接口在 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[] |是 |素材对象数组，每个对象需符合[素材标准格式](https://docs.volcengine.com/docs/6448/2666473?lang=zh#cb602b66)。单次请求最多支持 100 条。 | #### AI 助手 API (Assistant Runtime API) 这套 API 负责处理所有与大模型交互的逻辑，包括自然语言理解、对话管理和 Agent 工具调用。 **基础信息** |项目 |说明 | |---|---| |浏览器侧代理前缀 |例如 /api/amk\-proxy/api/v1/studio/agents，由 SDK 基于顶层 endpoint 自动生成，无需单独配置 runtimeUrl。 | |Runtime 上游地址 |https://mediakit.cn\-beijing.volces.com/api/v1/studio/agents | |上游鉴权 |由您的代理服务注入 Authorization: Bearer 。 | |响应类型 |普通查询接口返回 JSON；Agent 执行接口可能返回 text/event\-stream 流式响应。 | **接口白名单** 您的代理服务应至少放行以下 SDK 必需的路径和方法： |方法 |浏览器请求路径（示例） |用途 | |---|---|---| |GET |/api/amk\-proxy/api/v1/studio/agents/copilotkit |建立或检查 Runtime 连接。 | |POST |/api/amk\-proxy/api/v1/studio/agents/copilotkit |提交对话请求并执行 Agent，可能返回 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 年 9 月 15 日 |0.0.1 |首次发布。 |