文件真实类型检测

接口标识: filetypecheck 价格: 0.008 元/次同步响应

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

接口简介

文件真实类型检测接口依据文件头部的魔数字节判定文件的真实格式，能识破只改扩展名的伪装文件，返回 MIME 类型与真实扩展名；同时传入声称的文件名即可直接获得两者是否一致的比对结论。检测只读取文件头部 1MB，超大文件无需完整传输；无法识别魔数时如实返回未检出而不猜测。适合上传安全校验、内容审核前置、文件归档分类与附件一致性核验等场景。

详细介绍

![文件真实类型检测接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261111/apiops_filetypecheck__1794363316_9e42495371b6.png)

把可执行程序改名成 .jpg 上传，是上传场景里最常见的伪装手法。文件真实类型检测接口看内容不看后缀，一眼识破伪装文件。

## 接口概述
面向上传安全校验、内容审核前置与文件归档整理等场景，传入一个待检文件，接口依据文件头部的魔数字节判定其真实格式，返回 MIME 类型与真实扩展名；还可同时传入调用方声称的文件名，接口会把声称扩展名与检测结果比对，直接给出是否一致的结论。检测只读取文件头部 1MB 内容，大文件也无需完整传输，可嵌入上传网关、审核流水线与文档系统的前置环节。

## 核心能力
1. **魔数判型**：依据文件头部魔数字节判定真实类型，改扩展名不影响检测结果。
2. **一致性比对**：传入声称文件名即可获得是否一致的布尔结论，无需自写比对逻辑。
3. **轻量检测**：只读取文件头部 1MB，超大文件的检测同样快速。
4. **如实反馈**：无法识别魔数的文件如实返回未检出，不猜测、不误报类型。

## 产品优势
1. **接入简单**：单次 POST 传一个文件即得结论，无需部署检测组件。
2. **响应迅速**：本地魔数匹配，同步返回结果。
3. **安全前置**：在文件入库前拦截伪装文件，降低恶意程序与违规内容风险。
4. **稳定可靠**：判定规则基于文件字节特征，不依赖任何第三方服务。
5. **降本增效**：省去自建魔数特征库与逐格式判断逻辑的开发维护成本。

## 效果展示
一句话理解：它就像小区门口的安检机，不管文件穿着什么「马甲」，扫一眼就知道它里面到底是什么。

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

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| file | https://example.com/demo/report.pdf | 待检文件，支持公网 URL、Base64 内容或平台文件 ID |
| filename | report.pdf | 可选，调用方声称的文件名，用于与真实类型比对一致性 |

你会拿到的结果：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 是否识别出类型 | true | `detected`，false 表示未找到可识别的魔数 |
| MIME 类型 | application/pdf | `mime`，检测出的真实类型 |
| 真实扩展名 | pdf | `ext`，以文件内容为准 |
| 声称扩展名 | pdf | `claimed_ext`，从传入文件名中提取 |
| 是否一致 | true | `match`，未传 filename 时为 null |

API请求示例：

```text
POST /api/filetypecheck
file=https://example.com/demo/report.pdf&filename=report.pdf
```

API响应示例：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "detected": true,
    "mime": "application/pdf",
    "ext": "pdf",
    "claimed_ext": "pdf",
    "match": true
  },
  "request_id": "ftc-demo-pdf-0001"
}
```

若该文件实为改名后的可执行程序，`ext` 会返回真实类型而 `match` 变为 false，业务侧即可据此拦截或转人工复核。

## 应用场景
1. **上传安检**：UGC 平台与网盘在文件入库前验明正身，拒绝伪装成图片的可执行文件。
2. **审核前置**：内容审核流水线先判类型，再按格式分发到对应的审核环节。
3. **归档分类**：历史资料整理时按真实格式自动归类，纠正错标的扩展名。
4. **附件校验**：业务系统核对收到的附件类型与提交者声称是否一致。
5. **数据清洗**：混合来源的文件先判明真实格式，再进入格式转换处理链。

## 应用案例
一个社交平台的头像上传功能屡次被人上传改名成 .jpg 的可执行文件，事后排查成本很高；接入接口后上传先检测类型，扩展名与真实类型不符的文件直接拒收，风险被拦在了入口。

一家企业文档管理系统接收各分部回传的文件，扩展名标注混乱，转换组件经常因格式错配报错；现在文件入库前统一检测出真实 MIME 类型再分发处理，转换失败率大幅下降。

一个票据影像采集系统偶尔收到压缩包混在照片队列里，导致识别流程卡死；接入检测后压缩包被自动分流到解压分支，识别流水线不再中断。

常见问题

Q：文件识别不出类型会怎样？

A：接口不会猜测，而是如实返回 detected=false，mime 与 ext 为空字符串；若传了 filename，match 返回 false。业务侧可将这类文件转人工复核或按未知类型处理。

Q：match 字段什么时候是 null？

A：未传 filename 时无从比对，match 返回 null（JSON 中为 null）；只要传了文件名，就会提取其扩展名与真实类型比对，返回 true 或 false。

Q：大文件需要完整上传吗？

A：不需要。检测只读取文件头部 1MB 内容，传公网 URL 时也只下载头部数据，超大文件同样快速返回结论。

文件检测文件类型魔数伪装文件上传安全 MIME

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

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`file`	string	必填	-	待检测文件：公网 URL / Base64(data: 开头) / 文件 ID(fileid_ 开头)
`filename`	string	选填	-	可选，文件名或 URL，用于比对声称扩展名与真实类型是否一致

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

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`detected`	boolean	是否识别出真实类型
`mime`	string	检测出的 MIME 类型
`ext`	string	真实扩展名
`claimed_ext`	string	文件名声称的扩展名
`match`	boolean	声称扩展名与真实类型是否一致（未传 filename 时为 null）
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

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

调用失败：

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

请先登录后使用在线测试