Skip to main content
POST
/
v1
/
files
/
upload_url
获取文件上传URL
curl --request POST \
  --url https://api.tokenops.ai/v1/files/upload_url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "path": "my_files/test.mp4"
}
'
{
  "upload_url": "https://bucket.cos.ap-guangzhou.myqcloud.com/example/test.mp4?sign=xxx",
  "method": "PUT",
  "path": "cos://bucket.cos.ap-guangzhou.myqcloud.com/example/test.mp4",
  "visit_url": "https://bucket.cos.ap-guangzhou.myqcloud.com/example/test.mp4"
}

​
使用指南

通过预签名 URL 上传文件分为两步：先获取上传 URL，再使用该 URL 直接上传文件到对象存储。

​
第一步：获取预签名上传 URL

调用 /v1/files/upload_url 接口，传入文件路径，获取带签名的上传 URL。 
curl -X POST "https://api.tokenops.ai/v1/files/upload_url" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "my_files/test.mp4",
    "storage_provider": "COS"
  }'
返回示例： 
{
  "upload_url": "https://bucket.cos.ap-guangzhou.myqcloud.com/my_files/test.mp4?sign=xxx",
  "method": "PUT",
  "path": "cos://bucket.cos.ap-guangzhou.myqcloud.com/my_files/test.mp4",
  "visit_url": "https://bucket.cos.ap-guangzhou.myqcloud.com/my_files/test.mp4"
}

​
第二步：使用预签名 URL 上传文件

拿到 upload_url 和 method 后，使用对应的 HTTP 方法将文件内容直接上传到该 URL。 
# 使用第一步返回的 upload_url 和 method 上传文件
curl -X PUT "<upload_url>" \
  --upload-file ./test.mp4
预签名 URL 有时效限制，获取后请尽快完成文件上传。上传完成后，可通过返回的 visit_url 访问文件，或使用 path 字段在其他 API 中引用该文件。

Authorizations

​
Authorization
string
header
required

API-Key 鉴权。所有 API 请求都应在 Authorization HTTP Header 中包含您的 API-Key，格式为 Bearer {API_KEY}

Body

application/json

获取上传 URL 的请求参数，需指定文件上传路径，可选指定存储提供商和区域。

​
path
string
required

文件上传路径，不能超过 255 个字符

Maximum string length: 255
Example:

"my_files/test.mp4"

​
storage_provider
string
default:COS

存储提供商，默认为 COS（腾讯云对象存储）

Example:

"COS"

​
region
string

存储区域，可选参数。COS 默认为 ap-guangzhou

Example:

"ap-guangzhou"

Response

获取上传URL成功

​
upload_url
string
required

预签名的文件上传 URL，客户端使用该 URL 直接上传文件到对象存储。URL 包含签名信息，有效期有限

Example:

"https://bucket.cos.ap-guangzhou.myqcloud.com/my_files/test.mp4?sign=xxx"

​
method
string
required

上传文件时使用的 HTTP 方法

Example:

"PUT"

​
path
string
required

文件的存储路径标识，COS 使用 cos:// 协议前缀，GCS 使用 tokenops:// 协议前缀

Example:

"cos://bucket.cos.ap-guangzhou.myqcloud.com/my_files/test.mp4"

​
visit_url
string
required

文件上传成功后的访问 URL

Example:

"https://bucket.cos.ap-guangzhou.myqcloud.com/my_files/test.mp4"