文件基本信息获取

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

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

接口简介

文件基本信息获取接口一次读出文件的基础信息与内容体量：返回MIME类型、后缀名、大小（KB），以及可提取字符数（PDF、DOCX、TXT等文本类，二进制文件为0）与预估Token数，文本按约2.5字符/Token、图片按约1Token/1000像素估算，便于调用AI类接口前预估用量成本。网络文件无需下载完整文件即可估算，最大支持2GB。适合AI调用成本预估、文件类型校验与大文件预检。

详细介绍

![文件基本信息获取接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261109/apiops_filecounttoken__1794166657_9b6851a64b71.png)

处理文件之前先「称重」——输入文件URL或Base64，即刻获知它的类型、大小、字符数与AI处理Token预估，不必下载完整文件。

## 接口概述

文件基本信息获取接口面向AI应用开发、文件上传预检与文档管理等需要在正式处理前摸清文件底细的场景：传入文件公网URL、Base64编码或平台文件ID，接口自动识别输入形态，通过魔术字节与内容探测判定真实MIME类型和后缀名，统计文件大小（KB）与可提取字符数，并按文件类别给出Token消耗预估。URL模式采用「HEAD预检＋片段采样」：先取文件头部信息，再采样最多2MB内容按密度外推全文件指标，2GB大文件也无需完整下载。预估结果可直接用于AI接口的成本试算、上传前的类型与体积校验、档案系统的批量著录，本地分析、同步返回。

## 核心能力

1. **类型鉴定**：魔术字节优先、Content-Type与扩展名兜底，识破「改后缀」的伪装文件。
2. **大小速读**：返回文件KB大小；URL模式仅采样最多2MB，不下载完整文件，最大支持2GB。
3. **字符统计**：PDF、DOCX、DOC与文本类文件自动提取正文，给出预估字符数，二进制文件为0。
4. **Token预估**：按类别适配估算策略——文本按字符密度、图片按像素、音视频按时长、压缩包按解压体积。
5. **三种输入**：公网URL、Base64编码、平台文件ID任选其一，自动识别无需声明。

## 产品优势

- **接入简单**：仅 file 一个业务参数，POST请求、JSON返回。
- **响应迅速**：采样式分析不下载完整文件，大文件同样快速返回。
- **准确规范**：以文件真实内容判定类型，比只看扩展名可靠。
- **降本增效**：调用OCR、翻译、摘要等AI接口前先估算Token，避免超预算与无效调用。
- **稳定可靠**：本地完成分析，不依赖第三方上游服务。

## 效果展示

一句话理解：它就像快递站的「安检称重台」——包裹不用拆完，扫一眼就知道是什么东西、多重、里面有多少字，顺便估出加工费（Token）。

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

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| file | https://example.com/demo/product_manual.pdf | 文件公网URL、Base64（data:开头）或文件ID（fileid_开头），三选一 |

你会拿到的结果：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| MIME类型 | application/pdf | `file_type`，按文件真实内容判定 |
| 文件后缀 | pdf | `file_suffix` |
| 文件大小 | 2048.35 | `file_size`，单位KB（约2MB） |
| 预估字符数 | 36500 | `file_character`，二进制文件为0 |
| 预估Token数 | 14600 | `file_token`，AI处理成本试算依据 |

API请求示例：

```
POST /api/v1/filecounttoken
file=https://example.com/demo/product_manual.pdf
```

API响应示例：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "file_type": "application/pdf",
    "file_suffix": "pdf",
    "file_size": 2048.35,
    "file_character": 36500,
    "file_token": 14600
  }
}
```

这份约2MB的PDF产品手册共提取约3.65万字符，按文本密度折算约1.46万Token——把它交给翻译或摘要类AI接口之前，成本心里已有数。

## 应用场景

- **AI成本预估**：调用OCR、翻译、摘要等接口前先估算Token消耗，控制预算与计费
- **上传预检**：用户提交文件时即时校验真实类型与体积，拦截伪装与超限文件
- **文档管理**：批量著录档案的类型、大小与文本量，自动归档分类
- **大文件初筛**：2GB级文件不下载即可完成基本信息盘点
- **计费风控**：按Token预估为下游处理分档定价或限流

## 应用案例

- **AI文档助手**：接入前用户上传超大PDF直接送入大模型，频繁触发超限报错与费用争议；接入后先预检大小与Token量，超限文件提前拦截并提示分段，客诉与意外成本明显减少。
- **网盘服务**：批量导入历史文件时需要建立索引，逐份下载分析耗时过长；接入后仅凭URL采样即可回填类型、大小与文本量字段，索引构建速度大幅提升。

常见问题

Q：支持哪些文件格式？

A：覆盖PDF、DOC、DOCX等办公文档，TXT、CSV、JSON等文本，JPEG、PNG、GIF、BMP、WebP、TIFF等图片，MP3、WAV等音频，MP4等视频，以及ZIP、RAR、GZ等压缩包；无法识别的类型会返回明确的错误提示。

Q：file_size 的单位是什么？

A：单位为KB，保留2位小数，例如返回 2048.35 表示文件约2MB。

Q：file_character 和 file_token 有什么区别？

A：file_character 是从文档/文本类文件中提取统计的预估字符数，图片、音视频等二进制文件为0；file_token 是预估的AI处理Token数，所有支持的类型均有值——文本按约2.5字符/Token估算，图片按约1000像素/Token换算，音频按时长、压缩包按解压体积估算。

Q：URL模式下会下载完整文件吗？最大支持多大？

A：不会。先发HEAD请求获取文件大小与类型，再按Range采样最多2MB内容做密度外推，因此最大支持2GB的文件也能快速返回。

文件信息 MIME类型 Token预估文件大小字符统计文件预检

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

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`file`	string	必填	-	文件输入（自动识别）：公网URL / Base64(data:开头) / 文件ID(fileid_开头)

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

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`file_type`	string	文件MIME类型，如 application/pdf、image/jpeg
`file_suffix`	string	文件后缀名，如 pdf、docx、jpg
`file_size`	float	文件大小（KB，保留 2 位小数）
`file_character`	int	预估的文件字符数（PDF/DOCX/TXT可提取文本统计，二进制文件为0）
`file_token`	int	预估 Token 数量：文本类按约 2.5 字符/Token 估算（中英混合均值），图片类按约 1 Token/1000 像素估算
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

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

调用失败：

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

请先登录后使用在线测试