本文档基于最新抽取API版本v3 ，如需查看旧版API（包含Prompt模式）或在线调试，请移步Textin文档中心。

​
概述

TextIn xParse现已推出的全新版本的文档抽取API（v3）。在文档抽取中，您可以自定义抽取配置（JSON schema），指定您要抽取的字段名称、类型和字段描述，系统会根据您定义的配置进行抽取。 通过定义JSON schema，文档抽取兼顾了定义字段的灵活性和输出结果的稳定性。 您可以从多种样式的表单或文档中提取统一的结构化信息，并根据字段设定的标准类型完成自动格式转换。您可以根据下游系统的字段和结构要求来定义抽取JSON schema，以实现API”即插即用”的效果。例如，当您想要完成文档数据自动化录入系统时，文档抽取可以帮助您快速完成从复杂文档到系统结构化数据的无缝衔接。
新增功能
  1. 支持更灵活的上传文件传参方式，兼容file_url和file_base64
  2. 支持设定字段类型，包括常见的文本、数字、枚举等格式
  3. 支持抽取多个表格，且限定抽取范围
  4. 支持通过参数开关按需返回坐标信息，提升响应速度

​
文档抽取配置

​
JSON schema 结构示例

在文档抽取中最核心的配置是JSON schema，其结构示例如下： 
{
    "type": "object",
    "properties": {
        "field_name": {
            "type": ["string","null"],
            "description": "Field description"
        },
        "table_name": {
            "type": "array",
            "description": "Table description",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": ["string","null"],
                        "description": ""
                    },
                    "category": {
                        "type": ["string","null"],
                        "description": ""
                    }
                },
                "required": [
                    "name",
                    "category"
                ]
            }
        }
    },
    "required": [
        "field_name",
        "table_name"
    ]
}

​
JSON schema 结构说明和抽取指南

我们使用JSON Schema来定义要抽取的数据结构，在遵循 schema 规范的基础上，剔除了一些不必要的字段，文档抽取使用的 schema 字段如下：
  • type：schema的类型，最外层固定为object
  • properties：抽取字段的集合
    • <name>：要抽取的字段名称，由用户自定义，每个字段包含以下信息：
      • type：要抽取的字段类型，参考支持的字段类型列表
      • description：要抽取的字段描述
      • enum：当type为enum时，该字段表示抽取字段的枚举值列表
      • items：当type为array时，该字段表示要抽取的列表中的字段集合，与properties类似
  • required：指定抽取必要字段，其顺序表达了抽取输出的字段顺序，仅在type为object时需要。
在定义要抽取的数据时，您需要为每个字段提供一个名称，以及确定该字段的类型。您还可以添加可选的字段描述为大模型提供更多的上下文，帮助文档抽取准确了解需要从文档中查找和提取哪些信息。字段名称和描述越具体、表义越明确，文档抽取就越能准确地识别和抽取文档中的正确数据。

​
JSON schema 支持的字段类型

  • string：字符串
  • number：数字
  • integer：整数
  • enum：枚举
  • object：对象，对象内可以包含以下类型：string、number、integer、enum。
  • array：数组，数组内可以包含以下类型：string、number、integer、enum、object。
请注意，在JSON schema中array、object类型均支持层级嵌套结构，以便于抽取如表格或者具有多个属性的实体对象。目前文档抽取仅支持最多不超过3级的嵌套。 type可以设置为字符串（如"type": "string"）或者包含null的数组（如"type": ["string", "null"]），即使type不带null，接口底层也会默认带上null，当抽取不到数据时，接口统一返回null值。

​
JSON schema 支持的字段数量

为了获得最佳性能，保障抽取的精度和速度，在JSON schema中包含的最低层级（叶子节点）字段数量限制总计应不超过100个。

​
更多请求体参数说明

file: object 必填，传入需要处理的文件内容
  • file_url: string 待处理文件的url链接，与file_base64二选一
  • file_base64: string 待处理文件的base64编码，与file_url二选一
  • file_name: string 文件名，可选
如果file_base64和file_url同时存在，优先取file_base64的值。 parse_options: object 用于控制文档解析输出的相关参数
  • page_start：当上传的是pdf时，page_start 表示从第几页开始抽取，取值范围从1开始，不传该参数时默认从首页开始。
  • page_count：当上传的是pdf时，page_count 表示要进行抽取的pdf页数。
  • parse_mode：pdf文档的解析模式，默认为scan模式。图片不用设置，均默认按scan模式处理。
    • auto 综合文字识别和解析模式：对pdf电子档解析，会直接提取pdf中的文字
    • scan 仅按文字识别模式：将pdf当成图片处理
  • get_image：获取图片，默认为objects。
    • none 不返回任何图像
    • page 返回每一页的整页图像：即pdf页的完整页图片
    • objects 返回页面内的子图像：即pdf页内的各个子图片
    • both 返回整页图像和图像对象
  • crop_dewarp：是否进行切边矫正预处理，默认为0，不进行切边矫正。
    • 0 不进行切边矫正
    • 1 进行切边矫正
  • remove_watermark：是否进行去水印预处理，默认为0，不去水印。
    • 0 不去水印
    • 1 去水印
  • formula_level：公式识别等级，默认为0，全识别。
    • 0 行间公式和行内公式都识别
    • 1 仅识别行间公式，行内公式不识别
    • 2 不识别公式
  • table_flavor：markdown里的表格格式，默认为html，按html语法输出表格
    • md 按md语法输出表格
    • html 按html语法输出表格
    • none 不进行表格识别，把表格图像当成普通文字段落来识别
extract_options: object 用于控制更多抽取的高级功能
  • generate_citations boolean 是否生成坐标，默认为true
  • stamp boolean 是否开启印章识别，默认为true

​
使用文档抽取 API：快速启动

推荐使用我们的在线Web平台快速创建和验证 schema 抽取效果，页面使用方式请参考使用指南，之后您可以在API调用中直接使用。
您也可以参考以下示例文件和示例代码，快速验证并将文档抽取接入到您的系统和应用流程中。

​
示例文件

这里为您提供了一份Textin官方示例图片，您可以点击下载使用：文档抽取png示例.pngExtract Sample Image

​
先决条件：获取API Key

使用文档抽取API处理文档时，您需要先获取API Key。请先登录后前往 TextIn工作台 - 账号与开发者信息 获取您的x-ti-app-id 和 x-ti-secret-code。

​
请求示例

import requests

url = "https://api.textin.com/ai/service/v3/entity_extraction"

payload = {
    # 您要抽取的文件
    "file": {
        "file_url": "https://web-api.textin.com/open/image/download?filename=54efc36a05cf475aa6b39137b0717726"
    },
    # 定义抽取的schema
    "schema": {
        "type": "object",
        "properties": {
            "商品": {
                "type": ["string","null"],
                "description": ""
            },
            "商品列表": {
                "type": "array",
                "description": "",
                "items": {
                    "type": "object",
                    "properties": {
                        "名称": {
                            "type": ["string","null"],
                            "description": ""
                        },
                        "类型": {
                            "type": ["string","null"],
                            "description": ""
                        }
                    },
                    "required": ["名称","类型"]
                }
            }
        },
        "required": [
            "商品",
            "商品列表"
        ]
    },
    # 解析相关参数
    "parse_options":{
        "crop_dewarp":1,
        "get_image":"both"
    },
    # 抽取高级配置
    "extract_options":{
        "generate_citations": True,
        "stamp": True
    }
}

# 设置API key
headers = {
    "x-ti-app-id": "<api-key>",    #需替换为你的x-ti-app-id
    "x-ti-secret-code": "<api-key>",    #需替换为你的x-ti-secret-code
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

​
返回示例

{
  "code": 200,
  "message": "Success",
  "version": "v3.0.60",
  "duration": 8267,
  "x_request_id": "7596b8c9d2ddbc9924b66651e9efc174",
  "status": "finished",
  "result": {
    "success_count": 1,
    "extracted_schema": {
      "商品": "童装 Looney Tunes UT（短袖T恤）女装SUPIMA COTTON圆领T恤（短袖）",
      "商品列表": [
        {
          "名称": "童装 Looney Tunes UT（短袖T恤）",
          "类型": "童装"
        },
        {
          "名称": "女装SUPIMA COTTON圆领T恤（短袖）",
          "类型": "女装"
        }
      ]
    },
    "citations": {
      "商品": {
        "value": "童装 Looney Tunes UT（短袖T恤）女装SUPIMA COTTON圆领T恤（短袖）",
        "bounding_regions": [
          {
            "page_number": 1,
            "position": [137, 599, 1129, 599, 1129, 625, 182, 625],
            "text": "童装 Looney Tunes UT（短袖T恤）"
          }
        ],
      }
      // 商品列表...
    },
    "pages": [
      {
        "page_number": 1,
        "image_id": "62bfe3c3a8e9c9cf.jpg",
        "height": 1824,
        "width": 600,
        "angle": 0,
        "status": "Success",
        "durations": 930.178466796875
      }
    ]
  }
}

​
返回结果说明

​
常规字段说明

  • x_request_id：该请求的唯一标识
  • code：错误码，200表示成功。详情见错误码说明
  • message：错误信息，成功时为”Success”
  • version：版本号，例如”v3.0.29_20250819”
  • duration：总耗时(毫秒)，例如”8267”
  • status：处理状态，例如”finished”

​
主要结果说明：result对象

文档抽取会在返回结果的result对象中包含以下关键信息。 success_count：成功处理的文档页数。 extracted_schema：结构化的抽取结果，以json格式返回，与抽取时传入的schema定义的结构一致。 citations：抽取结果的详细信息，包含坐标位置，结构与schema定义一致。 每个抽取字段的详细信息如下：
  • <name>：在schema中定义的抽取字段名
    • value：该字段的抽取结果
    • bounding_regions：抽取结果value对应的坐标位置
      • page_number：所在页码，从1开始
      • text：边界框所在区域内的文本内容
      • position：坐标位置，长度为8的数组，表示四个顶点的像素坐标 [左上x, 左上y, 右上x, 右上y, 右下x, 右下y, 左下x, 左下y]
stamps：印章相关信息
  • color：当前印章颜色，可选值有：红色、蓝色、黑色、其他
  • position：印章的坐标信息
  • stamp_shape：当前印章形状，可选值有：圆章、椭圆章、方章、三角章、菱形章、其他
  • type：当前印章类型，可选值有：公章、个人章、专用章、其他、合同专用章、财务专用章、发票专用章、业务专用章
  • value：印章的文本内容
pages：文档页面相关信息
  • page_number：当前页码
  • image_id：当前页面图片id
  • height：文档页面高度
  • width：文档页面宽度
  • angle：页面角度（可选值0, 90, 180, 270）
  • status：当前页处理状态
  • durations：当前页处理耗时(毫秒)

​
错误码说明

错误码描述
40101x-ti-app-id 或 x-ti-secret-code 为空
40102x-ti-app-id 或 x-ti-secret-code 无效，验证失败
40103客户端IP不在白名单
40003余额不足，请充值后再使用
40004Parameter error (参数错误，请检查入参)
40007机器人不存在或未发布
40008机器人未开通，请至市场开通后重试
40301图片类型不支持
40302上传文件大小不符，文件大小不超过 50M
40303文件类型不支持，接口会返回实际检测到的文件类型，如“当前文件类型为.gif”
40304图片尺寸不符，图像宽高须介于 20 和 10000（像素）之间
40305File not uploaded (识别文件未上传)
40306qps超过限制
40400无效的请求链接，请检查链接是否正确
40424Page number out of range (页面设置超出文件范围)
40425The input file format is not supported (输入文件格式不支持)
500Engine failed (服务器内部错误)
50011LLM Connection Failed （访问大模型超时）
50012LLM Engine Faield (大模型引擎错误)

​
Prompt 模式

目前v3版本仅支持字段模式（JSON Schema ）抽取，Prompt 模式抽取请参考v2版本文档。