You need to enable JavaScript to run this app.
文档中心
AI MediaKit

AI MediaKit

请输入
  • 文档首页
    • AI MediaKit开发指南剪辑工具智能剪辑Web 智能剪辑 SDK 集成指南
复制全文
下载 pdf
我的收藏
智能剪辑
Web 智能剪辑 SDK 集成指南
复制全文
下载 pdf
我的收藏
Web 智能剪辑 SDK 集成指南
本文档面向需要在 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 分别追加对应的上游路径： ​
​
链路 ​
SDK 配置入口 ​
主要职责 ​
剪辑器（Editing API） ​
顶层 endpoint、getHeaders ​
加载与保存剪辑工程、管理素材、调用原子编辑工具（如转码、拼接）、查询任务状态和访问预设资源库。 ​
AI 助手（Assistant Runtime） ​
顶层 endpoint（自动派生 Runtime 地址）、assistant.runtime.getHeaders ​
进行大模型推理、管理对话历史、调用 Agent 工具（包括云剪辑工具和前端工具）。 ​
​
核心设计：业务代理​
为保障密钥（API Key）安全，浏览器不能直接请求 AI MediaKit 服务。所有请求都必须通过您自己实现的业务代理服务进行中转。该服务主要负责： ​
  1. 安全地附加密钥：将安全存储在您服务器上的 AI MediaKit API Key 添加到请求头中。 ​
  1. 校验业务权限：验证当前登录用户是否有权访问其正在操作的 projectId，防止数据越权。 ​
  1. 转发请求：将来自 SDK 的请求安全地转发给对应的 AI MediaKit 上游服务。 ​
费用说明​
使用 Web 智能剪辑 SDK 会涉及三部分费用，分别由 AI MediaKit 和火山方舟进行计费。费用遵循日结后付费模式，次日 6:00 生成前一日的账单并进行结算。​
火山方舟大模型调用费​
AI 助手在进行自然语言对话（推理模型）和多模态内容理解（多模态理解模型）时，会调用您在 SDK 中配置的火山方舟大模型。此部分费用由火山方舟根据模型调用过程中实际消耗的 Token 数量（包括输入和输出 Token）进行计费。 关于不同模型的 Token 计费标准，请查阅火山方舟最新官方定价说明。​
AI MediaKit 原子能力费用​
在 AI 助手自动编排或用户手动编辑过程中，可能会调用 AI MediaKit 的多种原子能力。这些能力将按照各自的计费规则进行计费，主要包括以下两类：​
  • 视频工具：当 AI 助手需要理解视频内容或执行特定处理时，会触发视频工具的调用，包含字幕识别、视频抽帧、视频理解、高光识别等。这些能力将按照各自的计费规则进行计费，详细规则请参阅视频工具计费。​
  • 剪辑工具：当您或您的用户最终执行“导出视频”操作时，会产生剪辑费用。该费用基于最终输出的视频时长和分辨率进行计费。详细规则请参阅剪辑工具计费。​
准备工作​
在开始编码前，请确保已完成以下准备： ​
  • 获取 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-0-lite-260428，以支持音频相关的理解能力。​
  • 视觉理解（推荐）：建议从 doubao-seed-2-1-turbo-260628 或 doubao-seed-2-1-pro-260628 中选择一个配置，以支持视频画面、图片等视觉内容的理解。​
  • 进行跨服务授权：前往 AI MediaKit 控制台基础配置 > 授权管理页面，为 AI MediaKit 授予访问您 ARK 火山方舟资源的权限。​
快速开始 ​
本节将引导您完成一个从零到一的端到端集成，快速运行一个最基本的智能剪辑应用。 ​
步骤 1：安装 SDK（前端） ​
在您的前端项目根目录中执行以下命令： ​
​
# 使用 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 传递给前端。 ​
请求示例：​
​
# 请在您的服务端发起此请求​
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。 ​
响应示例：​
​
{​
"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 的路径白名单及转发逻辑；在实际项目中，您还需补充用户身份验证、工程权限校验、接口限流和操作审计。​
​
// 适用于 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 方法创建并挂载实例。 ​
准备挂载容器：​
​
<div id="amk-container"></div>​
​
​
/* 确保容器有明确的尺寸 */​
#amk-container {​
width: 100%;​
height: 100vh;​
}​
​
创建实例：​
​
import {​
createAmkEditorAssistant,​
type AmkEditorUploadSTSCredentials,​
type MaterialItem,​
} from '@volcengine/amk-editor-assistant';​
import '@volcengine/amk-editor-assistant/styles.css';​
​
// 示例：从业务后端获取用于访问代理的短期凭证。​
async function getShortLivedToken(): Promise<string> {​
return 'your_business_auth_token';​
}​
​
const getAmkHeaders = async (): Promise<Record<string, string>> => ({​
Authorization: `Bearer ${await getShortLivedToken()}`,​
});​
​
// 从业务服务端获取最小权限、短有效期的 TOS 临时凭证。​
// 浏览器端不得保存或使用客户的长期 AK/SK。​
async function getUploadSTS(): Promise<AmkEditorUploadSTSCredentials> {​
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<MaterialItem> {​
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://<bucket>/<可选目录>。​
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<MaterialItem[]> => {​
return importUrlsToYourStorage(urls);​
},​
​
// 刷新短期播放地址、封面和雪碧图地址。​
// 对于 tos:// 资源，SDK 会先使用 getUploadSTS 自动重新签名；​
// 该回调可继续处理业务自定义存储或 VOD 素材。​
onRefreshPlayInfo: async (​
materials: MaterialItem[],​
): Promise<Partial<MaterialItem>[]> => {​
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:// 素材的已有工程。​
  1. 前端 SDK 调用您在初始化时提供的 getUploadSTS 回调函数，向您的业务服务端请求临时上传凭证。​
  1. 您的业务服务端在验证用户身份和权限后，使用其安全存储的长期 AK/SK 调用火山引擎 STS 服务的 AssumeRole 接口。​
  1. STS 服务返回一组有时效性的临时凭证（AccessKeyId, SecretAccessKey, SessionToken），业务服务端将其透传给前端。​
  1. SDK 使用这组临时凭证初始化一个 TOS Browser.js SDK 实例，执行文件上传（PutObject）或为已有文件生成预签名 URL（getPreSignedUrl）。​
  1. 上传成功后，SDK 将 tos://bucket/key 作为素材的 source_material_id 进行持久化，并将新签发的播放地址填入 url 字段供 SDK 使用。​
操作步骤​
步骤 1：创建并配置 TOS Bucket​
  1. 创建存储桶：前往火山引擎对象存储 TOS 控制台创建一个存储桶（例如 example-bucket）：​
  • 地域（Region）：必须选择华北2（北京）。​
  • 访问权限：建议选择私有。​
说明​
建议为每个剪辑工程规划独立的对象前缀，例如 amk-editor/<projectId>/，以便后续进行精细化的权限控制和成本分摊。​
  1. 配置跨域访问（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 子账号）：​
  • 为其创建并保存好访问密钥（AK/SK），此密钥将部署在您的业务服务端。​
  • 为该子用户授予 STSAssumeRoleAccess 权限，或创建一个仅允许对特定角色执行 sts:AssumeRole 操作的更严格的自定义策略。​
  1. 创建用于上传的 IAM 角色：在 IAM 控制台的角色管理页面中创建一个角色。信任身份选择当前账号，策略选择 STSAssumeRoleAccess。​
  1. 为角色绑定 TOS 权限策略：角色的权限策略决定了临时凭证的最终权限。请创建一个自定义策略，仅授予必要的 TOS 操作权限，然后将其绑定到角色上。切勿直接授予 TOSFullAccess。以下是一个最小权限策略示例，仅允许对 example-bucket 下amk-editor/ 前缀内的对象执行上传和读取操作。请务必将桶名和前缀替换为您自己的配置。​
  • ​
    {​
    "Statement": [​
    {​
    "Effect": "Allow",​
    "Action": [​
    "tos:PutObject",​
    "tos:GetObject"​
    ],​
    "Resource": [​
    "trn:tos:::example-bucket/amk-editor/*"​
    ]​
    }​
    ]​
    }​
    ​
  1. 记录角色 TRN：在角色详情页面，复制并保存其 TRN（火山引擎资源名称），格式为 trn:iam::<AccountId>:role/<RoleName>。此 TRN 将用于服务端的 AssumeRole 调用。​
步骤 3：实现 STS 临时凭证签发接口​
在您的业务服务端，创建一个 API 端点，例如 /api/tos-upload-sts，用于接收前端的凭证请求并返回 STS 临时凭证。​
注意​
以下 Node.js 示例仅为核心逻辑演示。生产环境的接口必须包含完整的用户登录态校验、剪辑工程 projectId 的访问权限检查、接口限流和日志审计。​
​
// 服务端代码 (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 上传功能。​
​
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://<bucket>/<key> 地址保存到素材的 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://<bucket>[/<prefix>]；VOD 格式为 vod://<space>。​
getUploadSTS​
() => Promise<AmkEditorUploadSTSCredentials>​
是​
一个异步回调函数，用于从您的业务服务端获取短期的存储访问凭证，供 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 <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 条。 ​
​
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 <YOUR_AMK_API_KEY>。 ​
响应类型 ​
普通查询接口返回 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​
首次发布。​
​
最近更新时间：2026.10.10 12:10:35
这个页面对您有帮助吗？
有用
有用
无用
无用