快速启动

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

概述

TextIn xParse现已推出的全新版本的文档抽取API（v3）。在文档抽取中，您可以自定义抽取配置（JSON schema），指定您要抽取的字段名称、类型和字段描述，系统会根据您定义的配置进行抽取。通过定义JSON schema，文档抽取兼顾了定义字段的灵活性和输出结果的稳定性。您可以从多种样式的表单或文档中提取统一的结构化信息，并根据字段设定的标准类型完成自动格式转换。您可以根据下游系统的字段和结构要求来定义抽取JSON schema，以实现API”即插即用”的效果。例如，当您想要完成文档数据自动化录入系统时，文档抽取可以帮助您快速完成从复杂文档到系统结构化数据的无缝衔接。

新增功能

支持更灵活的上传文件传参方式，兼容file_url和file_base64
支持设定字段类型，包括常见的文本、数字、枚举等格式
支持抽取多个表格，且限定抽取范围
支持通过参数开关按需返回坐标信息，提升响应速度

文档抽取配置

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个。

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

推荐使用我们的在线Web平台快速创建和验证 schema 抽取效果，页面使用方式请参考使用指南，之后您可以在API调用中直接使用。

您也可以参考以下示例文件和示例代码，快速验证并将文档抽取接入到您的系统和应用流程中。

示例文件

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

先决条件：获取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：当前页处理耗时(毫秒)

错误码说明

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

Prompt 模式

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

产品概览

文档解析

文档抽取

FAQ

概述

文档抽取配置

JSON schema 结构示例

JSON schema 结构说明和抽取指南

JSON schema 支持的字段类型

JSON schema 支持的字段数量

更多请求体参数说明

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

示例文件

先决条件：获取API Key

请求示例

返回示例

返回结果说明

常规字段说明

主要结果说明：result对象

错误码说明

Prompt 模式

产品概览

文档解析

文档抽取

FAQ

​概述

​文档抽取配置

​JSON schema 结构示例

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

​JSON schema 支持的字段类型

​JSON schema 支持的字段数量

​更多请求体参数说明

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

​示例文件

​先决条件：获取API Key

​请求示例

​返回示例

​返回结果说明

​常规字段说明

​主要结果说明：result对象

​错误码说明

​Prompt 模式

概述

文档抽取配置

JSON schema 结构示例

JSON schema 结构说明和抽取指南

JSON schema 支持的字段类型

JSON schema 支持的字段数量

更多请求体参数说明

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

示例文件

先决条件：获取API Key

请求示例

返回示例

返回结果说明

常规字段说明

主要结果说明：result对象

错误码说明

Prompt 模式