简体中文

English

简体中文

English

主题

上传文件 ​

调用 /v1/file/upload 生成预签名上传地址，再把返回的 download_url 传给接受公网素材 URL 的接口。

http
PUT /v1/file/upload

这个接口不直接接收文件内容，而是先签发一个对象存储 PUT 地址，客户端拿到地址后再自行上传文件。适合图片、视频和其他媒体素材的预上传，使用 API Key 认证。

预签名地址默认过期时间为 900 秒，最短 60 秒，最长 3600 秒。

请求头 ​

名称类型必填说明
string是请求身份认证。使用 Bearer Token，示例：
string是请求内容类型，必须设置为

请求体 ​

名称类型必填说明
object否上传请求的自定义头部
string否文件 MIME 类型，例如 、、
object否上传 URL 的附加查询参数；不需要时可传空对象

请求示例 ​

bash
curl -X PUT https://octopusx.ai/v1/file/upload \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": {
      "Content-Type": "image/png"
    },
    "params": {}
  }'
bash
curl -X PUT https://octopusx.ai/v1/file/upload \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": {
      "Content-Type": "video/mp4"
    },
    "params": {}
  }'

响应示例 ​

json
{
  "download_url": "https://xxxx.cn/uploads/file/2026/djlh2xxxxffqhkt.png",
  "expire": 3600,
  "method": "PUT",
  "upload_url": "https://.../uploads/user/12/20260519-abcdef.png?signature=..."
}

响应字段 ​

名称类型说明
string上传成功后可直接传给图像、视频和任务接口的公网 URL
integer预签名 URL 的过期时间，单位秒
string上传方法，当前固定为
string带签名的对象存储上传地址

上传文件到预签名地址 ​

拿到 upload_url 后，对目标地址发起 PUT 请求上传文件本体。Content-Type 须与请求预签名地址时传入的值一致。

bash
# 上传视频（Content-Type 须与获取 upload_url 时声明的 video/mp4 一致）
curl -X PUT "https://.../uploads/user/12/20260519-abcdef.mp4?signature=..." \
  -H "Content-Type: video/mp4" \
  --data-binary @/path/to/video.mp4

使用场景 ​

上传后再用于素材 URL 接口 ​

  1. 调用 /v1/file/upload 取得 upload_url 与 download_url
  2. 对 upload_url 发起 PUT 上传文件
  3. 在接受公网素材 URL 的接口中把 download_url 作为输入字段传入

注意事项 ​

WARNING

这个接口只负责签发上传地址，不会替你上传文件本身。真正的文件上传需要客户端对 upload_url 再发一次 PUT 请求。

相关接口 ​