> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Extraction



## OpenAPI

````yaml api-reference/extract-1.0.3.openapi.yaml POST /ai/service/v3/entity_extraction
openapi: 3.0.1
info:
  title: Intelligent Document Recognition (Extraction) - API Documentation
  description: Intelligent Document Recognition (Extraction) - API Documentation
  version: 1.0.3
servers:
  - url: https://api.textin.ai
    description: Production server
security:
  - AppIdAuth: []
    SecretCodeAuth: []
paths:
  /ai/service/v3/entity_extraction:
    post:
      summary: general information extration
      operationId: llm_uie_v3
      requestBody:
        description: >
          Supported file formats: png, jpg, jpeg, pdf, bmp, tiff, webp, doc,
          docx, html, mhtml, xls, xlsx, csv, ppt, pptx, txt, ofd.


          Supports schema-based structured information extraction, where you
          define the field structure for precise extraction.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - file
                - schema
              properties:
                file:
                  type: object
                  description: File information
                  properties:
                    file_base64:
                      type: string
                      description: >
                        Base64-encoded content of the file to process. Mutually
                        exclusive with file_url.
                      example: /9j/4AAQSk...
                    file_url:
                      type: string
                      description: >
                        URL of the file to process. Mutually exclusive with
                        file_base64. If file_base64 is present, file_url is
                        ignored.
                      example: https://example.com/document.pdf
                    file_name:
                      type: string
                      description: |
                        File name for front-end display. Optional.
                      example: document.pdf
                schema:
                  type: object
                  description: >
                    Extraction data structure. See the [Schema
                    Guide](/xparse/extract/schema-guide#schema-json-structure).
                  example:
                    type: object
                    properties:
                      product:
                        type: string
                        description: Product name
                    required:
                      - product
                parse_options:
                  $ref: '#/components/schemas/ParseOptions'
                extract_options:
                  $ref: '#/components/schemas/ExtractOptions'
      responses:
        '200':
          description: Response result
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/ExtractionResult'
components:
  schemas:
    ParseOptions:
      type: object
      description: Parsing stage parameters
      additionalProperties: false
      properties:
        page_start:
          type: integer
          description: Page number to start extraction from. Default is 1.
          default: 1
          example: 1
        page_count:
          type: integer
          description: Number of PDF pages to extract. Default is 100.
          default: 100
          example: 10
        get_image:
          type: string
          description: Image retrieval mode. Default is objects.
          enum:
            - none
            - both
            - page
            - objects
          default: objects
          example: objects
        crop_dewarp:
          type: integer
          description: >-
            Whether to perform cropping and dewarping preprocessing on the
            document.
          enum:
            - 0
            - 1
          default: 0
          example: 0
        remove_watermark:
          type: integer
          description: Whether to perform watermark removal preprocessing on the document.
          enum:
            - 0
            - 1
          default: 0
          example: 0
        parse_mode:
          type: string
          description: >
            Document parsing mode. Default is scan.

            - auto: The engine selects automatically; widest applicability.

            - scan: Parse the whole document as images (e.g., each PDF page is
            parsed as an image).

            - lite: Lightweight mode; outputs only tables and text.

            - parse: Digital text parsing only; fastest.

            - vlm: Vision-language model parsing mode.
          enum:
            - auto
            - scan
            - lite
            - parse
            - vlm
          default: scan
          example: scan
        formula_level:
          type: integer
          description: Formula recognition level.
          enum:
            - 0
            - 1
            - 2
          default: 0
          example: 0
        table_flavor:
          type: string
          default: html
          enum:
            - md
            - html
            - none
        pdf_pwd:
          type: string
          description: >
            Password for an encrypted PDF document.

            Note: when wrapping this API on the front end, protect the password
            appropriately.
    ExtractOptions:
      type: object
      description: Advanced extraction controls
      additionalProperties: false
      properties:
        generate_citations:
          type: boolean
          description: Whether to generate citation information.
          default: false
          example: true
        stamp:
          type: boolean
          description: Whether to run stamp (seal) recognition.
          default: false
          example: true
    BaseResponse:
      type: object
      required:
        - code
        - message
        - version
      properties:
        code:
          type: integer
          description: >
            Status code

            - 200: Success

            - 40101: x-ti-app-id or x-ti-secret-code is empty

            - 40102: x-ti-app-id or x-ti-secret-code is invalid, authentication
            failed

            - 40103: Client IP is not in the allowlist

            - 40003: Insufficient balance, please recharge before using

            - 40004: Parameter error, please check the technical documentation
            and verify the parameters

            - 40007: Robot does not exist or is not published

            - 40008: Robot is not activated, please activate it from the market
            before retrying

            - 40302: Uploaded file size does not meet requirements, file size
            must not exceed 50M

            - 40303: File type not supported. The API will return the actual
            detected file type, e.g., "Current file type is .gif"

            - 40304: Image dimensions do not meet requirements. Images with
            aspect ratio less than 2 must have width and height between 20-20000
            pixels, other images must have width and height between 20-10000
            pixels

            - 40305: Recognition file not uploaded

            - 40306: QPS exceeds limit

            - 40400: Invalid request URL, please check if the URL is correct

            - 40422: The file is corrupted

            - 40423: Password required or incorrect password

            - 40424: Page number out of range

            - 40425: The input file format is not supported

            - 40428: Process office file failed or timeout

            - 500: Internal server error

            - 50011: LLM Connection Failed (timeout connecting to the large
            model)

            - 50012: LLM Engine Failed (large model engine error)

            - 50207: Partial failed
          enum:
            - 200
            - 40101
            - 40102
            - 40103
            - 40003
            - 40004
            - 40007
            - 40008
            - 40302
            - 40303
            - 40304
            - 40305
            - 40306
            - 40400
            - 40422
            - 40423
            - 40424
            - 40425
            - 40428
            - 500
            - 50011
            - 50012
            - 50207
          example: 200
        message:
          type: string
          description: Status message
          example: Success
        version:
          type: string
          description: Version number
          example: v3.0.29_20250819
        duration:
          type: integer
          description: Total processing time (milliseconds)
          example: 8267
        x_request_id:
          type: string
          description: Request ID
          example: 7596b8c9d2ddbc9924b66651e9efc174
        status:
          type: string
          description: Processing status
          example: finished
    ExtractionResult:
      type: object
      properties:
        result:
          type: object
          properties:
            success_count:
              type: integer
              description: Billable page count / successful page count
              example: 1
            extracted_schema:
              type: object
              description: >
                Structured extraction result: a simplified key-value structure
                extracted according to the user-defined schema.


                Because extraction is schema-driven, the specific field names
                and data types are determined by the user's schema and cannot be
                predetermined.
              additionalProperties: true
              example:
                product: >-
                  Kids' Looney Tunes UT (short-sleeve T-shirt), Women's SUPIMA
                  COTTON crew-neck T-shirt (short-sleeve)
            citations:
              type: object
              description: >
                Extraction result with coordinate information, including
                detailed location and bounding-box data for advanced processing
                scenarios.


                Because extraction is schema-driven, the specific field names
                cannot be predetermined, but every field value follows a
                consistent structure that includes the extracted value, page
                number, and detailed coordinate data.
              additionalProperties:
                type: object
                allOf:
                  - $ref: '#/components/schemas/CitationItem'
              example:
                product:
                  value: >-
                    Kids' Looney Tunes UT (short-sleeve T-shirt), Women's SUPIMA
                    COTTON crew-neck T-shirt (short-sleeve)
                  bounding_regions:
                    - page_number: 1
                      position:
                        - 137
                        - 599
                        - 1129
                        - 599
                        - 1129
                        - 625
                        - 182
                        - 625
                      text: >-
                        Kids' Looney Tunes UT (short-sleeve T-shirt), Women's
                        SUPIMA COTTON crew-neck T-shirt (short-sleeve)
            pages:
              type: array
              description: Processing information for each page of the document
              items:
                $ref: '#/components/schemas/PageInfo'
            stamps:
              type: array
              description: Stamp (seal) recognition results
              items:
                $ref: '#/components/schemas/StampInfo'
        part_durations:
          type: object
          description: Processing time per stage
          properties:
            parse_duration:
              type: integer
              description: Parsing time (milliseconds)
              example: 1080
            retrieve_duration:
              type: integer
              description: Retrieval time (milliseconds)
              example: 0
            prompt_duration:
              type: integer
              description: Prompt processing time (milliseconds)
              example: 1
            llm_duration:
              type: integer
              description: Large model inference time (milliseconds)
              example: 7114
            format_duration:
              type: integer
              description: Formatting time (milliseconds)
              example: 51
    CitationItem:
      type: object
      required:
        - value
        - bounding_regions
      properties:
        value:
          description: Extracted value of the field
          type: string
          nullable: true
          example: Kids' Looney Tunes UT (short-sleeve T-shirt)
        bounding_regions:
          type: array
          description: Bounding-box information for the field
          items:
            $ref: '#/components/schemas/BoundingRegion'
    PageInfo:
      type: object
      required:
        - page_number
        - status
        - durations
      properties:
        page_number:
          type: integer
          description: Page number
          example: 1
        image_id:
          type: string
          description: Page image ID, used to download the image
          example: 62bfe3c3a8e9c9cf.jpg
        height:
          type: integer
          description: Page height
          example: 1824
        width:
          type: integer
          description: Page width
          example: 600
        angle:
          type: integer
          description: Page angle
          enum:
            - 0
            - 90
            - 180
            - 270
          example: 0
        status:
          type: string
          description: Page processing status
          example: Success
        durations:
          type: number
          description: Page processing time (milliseconds)
          example: 930.178466796875
    StampInfo:
      type: object
      properties:
        color:
          type: string
          description: |
            Stamp color. The API returns one of the following Chinese values:
            - 红色 (red)
            - 蓝色 (blue)
            - 黑色 (black)
            - 其他 (other)
          enum:
            - 红色
            - 蓝色
            - 黑色
            - 其他
          example: 红色
        position:
          type: array
          description: >-
            Quadrilateral coordinates of the stamp [x1,y1,x2,y2,x3,y3,x4,y4], in
            the order of top-left, top-right, bottom-right, bottom-left.
          items:
            type: number
          minItems: 8
          maxItems: 8
          example:
            - 1223
            - 995
            - 1642
            - 1007
            - 1630
            - 1689
            - 1621
            - 1677
        stamp_shape:
          type: string
          description: |
            Stamp shape. The API returns one of the following Chinese values:
            - 圆章 (round)
            - 椭圆章 (oval)
            - 方章 (square)
            - 三角章 (triangular)
            - 菱形章 (diamond)
            - 其他 (other)
          enum:
            - 圆章
            - 椭圆章
            - 方章
            - 三角章
            - 菱形章
            - 其他
          example: 圆章
        type:
          type: string
          description: |
            Stamp type. The API returns one of the following Chinese values:
            - 公章 (official seal)
            - 个人章 (personal seal)
            - 专用章 (special-purpose seal)
            - 其他 (other)
            - 合同专用章 (contract seal)
            - 财务专用章 (finance seal)
            - 发票专用章 (invoice seal)
            - 业务专用章 (business seal)
          enum:
            - 公章
            - 个人章
            - 专用章
            - 其他
            - 合同专用章
            - 财务专用章
            - 发票专用章
            - 业务专用章
          example: 公章
        value:
          type: string
          description: Text content of the stamp
          example: 电力公司专用章
    BoundingRegion:
      type: object
      required:
        - page_number
        - position
        - text
      properties:
        page_number:
          type: integer
          description: Page number where the value is located
          example: 1
        position:
          type: array
          description: >
            Quadrilateral coordinates [x1,y1,x2,y2,x3,y3,x4,y4], in the order of
            top-left, top-right, bottom-right, bottom-left.
          items:
            type: number
          minItems: 8
          maxItems: 8
          example:
            - 137
            - 599
            - 1129
            - 599
            - 1129
            - 625
            - 182
            - 625
        text:
          type: string
          description: Text content within this bounding box
          example: Kids' Looney Tunes UT (short-sleeve T-shirt)
  securitySchemes:
    AppIdAuth:
      type: apiKey
      in: header
      name: x-ti-app-id
      description: >-
        Please [Sign in to
        TextIn](https://www.textin.ai/console/dashboard/setting) and navigate to
        "Console - API Keys" to view x-ti-app-id
    SecretCodeAuth:
      type: apiKey
      in: header
      name: x-ti-secret-code
      description: >-
        Please [Sign in to
        TextIn](https://www.textin.ai/console/dashboard/setting) and navigate to
        "Console - API Keys" to view x-ti-secret-code

````