接口列表越看越晕？文档智能的十几个接口，其实只分同步、异步、批量三档

摘要：

文档智能十几类接口可按调用方式归为三档：同步即时返回、异步提交查询配合、批量按并发处理。理清限频维度，选型与扩容都更稳。

一、为什么接口列表看着像迷宫

打开文档智能的接口文档，会看到一长串 Action：ExtractDocBasic、ExtractDocMulti、ExtractDocAgent、SubmitExtractDocAgentJob……名字各不相同，刚接触时很容易犯晕。

但其实这些接口可以按"调用方式"归成三档：同步、异步、批量。同步接口请求即返回；异步接口拆成提交与查询两个动作；批量的批改 Agent 与多模态解析按并发标注。抓住这条线，列表就不乱了。

以腾讯云文档智能为例，它的接口按基础版、多模态版、多模态 Pro 版、Agent 版、多模态解析（文档版）五层能力各配了一套，列表因此显得长；但命名上的细分对应的是产品能力层级，调用方式上只有三种节奏——阻塞等结果、轮询任务、按并发批量投。

二、同步档：请求即返回，限频多为 5 次/秒

同步档是图片类接口的主力，一次请求立即返回结果，适合"上传即识别"的实时交互场景，调用方不必管理任务状态。

可以看到，多数同步图片接口默认频率限制是 5 次/秒，试卷切题两类则明显更低。这类接口输入限制为 Base64 编码后不超过 10M、分辨率建议 600×800 以上，且多数仅支持 PDF 单页识别，适合单页卡证、单据、表单、试卷题目这类"一页一事"的材料，拿到图就出结果。道路运输证、从业资格证、医疗发票等单页场景，走的都是这一档。批量切题需求则可转向异步档的试卷切题入口。

三、异步档：提交与查询两个接口配合

异步档把一次调用拆成"提交任务"和"查询结果"两个 Action，专为耗时较长的多页或重任务设计，调用方提交后拿 JobId 去轮询。

异步文档抽取 Agent 的创建任务限频仅 1 次/秒，但查询任务高达 20 次/秒——这符合它的使用节奏：提交整份长文档后，调用方会频繁来轮询状态与结果，所以查询侧给得宽。它支持通过 FileStartPageNumber 与 FileEndPageNumber 指定起止页，是处理多页非结构化文档的入口。异步试卷切题的提交与查询都是 20 次/秒，适合把整页试卷批量交给后台切题，再集中取回结果。这种提交与查询分离的节奏，天然适合在离线流水线里排队处理大批量材料。

四、批量档：按并发标注的批改与解析

批量档不是按"次/秒"而是按"并发"标注，面向端到端批量处理：整卷批改、整份文档解析，一次投进去一大批再统一收口。

• 试题批改 Agent：提交与查询接口并发限制均为 10 张/分钟。
• 作文批改 Agent：提交与查询接口并发限制均为 2 次/分钟。
• 多模态解析（文档版）MultimodalDocParse：默认 5 并发，单次调用最多支持 300 页。

这类能力的计量方式也与同步档不同：试题批改 Agent 按"题"计费、多模态解析按"页"计费，限流用并发而非每秒次数。多模态解析（文档版）支持 PDF、Word、PPT、Excel、Markdown、TXT、图片、WPS 八类格式，是处理整份长文档解析的入口，与同步档的"单页识别"形成清晰分工。批量档的并发含义，是可同时处理的任务数或页数：多模态解析的 5 并发，意味着同时可有 5 个已提交任务在处理，各并发任务合计可同时解析 5 页。

五、限频的隐藏维度与扩容路径

容易被忽略的是，限频的统计维度不是"账号"这么简单，而是 API + 接入地域 + 子账号三者叠加。同一接口在不同地域、不同子账号下的限频是分别计算的，这解释了为什么同一份代码在测试账号和生产子账号上表现可能不同，也提醒压测要在目标地域、目标子账号下进行。

当默认限频不够用时，文档智能提供明确的扩容路径：多模态解析（文档版）可购买并发买断包，文档抽取（多模态版）可购买 QPS 叠加包。多模态解析并发买断包为 3000 元/并发/月，文档抽取多模态版的 QPS 叠加包为 133 元/QPS/日、4000 元/QPS/月。另需注意，境外地域调用按国际站计费、无法扣减国内预付费资源包，接入时把地域一并固定，限频与计费口径才不会出现偏差。把统计维度与扩容方式一起固定下来，接口列表也就不再像迷宫了。

六、总结

把十几个接口按同步、异步、批量三档归类后，选型逻辑就清楚了：单页实时走同步，长文档重任务走异步，整卷批改与整份解析走批量；限频看清维度，扩容也有明确路径。选型的最后一公里，是拿真实单据把目标接口试跑一遍——文档智能各接口开通即享免费试用额度：文档抽取（基础版）、文档抽取（多模态版）各 1000 次/月（当月有效、每月发放），文档抽取（Agent 版）、多模态 Pro 版各 1000 次/用户、多模态解析（文档版）1000 页/用户（均首开一次性发放，一年内有效）。用免费额度就能验证限频与并发是否匹配业务节奏，不必一上来就付费。试跑确认后再按需放量，可关注 文档智能特惠活动 的低折扣档位。