文件上传 — U-Token 通用币 Docs

U-Token 通用币同时提供两类文件上传方式：

OSS 直传：适合浏览器、大文件和高并发。文件内容不经过 U-Token 通用币网关。
一步上传兼容接口：支持远程 URL、multipart 文件流和 Base64，上传成功后直接返回可用于媒体请求的公网 fileUrl。

所有接口均需要 U-Token 通用币 API Key，支持 Authorization: Bearer sk-... 和 x-api-key。三个一步上传接口生成公开临时对象，默认 24 小时后由 OSS 生命周期规则清理。

方式对比

方式	接口	适用场景	默认上限
OSS 直传	`/api/v1/asset/get-presigned-url` + `/api/v1/asset/register`	大文件、浏览器、需要私有文件	由 OSS 策略决定
URL 上传	`/api/file-url-upload`	将公网远程文件转存到 U-Token 通用币 CDN	100 MB
文件流上传	`/api/file-stream-upload`	直接上传本地文件	100 MB
Base64 上传	`/api/file-base64-upload`	小文件、仅支持 JSON 的集成	10 MB（解码后）

uploadPath 和 fileName 都是可选值。服务端会清理不安全字符，并在真实对象名中加入 UUID，因此同名上传不会覆盖旧文件。

一步上传响应

三个兼容接口成功时使用相同响应结构：

{
  "success": true,
  "code": 200,
  "msg": "文件上传成功",
  "data": {
    "fileId": "file_550e8400e29b41d4a716446655440000",
    "fileName": "reference.png",
    "originalName": "reference.png",
    "fileSize": 245760,
    "mimeType": "image/png",
    "uploadPath": "images",
    "fileUrl": "https://assets.example.com/public/tmp/42/images/...-reference.png",
    "downloadUrl": "https://assets.example.com/public/tmp/42/images/...-reference.png",
    "uploadTime": "2026-07-24T06:00:00.000Z",
    "expiresAt": "2026-07-25T06:00:00.000Z"
  }
}

fileId 是本次响应的稳定标识格式，但当前不会创建可查询的资产数据库记录。fileUrl 和 downloadUrl 对公开临时对象相同。

URL 文件上传

POST/api/file-url-upload

从公网 HTTP(S) 地址下载文件并上传至当前账户的临时公开目录。

{
  "fileUrl": "https://example.com/reference.png",
  "uploadPath": "images",
  "fileName": "reference.png"
}

字段	类型	必须	说明
`fileUrl`	string	是	公网可访问的 HTTP(S) 文件地址。
`uploadPath`	string	否	逻辑目录，例如 `images/references`。最多保留 8 段并清理不安全字符。
`fileName`	string	否	保存时使用的展示文件名；省略时从最终 URL 推导。

curl https://u-token.ai/api/file-url-upload \
  -H "Authorization: Bearer sk-你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://example.com/reference.png",
    "uploadPath": "images",
    "fileName": "reference.png"
  }'

URL 上传默认 30 秒超时、最多 5 次重定向、最大 100 MB。每次解析和重定向都会拒绝 localhost、内网、环回、链路本地、保留地址和包含凭据的 URL，以降低 SSRF 风险。

文件流上传

POST/api/file-stream-upload

使用 multipart/form-data 直接上传本地文件。

字段	类型	必须	说明
`file`	file	是	本地文件，默认最大 100 MB。
`uploadPath`	string	否	逻辑目录。
`fileName`	string	否	保存时使用的展示文件名；省略时使用 multipart 文件名。

curl https://u-token.ai/api/file-stream-upload \
  -H "Authorization: Bearer sk-你的KEY" \
  -F "file=@./reference.png" \
  -F "uploadPath=images" \
  -F "fileName=reference.png"

文件流会经过 U-Token 通用币网关并由网关上传 OSS。大文件或高并发场景优先使用下方的 OSS 直传流程。

Base64 上传

POST/api/file-base64-upload

通过 JSON 上传原始 Base64 字符串或 Data URL。

{
  "base64Data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "uploadPath": "images",
  "fileName": "reference.png"
}

字段	类型	必须	说明
`base64Data`	string	是	原始 Base64 或 `data:<mime>;base64,...`。解码后默认最大 10 MB。
`uploadPath`	string	否	逻辑目录。
`fileName`	string	否	展示文件名。省略时根据 Data URL MIME 类型生成随机文件名。

curl https://u-token.ai/api/file-base64-upload \
  -H "Authorization: Bearer sk-你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "uploadPath": "images",
    "fileName": "reference.png"
  }'

Base64 会增加约 33% 的请求体积。超过 10 MB 的文件应使用文件流或 OSS 直传。

OSS 预签名直传

原有三步流程保持不变，并且仍是大文件上传的推荐方式：

调用 POST /api/v1/asset/get-presigned-url，提交文件元数据和可见性。
使用 HTTP PUT 将文件内容直接发送到返回的 signed_url。
使用返回的 object_key 调用 POST /api/v1/asset/register，验证对象并获取 file_url。

1. 申请上传地址

POST/api/v1/asset/get-presigned-url

创建当前账户专属的对象键和临时 OSS 预签名上传地址。

{
  "file_name": "report.pdf",
  "content_type": "application/pdf",
  "is_public": false
}

字段	类型	必须	说明
`file_name`	string	是	原始文件名。目录部分会被移除，不安全字符会被替换。
`content_type`	string	是	上传使用的 MIME 类型。
`is_public`	boolean	是	`true` 返回公开 CDN 地址；`false` 返回临时签名下载地址。

响应：

{
  "object_key": "private/tmp/42/550e8400-e29b-41d4-a716-446655440000-report.pdf",
  "signed_url": "https://assets.example.com/private/tmp/42/...?OSSAccessKeyId=..."
}

上传地址默认约 10 分钟后过期。请保存 object_key，登记时需要使用。

2. PUT 文件

curl --request PUT "SIGNED_URL" \
  --header "Content-Type: application/pdf" \
  --upload-file ./report.pdf

Content-Type 必须与申请签名时的 content_type 完全一致。不要向 OSS 请求添加 U-Token 通用币 Authorization 请求头，也不要记录或分享签名地址。

3. 登记对象

POST/api/v1/asset/register

校验对象属于当前账户且已存在，然后返回公开或私有访问地址。

{
  "object_key": "private/tmp/42/550e8400-e29b-41d4-a716-446655440000-report.pdf",
  "name": "季度报告"
}

响应：

{
  "name": "季度报告",
  "type": "application/pdf",
  "file_url": "https://assets.example.com/private/tmp/42/...?OSSAccessKeyId=..."
}

公开对象返回无需认证的 CDN URL；私有对象返回默认约一小时有效的 GET 签名 URL。需要刷新私有下载地址时，可使用同一个 object_key 再次调用登记接口。

错误处理

一步上传兼容接口错误结构：

{
  "success": false,
  "code": 413,
  "msg": "文件超过大小限制",
  "data": null
}

HTTP 状态码	含义
`400`	请求体、Base64 或 URL 无效，或缺少必填字段
`401`	API Key 缺失、无效或已停用
`413`	请求体或文件超过接口大小限制
`502`	远程下载或 OSS 上传失败

参数、鉴权、大小和上游失败使用上述兼容结构。文件接口不使用 LLM 账户限流，也不再占用已退役的按 Key / 按 IP 共享额度。

原有预签名与登记接口继续使用 OpenAI 兼容的 error 对象；OSS PUT 错误由 OSS 直接返回。

On this page