文件上传 API 使用说明

本文面向接入 NewAPI 的下游开发者，说明如何申请临时上传地址并将文件直接上传到对象存储。

1. 接口概览

文件上传分为两个请求：

调用 NewAPI 获取临时上传地址。
使用临时地址将文件直接 PUT 到对象存储。

文件内容不会经过 NewAPI。NewAPI Key 只用于第一个请求，不能用于对象存储上传请求。

项目	内容
预签名接口	`POST /v1/upload/presign`
鉴权方式	`Authorization: Bearer <NewAPI Key>`
上传方法	使用响应中的 `method`，当前为 `PUT`
上传地址	使用响应中的 `url`
上传请求头	使用响应中的 `headers`
上传有效期	使用响应中的 `expires_at`，Unix 秒

将 https://your-new-api.example.com 替换为实际 NewAPI 服务地址。

2. 获取上传地址

2.1 请求

POST https://your-new-api.example.com/v1/upload/presign HTTP/1.1
Authorization: Bearer sk-your-new-api-key
Content-Type: application/json

{
  "filename": "photo.png",
  "content_type": "image/png"
}

2.2 请求参数

参数	类型	必填	说明
`filename`	string	是	原始文件名，最大 255 字节
`content_type`	string	否	文件 MIME 类型，例如 `image/png`；省略时使用 `application/octet-stream`

filename 只用于保留安全的扩展名，服务端不会直接使用它作为对象路径。对象路径由服务端生成，调用方不能指定或覆盖对象键。

2.3 成功响应

HTTP 状态码为 200：

{
  "url": "https://your-bucket.tos-cn-beijing.volces.com/uploads/123/2026/07/22/uuid.png?X-Tos-Signature=...",
  "public_url": "https://your-bucket.tos-cn-beijing.volces.com/uploads/123/2026/07/22/uuid.png",
  "method": "PUT",
  "object_key": "uploads/123/2026/07/22/uuid.png",
  "headers": {
    "Content-Type": "image/png"
  },
  "expires_at": 1784682900
}

字段	类型	说明
`url`	string	临时上传 URL，必须原样使用，不要修改查询参数
`public_url`	string	对象固定地址；只有对象存储配置为公共读时才能直接访问
`method`	string	上传 HTTP 方法，当前为 `PUT`
`object_key`	string	对象存储中的对象键，建议在业务数据库中保存
`headers`	object	上传时必须携带的签名请求头
`expires_at`	integer	`url` 过期时间，Unix 秒

url 是临时敏感信息，不要长期写入日志或公开分享。expires_at 只表示上传 URL 的有效期，不代表文件会在该时间自动删除。

3. 上传文件

获取响应后，使用 method、url 和 headers 上传文件。

3.1 curl

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

其中 UPLOAD_URL 是响应中的 url。如果响应的 headers 包含其他字段，也必须一并发送。

3.2 Node.js

Node.js 18 及以上版本可以使用项目提供的客户端：

NEW_API_BASE_URL=https://your-new-api.example.com \
NEW_API_KEY=sk-your-new-api-key \
node scripts/tos-upload-client.mjs --file ./photo.png

PowerShell：

$env:NEW_API_BASE_URL = "https://your-new-api.example.com"
$env:NEW_API_KEY = "sk-your-new-api-key"
node scripts/tos-upload-client.mjs --file ".\photo.png"

如需指定媒体类型：

node scripts/tos-upload-client.mjs ./file.bin --content-type application/octet-stream

3.3 浏览器

浏览器上传时，先由后端或前端服务调用预签名接口，再使用返回的 URL 上传：

const presignResponse = await fetch('/v1/upload/presign', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${newApiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filename: file.name,
    content_type: file.type || 'application/octet-stream',
  }),
})

if (!presignResponse.ok) {
  throw new Error('获取上传地址失败')
}

const presign = await presignResponse.json()
const uploadResponse = await fetch(presign.url, {
  method: presign.method,
  headers: presign.headers,
  body: file,
})

if (!uploadResponse.ok) {
  throw new Error(`文件上传失败：${uploadResponse.status}`)
}

console.log({
  objectKey: presign.object_key,
  publicUrl: presign.public_url,
})

浏览器直传还要求 TOS Bucket 配置允许当前前端域名的 PUT CORS 请求，并允许上传时使用的请求头，例如 Content-Type。

4. 上传成功后的文件地址

上传成功后，业务侧至少保存 object_key。public_url 是否能直接访问取决于 TOS 权限：

Bucket 或对象允许公共读：可以直接使用 public_url。
Bucket 为私有：访问 public_url 会返回 403，需要由业务后端另外生成 GET 预签名下载 URL。

不要根据客户端文件名自行拼接对象地址，应该使用接口返回的 object_key 或 public_url。

5. 错误处理

5.1 NewAPI 响应错误

{
  "error": {
    "message": "upload service is not configured",
    "type": "new_api_error",
    "param": "",
    "code": "upload_service_unavailable"
  }
}

状态码	错误码或现象	处理建议
`400`	`invalid_request_body`	检查 JSON 格式和 `Content-Type`
`400`	`invalid_upload_request`	检查 `filename` 和 `content_type`
`401`	令牌无效或未提供	检查 `Authorization` 是否为有效 NewAPI Key
`403`	用户、令牌或 IP 无权限	检查令牌状态、IP 限制和用户状态
`429`	触发上传限流	默认每个 API Key 60 秒最多申请 100 次，等待后重新申请上传地址
`503`	`upload_service_unavailable`	联系 NewAPI 管理员检查 TOS 配置
`500`	`upload_presign_failed`	稍后重试并检查服务端日志

5.2 TOS 上传响应错误

状态码或现象	常见原因	处理建议
`403 SignatureDoesNotMatch`	修改了 `url` 或签名请求头不一致	原样使用 `url` 和 `headers`，尤其是 `Content-Type`
`403 AccessDenied`	URL 过期或 TOS 权限不足	重新申请 URL，并检查 Bucket/IAM 权限
`404 NoSuchBucket`	Bucket 或区域配置错误	联系 NewAPI 管理员检查 TOS 配置
网络超时	文件较大或网络不稳定	重新申请 URL 后重试上传
上传成功但 `public_url` 返回 `403`	文件不是公共读	使用后端生成的临时下载 URL

预签名 URL 过期后不可复用。重试时必须重新调用 /v1/upload/presign。

6. 调用频率限制

预签名接口默认按 API Key 对应的令牌 ID进行限流：

每个 API Key 默认每 60 秒最多申请 100 个预签名 URL。
不同 API Key 分别计算，不会因为共用同一个 OpenResty、NAT 或代理 IP 而共享额度。
实际文件从客户端直传 TOS 的 PUT 请求不计入此限制。
只有调用 POST /v1/upload/presign 才会消耗额度。

管理员可以通过环境变量调整：

UPLOAD_RATE_LIMIT_ENABLE=true
UPLOAD_RATE_LIMIT=100
UPLOAD_RATE_LIMIT_DURATION=60

关闭限流：

UPLOAD_RATE_LIMIT_ENABLE=false

修改环境变量后需要重启或重新创建 NewAPI 服务。触发限制时接口返回 429 Too Many Requests，客户端应等待一段时间后重新申请 URL，不要在短时间内无限重试。

7. 安全要求

NewAPI Key 只发送给 NewAPI，不要放入 TOS PUT 请求。
不要把 TOS_ACCESS_KEY 或 TOS_SECRET_KEY 放到客户端代码中。
不要修改预签名 URL 的查询参数。
生产环境调用 NewAPI 应使用 HTTPS。
不要把完整的预签名 URL 写入长期日志。
私有文件不要依赖 public_url，应保存 object_key 并通过后端授权下载。

8. 最小接入示例

# 1. 获取预签名信息
curl -s https://your-new-api.example.com/v1/upload/presign \
  -H "Authorization: Bearer sk-your-new-api-key" \
  -H "Content-Type: application/json" \
  -d '{"filename":"photo.png","content_type":"image/png"}'

# 2. 使用上一步返回的 url 和 headers 上传文件
curl -X PUT "<response.url>" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

# 3. 业务侧保存 response.object_key；公共读对象可使用 response.public_url

概览

模型

文字系列

图像系列

视频系列

音频系列

上传管理

文件上传

文件上传 API 使用说明

1. 接口概览

2. 获取上传地址

2.1 请求

2.2 请求参数

2.3 成功响应

3. 上传文件

3.1 curl

3.2 Node.js

3.3 浏览器

4. 上传成功后的文件地址

5. 错误处理

5.1 NewAPI 响应错误

5.2 TOS 上传响应错误

6. 调用频率限制

7. 安全要求

8. 最小接入示例

​文件上传 API 使用说明

​1. 接口概览

​2. 获取上传地址

​2.1 请求

​2.2 请求参数

​2.3 成功响应

​3. 上传文件

​3.1 curl

​3.2 Node.js

​3.3 浏览器

​4. 上传成功后的文件地址

​5. 错误处理

​5.1 NewAPI 响应错误

​5.2 TOS 上传响应错误

​6. 调用频率限制

​7. 安全要求

​8. 最小接入示例

文件上传 API 使用说明

1. 接口概览

2. 获取上传地址

2.1 请求

2.2 请求参数

2.3 成功响应

3. 上传文件

3.1 curl

3.2 Node.js

3.3 浏览器

4. 上传成功后的文件地址

5. 错误处理

5.1 NewAPI 响应错误

5.2 TOS 上传响应错误

6. 调用频率限制

7. 安全要求

8. 最小接入示例