`POST https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/request-media-upload-url` 本 API 用于申请一个媒体文件上传地址，返回可直接发起 `PUT` 请求的上传 URL、方法和所需请求头。适用于客户端先申请上传地址、再自行上传图片/音频/视频文件的场景。这是通过本地上传方式媒体文件的第一步。完整流程如下： 1. 调用本 API，获取预签名上传地址 `upload_url`、上传方法 `method`、上传请求头 `upload_headers` 和文件唯一标识 `file_id`。 2. 使用 HTTP `PUT` 方法，并附带 `upload_headers` 中的所有请求头，将文件的二进制内容上传到获取的 `upload_url`。 3. 上传成功后，在其他处理任务（如视频拼接、裁剪等）中，通过 `mediakit://{file_id}` 的格式来引用该文件。关于本地文件上传的完整流程，请参阅[多源媒体输入与本地上传](https://www.volcengine.com/docs/6448/2536893)。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_MediaKit_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](https://www.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数请求体（Body）为空。 ## 请求示例 ### 步骤 1：获取上传地址以下示例演示了如何请求一个上传地址。 ```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 '{}' ``` ### 步骤 2：上传文件获取到 `upload_url` 和 `upload_headers` 后，您需要通过 `PUT` 方法，将文件的二进制内容作为请求体（body）上传到该地址，并携带所有指定的请求头。 * 上传格式：必须使用纯二进制流（Raw Binary）上传，严禁使用 `multipart/form-data`（表单）格式。 * `Content-Type`：请求头中的 `Content-Type` 需与您上传文件的实际类型匹配（例如：视频为 `video/mp4`，图片为 `image/png`）。 ```Bash # 假设步骤 1 返回的 upload_url 为 "https://bucket.s3.com/..." # 假设步骤 1 返回的 upload_headers 为 [{"key": "Content-Type", "value": "video/mp4"}] # 将 /path/to/your/local/my-video.mp4 替换为您的本地文件路径 curl -X PUT 'https://bucket.s3.com/...' \ -H 'Content-Type: video/mp4' \ --data-binary '@/path/to/your/local/my-video.mp4' ```

注意

upload_url 具有时效性（有效期为 24 小时），获取后请尽快使用。

PUT 请求必须包含 upload_headers 响应中返回的所有 HTTP 头部。请以编程方式构造请求，而不是手动复制示例。

## 响应说明 ### 成功响应请求成功后，接口会返回一个包含任务信息和上传凭证的 JSON 对象。 |**参数** |**类型** |**描述** | |---|---|---| |success |Boolean |请求是否成功。固定为 `true`。 | |task_id |String |本次任务的唯一标识。 | |task_type |String |任务类型，固定为 `request-media-upload-url`。 | |request_id |String |本次请求的唯一标识，可用于问题排查。 | |result |Object |包含上传凭证和文件信息的对象。 | |result.file_id |String |文件的唯一标识。文件上传成功后，您可以在其他 API 调用中，使用 `mediakit://{file_id}` 的形式来引用该文件。 | |result.method |String |上传文件时需使用的 HTTP 方法，固定为 `PUT`。 | |result.upload_headers |Array |一个对象数组，代表上传文件时必须在请求头中附带的键值对。 | |result.upload_url |String |预签名的上传 URL。您需要向此 URL 发起 `PUT` 请求来上传文件。该 URL 有效期为 24 小时，请在获取后尽快使用。 | 响应示例： ```JSON { "success": true, "task_id": "amk-tool-request-media-upload-url-85678953218", "task_type": "request-media-upload-url", "result": { "file_id": "mediakit://GXM3kDyWCrGLIpeOwHZplH2sjdNyrpTYHeZ4aaOCVyNpMryQWjtSaepngQlCGdXBjSRE8G2FbUtsINb5yDr5GoPyFv7wBF2hRDdfwpJEC6JcY-iZuUdIl1-sMRGoVM-9ruYcCgBHpbYSAbPbj......", "method": "PUT", "upload_headers": [], "upload_url": "https://tob-upload-y.volcvod.com/tos-vod-cn-v-2d4440844053eb6e/mediakit/upload/local/20260615163623362376?Content-CRC32=ignore&Authorization=SpaceKey%2Famk-2100007144-default-752301%2F%2F%3Aversion%3Av2%3AeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3ODE1OTg5ODMsInNpZ25hdHVyZUluZm8iOnsiYWNjZXNzS2V5IjoiZmFrZV9hY2Nlc3Nfa2V5IiwiYnVja2V0IjoidG9zLXZvZC1jbi12LTJkNDQ0MDg0NDA1M2ViNmUiLCJleHBpcmUiOjE3ODE1OTg5ODMsImZpbGVJbmZvcyI6W3sib2lkS2V5IjoibWVkaWFraXQvdXBsb2FkL2xvY2FsLzIwMjYwNjE1MTYzNjIzMzYyMzc2Iiwi......" }, "request_id": "20260615163623DDF8458DA0F913052188" } ``` ## 错误处理当请求的参数或鉴权信息不正确时，接口会返回一个同步的错误响应。详见[错误码](https://www.volcengine.com/docs/6448/2300662)。示例如下： ```JSON { "success": false, "request_id": "20240521100500XYZW12345", "error": { "code": "AuthenticationFailed", "message": "The API Key provided is invalid or has expired.", "type": "Unauthorized" } } ```

智能处理