文件上传 API 文档

概述

文件上传接口用于在创建图生图、视频生成等任务前上传输入素材，并获得可直接传入 imageUrls、videoUrl 等字段的文件访问 URL。

支持两种上传方式：

方式	接口	说明
客户端直传	`POST /api/v2/open/upload/presigned`	推荐。先获取预签名上传地址，再由客户端 `PUT` 文件到存储服务
服务端转存	`POST /api/v2/open/upload`	使用 `multipart/form-data` 将文件上传到网关服务

国内 Base URL: https://api.apiverse.ai

海外 Base URL: https://api.apiverse.ai

认证方式

所有接口均需要在请求头中携带 Token 进行认证：

Authorization: Bearer {YOUR_AUTH_TOKEN}

1. 获取预签名上传 URL

POST /api/v2/open/upload/presigned

获取一个临时有效的 uploadUrl。客户端使用该 URL 通过 PUT 方式直传文件，上传成功后使用接口返回的 fileUrl 作为业务请求中的素材 URL。

Content-Type: application/json

请求参数

参数	类型	必填	说明
filename	string	是	文件名，必须包含扩展名，如 `input.jpg`、`demo.mp4`
contentType	string	否	文件 MIME 类型。不传时会根据扩展名自动推断

支持格式

类型	支持扩展名
图片	`jpg`、`jpeg`、`png`、`gif`、`webp`
视频	`mp4`、`mov`、`avi`、`mkv`、`webm`

请求示例

curl -X POST "https://api.apiverse.ai/api/v2/open/upload/presigned" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "input.jpg",
    "contentType": "image/jpeg"
  }'

响应参数

参数	类型	说明
uploadUrl	string	预签名上传 URL，客户端使用 `PUT` 上传文件
fileUrl	string	上传成功后的文件访问 URL，可用于后续创建任务
key	string	文件存储路径
expire	int64	`uploadUrl` 过期时间戳，单位秒

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "uploadUrl": "https://example-bucket.example-endpoint.com/uploads/20260513/20260513120000_abc123.jpg?OSSAccessKeyId=xxx&Expires=1778661000&Signature=xxx",
    "fileUrl": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/uploads/20260513/20260513120000_abc123.jpg",
    "key": "uploads/20260513/20260513120000_abc123.jpg",
    "expire": 1778661000
  }
}

使用 uploadUrl 上传文件

PUT 上传时的 Content-Type 必须和获取预签名 URL 时传入或自动推断的 contentType 保持一致。

curl -X PUT "{uploadUrl}" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@input.jpg"

上传成功后，使用第一步响应中的 fileUrl 创建任务：

{
  "prompt": "将图片转换为水彩画风格",
  "genType": "i2i",
  "imageUrls": [
    "https://fc-gw-sh.oss-accelerate.aliyuncs.com/uploads/20260513/20260513120000_abc123.jpg"
  ]
}

2. 表单上传文件

POST /api/v2/open/upload

通过网关服务上传文件。该接口不限制文件格式，单个文件大小不能超过 100MB。

Content-Type: multipart/form-data

请求参数

参数	类型	必填	说明
file	file	是	文件

支持格式与限制

项目	限制
文件格式	不限制
文件大小	最大 100MB

请求示例

curl -X POST "https://api.apiverse.ai/api/v2/open/upload" \
  -H "Authorization: Bearer your_auth_token_here" \
  -F "file=@input.jpg"

响应参数

参数	类型	说明
url	string	文件访问 URL，可用于后续创建任务
filename	string	上传后的文件名
size	int64	文件大小，单位字节

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "url": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/open-uploads/20260513/120000_abc123.jpg",
    "filename": "120000_abc123.jpg",
    "size": 102400
  }
}

常见错误

场景	说明
未携带 Authorization	返回认证失败
`filename` 为空	预签名接口返回参数错误
文件扩展名不支持	预签名接口返回参数错误
表单上传文件超过 100MB	表单上传接口返回参数错误
`PUT` 上传失败	检查 `uploadUrl` 是否过期、`Content-Type` 是否一致、请求方法是否为 `PUT`