# 文件上传 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 进行认证：

```http
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` |

### 请求示例

```bash
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` 过期时间戳，单位秒 |

### 响应示例

```json
{
  "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` 保持一致。

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

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

```json
{
  "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 |

### 请求示例

```bash
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 | 文件大小，单位字节 |

### 响应示例

```json
{
  "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` |