---
id: "zh/api-get-api-file-preuploadfile-do"
title: "预上传文件"
language: "zh"
description: "GET /api/file/preUploadFile.do：预上传文件 接口说明，包含路径、方法、参数和返回信息。"
canonical_url: "https://www.babel.cc/public/babelwiki/zh/api-get-api-file-preuploadfile-do.html"
markdown_url: "https://www.babel.cc/public/babelwiki/ai/zh/api-get-api-file-preuploadfile-do.md"
alternates: {"en": "https://www.babel.cc/public/babelwiki/ai/en/api-get-api-file-preuploadfile-do.md", "zh": "https://www.babel.cc/public/babelwiki/ai/zh/api-get-api-file-preuploadfile-do.md"}
reading_note: "文档记录不等于当前部署能力；以实际版本、授权模块与配置为准。保留原文的可选、限制及待确认说明，勿补猜接口。 / Documentation is not a guarantee for every deployment. Preserve optional-module requirements, limitations and unresolved API contracts."
---

# 预上传文件

`GET /api/file/preUploadFile.do`

预上传用于取得上传地址和一次性上传凭据，之后还需实际传输文件内容。请求使用 `Authorization: Bearer <access_token>`。

## URL 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `parent_id` | string | 目标文件夹 ID。原文允许根目录上传时省略；企业目录操作建议显式指定有权限的目录 |
| `name` | string | 必填，文件名 |
| `file_id` | string | 上传已有文件的新版本时指定；新建文件时省略 |

## 响应示例

以下为结构示例，地址和凭据均为占位值，不能直接使用。

```json
{
  "upload_token": "<UPLOAD_TOKEN>",
  "url": "https://upload.example.com/<SERVER_RETURNED_PATH>",
  "success": true,
  "code": 0
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `url` | string | 服务端动态返回的上传地址；原文规定只能使用一次、有效期一小时 |
| `upload_token` | string | 下一步上传时提交的凭据 |
| `success` | boolean | 本次预上传请求是否成功 |
| `code` | integer | 业务状态码 |

## 第二步：上传文件内容

向返回的 `url` 发起 `multipart/form-data` POST，包含二进制字段 `file` 和字符串字段 `upload_token`。不要自行拼接上传路径，也不要将文件内容以 JSON 提交。由 HTTP 客户端生成 multipart boundary。

成功上传后的响应包含 `fileId`、`version`、`fileName`、`fileSize`、`success` 和 `code`。检查 HTTP 状态与业务结果后再认定完成；超时不等于未上传，重试前先核查已有文件。

## 安全与失败处理

- 上传地址必须属于已确认的服务端或存储服务；生产传输使用 HTTPS，发现不符合部署要求的地址时应停止并排查配置。
- 不将上传凭据、完整临时 URL 或 access_token 写入公开日志；不向动态上传域名附加无关凭据。
- 地址过期或已使用时重新申请，具体时效及字段以当前部署接口响应为准。
- 参考[获取 token](https://www.babel.cc/public/babelwiki/zh/api-post-api-token-do.html)和[文件 API](https://www.babel.cc/public/babelwiki/zh/developer-api-files.html)。