文件上传

接口标识: fileupload 价格: 0.0001 元/次 VIP免费同步响应

接口介绍
接口文档
在线测试

接口简介

文件上传接口把本地文件托管到平台，返回全平台通用的文件ID，可直接作为文档转换、签章、识别等文件类接口的输入引用，免去每次调用重复传大文件。分类大小上限：图像10MB、文档50MB、音频50MB、视频100MB；内置MD5去重，相同文件默认不重复上传，也可强制重新上传。返回文件ID、上传状态、文件大小与MIME类型。适合合同归档、材料收单与文件处理流水线。

详细介绍

![文件上传接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261109/apiops_fileupload__1794166661_ceb55d7566ee.png)

把文件交给平台，即刻拿到一张全平台通用的「文件凭证」——文件异步上传至云端存储空间，后续所有文件类接口凭 file_id 直接取用。

## 接口概述

文件上传接口面向合同归档、材料收单、文件处理流水线等需要把本地文件送入云端并供后续接口引用的场景：以 multipart/form-data 提交文件后，接口先完成类型白名单与分类大小校验、计算文件MD5，随即返回全平台通用的文件ID（file_id），真正的云端上传在后台异步完成，不占用请求等待时间。同一文件重复提交时按MD5自动去重，直接返回原文件ID。拿到的 file_id 可直接作为文档转换、签章提取、图像处理等各类文件接口的 file 参数，平台自动完成解析，无需自己维护文件地址。

## 核心能力

1. **异步受理**：提交后立即返回文件ID与受理状态，后台完成云端上传，大文件也不阻塞请求。
2. **MD5去重**：同一文件重复提交直接返回原文件ID，不重复占用存储空间（可传 reset=1 强制重传）。
3. **类型与大小管控**：按扩展名白名单校验类型，覆盖图像、文档、音频、视频四大类，分类限额（图像10MB、文档50MB、音频50MB、视频100MB）超限即时报错。
4. **全平台互通**：file_id 可作为本平台各文件类接口的 file 参数直接引用，自动解析为实际文件。

## 产品优势

- **接入简单**：标准 multipart/form-data 上传，业务参数仅文件与去重开关两项。
- **响应迅速**：受理即返回，云端上传在后台完成，接口耗时不随文件体积线性增长。
- **稳定可靠**：上传状态全程可查（processing/finish/fail），引用未完成文件时有明确提示。
- **降本增效**：MD5去重避免重复存储与重复上传，节省存储与带宽开销。
- **生态开放**：与文档转换、签章、图像处理等接口以 file_id 无缝串联，组成完整文件流水线。

## 效果展示

一句话理解：它就像机场的行李托运——你把文件交到柜台，立刻拿到一张行李票（file_id），文件由后台送进你自己的仓库，之后任何接口凭票取件。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| input_file | contract_scan.jpg | 要上传的文件本体，以 multipart/form-data 文件域提交 |
| reset | 0 | 去重控制：0=相同文件不重复上传（默认），1=强制重新上传 |

你会拿到的结果：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 文件凭证 | fileid_aB3xK9mPqR7t1762502400 | `file_id`，后续接口的 file 参数直接填它 |
| 上传状态 | processing | `oss_status`，变为 finish 即上传完成 |
| 文件大小 | 300 | `file_size`，单位 KB |
| 文件类型 | image/jpeg | `file_type`，MIME 类型 |

API请求示例：

```
POST /api/v1/fileupload
Content-Type: multipart/form-data
input_file=contract_scan.jpg
reset=0
```

API响应示例：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "file_id": "fileid_aB3xK9mPqR7t1762502400",
    "oss_status": "processing",
    "file_size": 300,
    "file_type": "image/jpeg"
  }
}
```

受理即返回：`file_id` 已可用于后续接口，`oss_status` 为 processing 表示后台仍在上传，完成后变为 finish；若引用时提示「文件尚未上传完成，请稍后再试」，稍候重试即可。

## 应用场景

- **电子合同归档**：业务系统将合同扫描件统一托管，凭 file_id 衔接自动签章与格式转换
- **材料收单**：报名、认证、理赔等场景批量收取用户材料，去重机制避免重复提交占用空间
- **文件流水线前置**：先把文件送云，再串联文档转换、签章提取、图像处理等接口
- **音视频托管**：培训、客服质检场景上传录音录像，供后续处理与回放引用
- **跨接口文件复用**：一次上传、多接口引用，免去各系统各自维护文件地址

## 应用案例

- **OA办公系统**：接入前员工提交的附件散落在各业务模块、重复存储严重；接入后附件统一托管并自动去重，同一文件多次流转只存一份，存储成本明显下降。
- **在线教育平台**：学员作业原先由各服务各自上传、地址难以统一管理；接入后作业文件先入云拿到 file_id，批改、转换、归档环节凭同一凭证取件，流程串接的开发量大幅减少。

常见问题

Q：上传成功后为什么返回的是文件ID而不是文件URL？

A：接口采用异步上传模式：受理后立即返回 file_id，文件在后台上传至平台附件存储。file_id 是全平台通用的文件凭证，可直接作为文档转换、签章、识别等接口的 file 参数使用，平台会自动解析为实际文件。

Q：如何判断文件是否已上传完成？

A：响应中的 oss_status 字段表示状态：processing 为上传中、finish 为已完成、fail 为失败。若引用尚未完成的文件，后续接口会返回「文件尚未上传完成，请稍后再试」，稍候重试即可。

Q：支持哪些文件类型？大小限制是多少？

A：覆盖图像、文档、音频、视频四大类常见格式。分类大小上限：图像10MB、文档50MB、音频50MB、视频100MB、其他类20MB，超限会返回明确错误提示。

Q：重复上传同一个文件会怎样？

A：默认开启MD5去重（reset=0）：同一账号重复提交内容相同的文件时直接返回已有的 file_id，不重复占用存储；如需强制重新上传，传 reset=1。

文件上传云存储文件托管文件ID 附件上传异步上传

接口地址： https://www.phpwc.cn/api/fileupload

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`input_file`	string	选填	-	上传的文件（multipart/form-data，网关转为 file_base64）
`reset`	int	选填	`0`	去重控制：0=相同文件不重复上传（默认），1=强制重新上传

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`file_id`	string	文件ID（格式：fileid_ + 22位字符，如 fileid_20PYjmjJ47931789726438）
`oss_status`	string	上传状态：processing=上传中，finish=已完成，fail=失败
`file_size`	int	文件大小（KB）
`file_type`	string	文件MIME类型
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

请先登录后使用在线测试