AI MediaKit 的各个 API 在接收媒体输入时，通过统一的 URL 参数（如 `video_url`, `audio_url`, `image_url`）提供了高度的灵活性。为了适配您不同的业务架构和存储方案，AI MediaKit 支持以下多种媒体输入方式。本文提供各项输入方式的详细说明与接入指引。 ## 媒体输入方式说明为了适配您不同的业务架构和存储方案，AI MediaKit 支持以下四种输入协议。您可以根据实际业务场景选择最合适的传入方式。 |协议 |格式 |描述 | |---|---|---| |公网 URL |`http://` 或 `https://` |指向一个公网可直接访问的媒体文件。这是最常规和直接的输入方式。 | |本地上传 |`mediakit://{file_id}` |用于处理存储在本地设备的媒体文件。您需先调用[获取媒体上传地址 API](https://www.volcengine.com/docs/6448/2536891) 获取文件标识 `file_id` 和上传地址。完成上传后，再通过 `mediakit://{file_id}` 引用该文件。 | |视频点播 VOD |`vod://<空间名(Space)>/<视频ID(Vid)>` |引用已存储在火山引擎视频点播（VOD）服务中的媒体资源。 | |对象存储 TOS |`tos://<存储桶名(Bucket)>/<文件路径(Path)>` |引用已存储在火山引擎对象存储（TOS）服务中的媒体文件。 | ## 使用公网 URL 如果您的媒体文件已托管在可通过公网访问的服务器上，您只需在 API 请求中直接传入文件的完整 HTTP/HTTPS 链接。请求示例（裁剪公网可访问的视频）： ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/trim-video' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.volcengine.com/full_video.mp4", "start_time": 10.5, "end_time": 60 }' ``` ## 使用本地文件上传当您的媒体文件（视频、音频、图片）存储在本地时，AI MediaKit 提供了客户端直传机制。完整的接入流程分为以下三步。

注意

本地上传限制：

单文件大小：最大 5 GB。

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

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

### 步骤 1：申请上传地址与 File ID 调用[获取媒体上传地址 API](https://www.volcengine.com/docs/6448/2536891) 为待上传的文件申请一个唯一的标识（`file_id`）和带有时效性签名的上传 URL（`upload_url`）。请求示例： ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/request-media-upload-url' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{}' ``` 响应示例： ```JSON { "success": true, "task_id": "amk-tool-request-media-upload-url-85694246914", "task_type": "request-media-upload-url", "result": { "file_id": "mediakit://GXM3kDyWCrGLIpeOwHZplH2sjd......", "method": "PUT", "upload_headers": [], "upload_url": "https://tob-upload-y.volcvod.com/tos-vod-cn-v-2d4440844053eb6e/mediakit/upload/local/20260616143850583248?Content-CRC32=ignore&Authorization=SpaceKey%2Famk-2100007144-default-752301%2F%2F%3Aversion%3Av2%3AeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3ODE2NzgzMzAs......" }, "request_id": "2026061614385027410ADCB136EA73B1A4" } ```

说明

请在您的业务服务端记录下返回的 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 视频 ```Bash # 将 upload_url 替换为第 1 步返回的 upload_url # 使用 --data-binary 参数指定本地文件路径并以二进制形式上传 # 将 @/Users/your_name/video/test.mp4 替换成你自己的本地文件路径 curl -X PUT -i "https://tos-upload-node.volces.com/your-temp-path?Signature=..." \ -H "Content-Type: video/mp4" \ --data-binary "@/Users/your_name/video/test.mp4" ``` cURL 上传示例：上传本地 PNG 图片 ```Bash curl -X PUT -i "https://tos-upload-node.volces.com/your-temp-path?Signature=..." \ -H "Content-Type: image/png" \ --data-binary "@/Users/your_name/images/test.png" ``` 当上传请求成功时，服务端会返回 2xx 的 HTTP 状态码，表示文件已成功接收。 ### 步骤 3：提交任务文件上传成功后，在调用 AI MediaKit 处理工具时，直接将步骤 1 获取的 `file_id`（`mediakit://...`）填入对应的 URL 参数中。请求示例（裁剪已上传的视频）： ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/trim-video' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "mediakit://1u03Sui7MxNouT1perrV...", "start_time": 10.5, "end_time": 60 }' ``` ## 使用火山引擎视频点播（VOD）资源如果您的视频已托管在火山引擎视频点播（VOD）平台，您可以使用 `vod://` 协议进行内网拉取。格式为：`vod://<空间名(Space)>/<视频ID(Vid)>`。

注意

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

请求示例（裁剪 VOD 中的视频）： ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/trim-video' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "vod://space-test2/v0cd7ag7007bd77iil7og65hfa66gqsg", "start_time": 10.5, "end_time": 60 }' ``` ## 使用火山引擎对象存储（TOS）资源如果您的媒体文件统一存储在火山引擎对象存储（TOS）的存储桶中，您可以使用 `tos://` 协议进行内网拉取。格式为：`tos://<存储桶名称(Bucket)>/<文件路径(Path)>`。

注意

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

请求示例（裁剪 TOS 桶中的视频）： ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/trim-video' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "tos://your-bucket-name/path/to/video.mp4", "start_time": 10.5, "end_time": 60 }' ```

智能处理