跳转到主要内容
POST
/
api
/
xparse
/
pipeline
文档处理流水线
curl --request POST \
  --url https://api.textin.com/api/xparse/pipeline \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-ti-app-id: <api-key>' \
  --header 'x-ti-secret-code: <api-key>' \
  --form file='@example-file' \
  --form 'stages=[{"type":"parse","config":{"provider":"textin"}}]'
{
  "code": 200,
  "message": "success",
  "elements": [
    {
      "element_id": "13a9939f23e485ca20a16c741658bcf64efd82309a6f0a8cf35679a65b2fd0dc",
      "type": "NarrativeText",
      "metadata": {
        "filename": "example.pdf",
        "filetype": "application/pdf",
        "last_modified": "1758624866230",
        "page_number": 1,
        "page_width": 1191,
        "page_height": 1684,
        "coordinates": [
          0.1822,
          0.2316,
          0.6717,
          0.2316,
          0.6717,
          0.2732,
          0.1822,
          0.2732
        ],
        "parent_id": "23a9939f23e485ca20a16c741658bcf64efd82309a6f0a8cf35679a65b2fd0dc",
        "category_depth": 1,
        "data_source": {
          "record_locator": {
            "protocol": "file",
            "remote_file_path": "/projects/demo/example.pdf"
          },
          "url": "file:///projects/demo/example.pdf",
          "version": "1758624866230967485",
          "date_created": "1764555574237",
          "date_modified": "1758624866230",
          "date_processed": "1764742970688"
        }
      },
      "text": "这是解析出的文本内容"
    }
  ],
  "stats": {
    "success_count": 1,
    "original_elements": 10,
    "chunked_elements": 0,
    "embedded_elements": 0,
    "stages": [
      {
        "type": "parse",
        "config": {
          "provider": "textin"
        }
      }
    ]
  }
}

授权

​
x-ti-app-id
string
header
必填

请登录Textin后前往 "工作台-账号设置-开发者信息" 查看 x-ti-app-id

​
x-ti-secret-code
string
header
必填

请登录Textin后前往 "工作台-账号设置-开发者信息" 查看 x-ti-secret-code

请求体

multipart/form-data
​
file
file
必填

需要处理的文档文件（支持 PDF、WORD、EXCEL、PPT、图片等多种格式）

​
stages
string
必填

流水线配置的 JSON 字符串，必须是 PipelineStage 数组。 注意：虽然这里是 string 类型（因为 form-data 限制），但内容必须是有效的 JSON 数组字符串。

Stages 说明：

Pipeline 接口使用 stages 数组来定义处理流程，每个 stage 包含：

  • type: 阶段类型，可选值：parse、chunk、embed、extract
  • config: 该阶段的配置，具体字段取决于阶段类型

使用示例

仅解析：

[{"type": "parse", "config": {"provider": "textin"}}]

解析 + 分块：

[
  {"type": "parse", "config": {"provider": "textin"}},
  {"type": "chunk", "config": {"strategy": "basic", "max_characters": 1000}}
]

解析 + 分块 + 向量化：

[
  {"type": "parse", "config": {"provider": "textin"}},
  {"type": "chunk", "config": {"strategy": "by_title", "max_characters": 500}},
  {"type": "embed", "config": {"provider": "qwen", "model_name": "text-embedding-v4"}}
]

解析 + 抽取：

[
  {"type": "parse", "config": {"provider": "textin"}},
  {"type": "extract", "config": {"schema": {...}, "generate_citations": false, "stamp": false}}
]

各阶段配置详细说明：

  1. Parse Stage (type: "parse")

Parse 参数中有必填项provider，表示文档解析服务的供应商，目前可选项如下：

  • textin: 合合信息提供的文档解析服务，在速度、准确性上均为行业领先，适合大多数场景（推荐）
  • textin-lite: 全文识别文档解析服务，适合纯文本、表格图片、电子档 pdf 等场景，速度更快，价格更低
  • mineru: 基于开源的最新 MinerU vlm 解析引擎，在学术论文等场景表现优异
  • paddle: 基于开源的最新 PaddleOCR-VL 解析引擎，在多语言和复杂文档场景（如PPT）表现优异

更多解析参数与详情参考文档解析 - Parse。

  1. Chunk Stage (type: "chunk")
  • strategy (string/必填): 分块策略，默认值：basic
    • basic: 基础分块，按字符数分割
    • by_title: 按标题分块，保持章节完整性
    • by_page: 按页面分块，保持页面完整性
  • combine_text_under_n_chars (int/可选): 将同一部分中的元素合并成一个数据块，直到该部分的总长度达到指定字符数。默认值：None。可用于将过短的小块合并成较长文本，提高语义连贯性。
  • include_orig_elements (bool/可选): 如果为 true，用于构成数据块的原始元素会出现在该数据块的 .metadata.orig_elements 中。默认值：False。用于调试或需要保留原始元素追溯的场景。
  • new_after_n_chars (int/可选): 当文本长度达到指定字符数时，强制结束当前章节并开始新的章节（近似限制）。默认值：None。适用于需要控制章节最大长度的情况下。
  • max_characters (int/可选): 数据块中允许的最大字符数上限。默认值：None。用于硬性限制块大小，避免过大块带来的处理延迟或内存占用。
  • overlap (int/可选): 将前一个文本分块末尾指定数量的字符，作为前缀应用到由过大元素分割而成的第二个及后续文本块。默认值：None。常用于确保分块之间的上下文连续性。
  • overlap_all (bool/可选): 如果为 true，重叠也会应用到由完整元素组合而成的"普通"块。默认值：False。谨慎使用，可能在语义上引入噪声。

更多分块参数与详情参考文本分块 - Chunk。

  1. Embed Stage (type: "embed")

xparse-client当前支持的文本向量化模型如下：

  • qwen 供应商，即通义千问:
    • text-embedding-v3
    • text-embedding-v4
  • doubao 供应商，即火山引擎:
    • doubao-embedding-large-text-250515
    • doubao-embedding-text-240715

更多向量化参数与详情参考向量化 - Embed。

  1. Extract Stage (type: "extract")

Extract 阶段用于从解析后的文档中提取结构化信息。

  • schema (object/必填): JSON Schema定义，用于指定要抽取的字段结构。参考文档抽取 - Extract了解详细的schema定义方法。
  • generate_citations (boolean/可选): 是否生成引用信息（坐标位置），默认值：false。当设置为 true 时，返回结果中会包含 citations 字段，包含每个抽取字段的坐标信息。
  • stamp (boolean/可选): 是否调用印章识别，默认值：false。当设置为 true 时，返回结果中会包含 stamps 字段，包含文档中的印章信息。

使用限制：

  • Extract 必须与 Parse 组合使用
  • Extract 必须在 Parse 之后
  • Extract 不能与 Chunk、Embed 同时使用

更多抽取参数与详情参考信息抽取 - Extract。

示例:

"[{\"type\":\"parse\",\"config\":{\"provider\":\"textin\"}}]"

响应

200 - application/json

处理结果

​
code
enum<integer>
默认值:200
必填

状态码

  • 200: Success
  • 40101: x-ti-app-id 或 x-ti-secret-code 为空
  • 40102: x-ti-app-id 或 x-ti-secret-code 无效，验证失败
  • 40004: 参数错误，请查看技术文档，检查传参
  • 500: 服务器内部错误

更多详细错误信息参考错误码说明。

可用选项:
200,
40101,
40102,
40004,
500
​
message
string
必填

错误信息

示例:

"success"

​
stats
object
必填
​
elements
object[]

处理后的元素列表。

注意：当使用 extract 节点时，此字段不会返回。

​
extract_result
object

抽取结果（仅在执行 extract stage 后存在）