# 上传文件

> 上传图片、视频、音频，取得 7 天内有效的下载地址。

Base URL：`https://platform.sgt.site`

本页接口用于取得模型可访问的临时文件 URL。鉴权与文件输入方式见[文件与素材约定](business-auth.md)；要在媒体生成请求里用 `file_id` 引用时，改用 `/media/v1/files`，选择方法见[参考文件与素材：选择上传接口](media-files.md#media-files-h-cf1470ee)。

| 方法 | 路径 |
| --- | --- |
| POST | `/api/files/upload` |

把图片、视频或音频存到平台存储，返回 7 天内有效的下载地址，适合把本地文件变成模型可访问的 URL。文件不进入素材库，也不经过审核。

<a id="business-files-section-1"></a>

## 请求

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `file` / `base64` / `url` | — | 文件内容，三选一，见[文件输入](business-auth.md#business-auth-section-2) |
| `content_type` | string | 配合纯 Base64 或 URL 声明 MIME；URL 省略时使用源站返回的 `Content-Type` |
| `asset_type` | string | 可选，`Image`/`Video`/`Audio`，填写时须与实际类型一致 |

不接受 `name`、`group_id`、`wait_seconds`，传入返回 400。

Base64 上传音频：

```http
POST /api/files/upload HTTP/1.1
Host: platform.sgt.site
Authorization: Bearer YOUR_VIRTUAL_KEY
Content-Type: application/json
```

```json
{"base64": "data:audio/wav;base64,BASE64_AUDIO_DATA"}
```

表单上传图片：

```bash
curl -X POST "$GATEWAY_ORIGIN/api/files/upload" \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./first-frame.png;type=image/png"
```

转存公网文件：

```json
{"url": "https://media.example.com/reference.mp4"}
```

<a id="business-files-section-2"></a>

## 响应

```json
{
  "success": true,
  "data": {
    "id": "file-example",
    "file_url": "https://<bucket>.tos-<region>.volces.com/heighliner-files/<企业>/<id>?<签名参数>",
    "expires_at": 1791163200,
    "asset_type": "Audio",
    "content_type": "audio/wav",
    "size": 32044
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `id` | 文件 ID |
| `file_url` | 带签名的下载地址，到期前任何持有者都能直接下载，无需鉴权 |
| `expires_at` | 地址到期时间，Unix 秒；为上传完成时刻加 604800 秒（7 天） |
| `asset_type` / `content_type` | 识别出的文件类型与 MIME |
| `size` | 文件字节数 |

- 地址不能续期；需要更长时间时重新上传。到期后文件会被清理，实际删除时间可能略晚于 `expires_at`。
- `file_url` 在有效期内可被任何人访问，不要公开发布。
- 使用 `url` 时由平台下载源文件再存储：只能访问公网地址，重定向逐跳检查，下载超时 2 分钟，大小限制同上表；平台不会把你的虚拟密钥发给源站。