文档中心

AI MediaKit

输入输出

多源媒体输入与本地上传

AI MediaKit 的各项工具支持以多种灵活的方式接收您待处理的视频、音频或图像文件。本篇指南将详细介绍 AI MediaKit 支持的四种媒体输入协议：公网 URL（HTTP/HTTPS）、本地文件上传（mediakit://），以及直接引用火山引擎视频点播（VOD）或对象存储（TOS）中的资源。通过阅读本文，您将掌握如何为不同的媒体来源构造正确的 API 输入参数，并通过 cURL 示例快速上手。

说明

输入文件临时副本清理策略：为优化资源利用，自 2026 年 9 月 23 日起，AI MediaKit 为执行任务而拉取的输入文件临时副本，将在任务处理完成后（无论成功或失败）24 小时内自动删除。该变更覆盖所有输入源，包括公网 URL、VOD、TOS 和本地上传（mediakit://）。此变更不影响您存储在源站（如公网服务器、TOS、VOD）的原始文件，也不影响您通过本地上传方式存入的、由 file_id 标识的原始文件自身的生命周期。

媒体输入方式说明

为了适配您不同的业务架构和存储方案，AI MediaKit 支持以下四种输入协议。您可以根据实际业务场景选择最合适的传入方式。

协议	格式	描述
公网 URL	http:// 或 https://	指向一个公网可直接访问的媒体文件。这是最常规和直接的输入方式。
本地上传	mediakit://{file_id}	用于处理存储在本地设备的媒体文件。您需先调用获取媒体上传地址 API 获取文件标识 file_id 和上传地址。完成上传后，再通过 mediakit://{file_id} 引用该文件。
视频点播 VOD	vod://<空间名(Space)>/<视频ID(Vid)>	引用已存储在火山引擎视频点播（VOD）服务中的媒体资源。
对象存储 TOS	tos://<存储桶名(Bucket)>/<文件路径(Path)>	引用已存储在火山引擎对象存储（TOS）服务中的媒体文件。

使用公网 URL

如果您的媒体文件已托管在可通过公网访问的服务器上，您只需在 API 请求中直接传入文件的完整 HTTP/HTTPS 链接。

请求示例（裁剪公网可访问的视频）：

使用本地文件上传

当您的媒体文件（视频、音频、图片）存储在本地时，AI MediaKit 提供了客户端直传机制。完整的接入流程分为以下三步。

注意

本地上传限制：

单文件大小：最大 5 GB。

总存储容量：当前无限制。

存储有效期：30 天。文件将在上传 30 天后被自动清理，相关的 file_id 随之失效。

步骤 1：申请上传地址与 File ID

调用获取媒体上传地址 API 为待上传的文件申请一个唯一的标识（file_id）和带有时效性签名的上传 URL（upload_url）。

请求示例：

响应示例：

说明

请在您的业务服务端记录下返回的 file_id 和 upload_url。upload_url 有效期为 24 小时，过期后无法用于上传。

步骤 2：上传文件

使用步骤 1 获取的 upload_url，通过 PUT 方法直接上传本地文件的二进制内容。

注意

文件大小限制：上传的单个文件大小不能超过 5 GB。

断点续传：系统当前不支持断点续传。对于大文件或网络不稳定的环境，请确保上传过程的稳定性。

上传格式：必须使用纯二进制流（Raw Binary）上传，严禁使用 multipart/form-data（表单）格式。

Content-Type：需与您的文件实际类型匹配（例如：视频为 video/mp4，图片为 image/png）。

cURL 上传示例：上传本地 MP4 视频

cURL 上传示例：上传本地 PNG 图片

当上传请求成功时，服务端会返回 2xx 的 HTTP 状态码，表示文件已成功接收。

步骤 3：提交任务

文件上传成功后，在调用 AI MediaKit 处理工具时，直接将步骤 1 获取的 file_id（mediakit://...）填入对应的 URL 参数中。

请求示例（裁剪已上传的视频）：

使用火山引擎视频点播（VOD）资源

如果您的视频已托管在火山引擎视频点播（VOD）平台，您可以使用 vod:// 协议进行内网拉取。格式为：vod://<空间名(Space)>/<视频ID(Vid)>。

注意

跨服务授权：首次使用 VOD 资源前，请前往 AI MediaKit 控制台基础配置 > 授权管理页面，为 AI MediaKit 授予访问您视频点播（VOD）资源的权限。否则，任务将因无权限访问而失败。

请求示例（裁剪 VOD 中的视频）：

使用火山引擎对象存储（TOS）资源

如果您的媒体文件统一存储在火山引擎对象存储（TOS）的存储桶中，您可以使用 tos:// 协议进行内网拉取。格式为：tos://<存储桶名称(Bucket)>/<文件路径(Path)>。

注意

跨服务授权：首次使用 TOS 资源前，请前往 AI MediaKit 控制台基础配置 > 授权管理页面，为 AI MediaKit 授予访问您对象存储（TOS）资源的权限。否则，任务将因无权限访问而失败。

请求示例（裁剪 TOS 桶中的视频）：

常见问题

如何获取用于输入的 VOD 或 TOS 资源地址？

要使用 VOD 或 TOS 作为输入源，您需要按照 AI MediaKit 的格式要求，在 API 请求中提供准确的资源地址。

VOD 资源地址格式：vod://<空间名>/<视频ID>

获取空间名：前往视频点播控制台，在空间管理页面的列表中，下图红框处即是 VOD 空间的名称。

获取视频 ID (Vid)：进入对应空间的媒资管理页面，在视频列表中找到目标视频，复制其 Vid。

示例：若空间名为 my-vod-space，视频 ID 为 v0c49g70000brc6n8t21g76j3k2d8q5g，则完整的 VOD 输入地址为：vod://my-vod-space/v0c49g70000brc6n8t21g76j3k2d8q5g。

TOS 资源地址格式：tos://<存储桶名>/<文件路径>

获取存储桶名 (Bucket Name)：前往对象存储控制台，在桶列表页面中，找到 TOS 桶对应的名称。

获取文件路径 (Object Key)：进入目标桶的文件列表页面，找到您要处理的媒体文件。从存储桶根目录到该文件的完整路径（包括所有文件夹和文件名）即是所需的文件路径。

示例：若桶名为 my-tos-bucket，文件路径为 videos/input.mp4，则完整的 TOS 输入地址为：tos://my-tos-bucket/videos/input.mp4。

最近更新时间：2026.10.10 16:22:29

这个页面对您有帮助吗？

有用

无用