AI 文档字段结构化解析（同步文本）

按自定义字段解析文档内容。
详情页：https://www.gugudata.com/api/details/document-field-extraction

当前接口契约

接口详情：https://www.gugudata.com/api/details/document-field-extraction

功能说明

按自定义字段规则提取文档内容；

支持 PDF、DOCX、TXT 和 Markdown 文档；

支持直接提交最长 120,000 字符文本；

支持常规文档与扫描文档识别；

返回字段值、字段状态与置信度；

返回可供人工核对的原文依据；

标记未找到、存在歧义或提取失败的字段；

提供文档页数、字符数与处理完整度；

支持同步处理和异步任务；

适合合同、报告、表单和资料入库；

请求参数

参数	类型	必填	默认值	说明
appkey	string	否	无	支持 Query、AppKey、X-GUGUDATA-APPKEY、X-API-Key、Bearer 或 multipart body。 AppKey 整体必填；在本操作已声明支持的鉴权位置任选一个提供，本位置无需重复填写。多处填写时须一致。
file	string/binary	否	无	与 text 二选一；最大 30 MiB，支持 PDF、DOCX、TXT、MD/Markdown。PDF 最多 500 页；二进制 .doc 请先转换。
text	string	否	无	与 file 二选一；最多 120,000 字符，20,000 字符以内可同步处理。
schema	string	是	无	最大 64 KiB 的 JSON Schema 子集；顶层必须为 object，最多 6 层、200 节点和 100 个叶子字段。
instruction	string	否	无	补充字段口径，最多 4,000 字符。
ocrMode	string	否	auto	OCR 策略：auto、always 或 never。
executionMode	string	否	auto	执行模式：auto、sync 或 async；大文件、长文本和强制 OCR 使用异步任务。

正常响应字段

字段	类型	说明
Data.requestId	string	每次请求的独立标识。
Data.mode	string	同步结果为 sync，任务结果为 async。
Data.document.extension	string	按文件内容识别的实际格式。
Data.document.pageCount	integer	解析页数。
Data.document.charCount	integer	完整正文字符数。
Data.document.processedCharCount	integer	实际覆盖的正文字符数。
Data.document.chunkCount	integer	处理块数量。
Data.document.isComplete	boolean	是否完整覆盖正文。
Data.summary	object	字段总数、成功数、失败数和成功率。
Data.values	object	与请求 Schema 对应的字段结果。
Data.values.{field}.status	string	字段成功、未找到、类型错误、歧义或解析错误状态。
Data.values.{field}.normalizedValue	any	通过类型和格式校验后的字段值。
Data.values.{field}.confidence	number	0 至 1 的字段置信度。
Data.values.{field}.evidence[]	array	可在原文定位的来源和证据文本。
Data.failedFields[]	array	字段级失败路径、状态和原因。
Data.warnings[]	array	解析提示；无提示时为空数组。
Data.operationId	string	异步任务标识。
Data.pollingUrl	string	Header 鉴权的任务查询地址。
Data.result	object	任务成功时的完整抽取结果。

业务状态说明

业务状态码	业务状态码解释	备注
100	请求成功	HTTP 200。
501	参数或文件错误	HTTP 400；输入、Schema、文件格式或同步模式不符合约束。
502	请求频率受限	HTTP 429。
503	订单已到期	HTTP 403。
504	APPKEY 错误	HTTP 401；包含缺少 APPKEY。
505	调用额度耗尽	HTTP 403。
900	内部错误	HTTP 500。
901	文档解析服务不可用	HTTP 503

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

请求成功（业务码 100）。

Bodyapplication/json

示例

{
    "DataStatus": {
        "ResponseDateTime": "string",
        "DataTotalCount": 0,
        "RequestParameter": "string",
        "StatusDescription": "string",
        "StatusCode": 0
    },
    "Data": {
        "requestId": "string",
        "mode": "sync",
        "document": {
            "fileName": "string",
            "contentType": "string",
            "extension": ".pdf",
            "pageCount": 0,
            "charCount": 0,
            "processedCharCount": 0,
            "chunkCount": 1,
            "isComplete": true,
            "textExtraction": {
                "method": "string",
                "sectionCount": 0
            }
        },
        "summary": {
            "totalFields": 0,
            "succeededFields": 0,
            "failedFields": 0,
            "successRate": 0
        },
        "values": {
            "property1": {
                "status": "SUCCEEDED",
                "value": null,
                "normalizedValue": null,
                "type": "string",
                "confidence": 0,
                "reason": "string",
                "evidence": [
                    {
                        "source": "string",
                        "text": "string"
                    }
                ]
            },
            "property2": {
                "status": "SUCCEEDED",
                "value": null,
                "normalizedValue": null,
                "type": "string",
                "confidence": 0,
                "reason": "string",
                "evidence": [
                    {
                        "source": "string",
                        "text": "string"
                    }
                ]
            }
        },
        "failedFields": [
            {
                "path": "string",
                "status": "string",
                "reason": "string"
            }
        ],
        "warnings": [
            "string"
        ]
    }
}

🟠400参数或文件错误（业务码 501）。

🟠401APPKEY 错误（业务码 504）。

🟠403订单已到期（业务码 503）；调用额度耗尽（业务码 505）。

🟠404资源不存在。请求路径不存在。

🟠405请求方法不允许。当前路径不支持该 HTTP 方法。

🟠415请求内容类型不支持。上传或请求体的内容类型不符合接口要求。

🟠429请求频率受限（业务码 502）。

🔴500内部错误（业务码 900）。

🔴502数据服务暂时不可用，请稍后重试。

🔴503文档解析服务不可用（业务码 901）。

AI 文档字段结构化解析（同步文本）

当前接口契约#

功能说明#

请求参数#

正常响应字段#

业务状态说明#

请求参数

请求示例代码

返回响应

当前接口契约

功能说明

请求参数

正常响应字段

业务状态说明