文档中心

AI MediaKit

其他

获取媒体上传地址 API

POST https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/request-media-upload-url

本 API 用于申请一个媒体文件上传地址，返回可直接发起 PUT 请求的上传 URL、方法和所需请求头。适用于客户端先申请上传地址、再自行上传图片/音频/视频文件的场景。这是通过本地上传方式媒体文件的第一步。完整流程如下：

关于本地文件上传的完整流程，请参阅多源媒体输入与本地上传。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

请求体（Body）为空。

请求示例

步骤 1：获取上传地址

以下示例演示了如何请求一个上传地址。

步骤 2：上传文件

获取到 upload_url 和 upload_headers 后，您需要通过 PUT 方法，将文件的二进制内容作为请求体（body）上传到该地址，并携带所有指定的请求头。

注意

响应说明

成功响应

请求成功后，接口会返回一个包含任务信息和上传凭证的 JSON 对象。

参数	类型	描述
success	Boolean	请求是否成功。固定为 true。
task_id	String	本次任务的唯一标识。
task_type	String	任务类型，固定为 request-media-upload-url。
request_id	String	本次请求的唯一标识，可用于问题排查。
result	Object	包含上传凭证和文件信息的对象。
result.file_id	String	文件的唯一标识。文件上传成功后，您可以在其他 API 调用中，使用 {file_id} 来引用该文件。
result.method	String	上传文件时需使用的 HTTP 方法，固定为 PUT。
result.upload_headers	Array<Object>	上传文件时必须在请求头中附带的键值对数组。数组中的每个对象均包含 key 和 value 字段。 result.upload_headers[].key：上传请求头名称，例如 Content-Type。 result.upload_headers[].value：上传请求头对应的值，例如 video/mp4。
result.upload_url	String	预签名的上传 URL。您需要向此 URL 发起 PUT 请求来上传文件。该 URL 有效期为 24 小时，请在获取后尽快使用。

响应示例：

错误处理

当请求的参数或鉴权信息不正确时，接口会返回一个同步的错误响应。详见错误码。示例如下：

最近更新时间：2026.07.31 15:34:37

这个页面对您有帮助吗？

有用

无用