Text extraction parameters

When you submit a text extraction request by using the watsonx.ai REST API, you include a payload that specifies configuration details for the text extraction operation.

Make choices about the various common REST API settings used to process text in your documents. For details, see Text processing parameters.

In addition, choose how to configure the following settings in the text extraction REST API request body that meet your requirements:

Setting the output format with the requested_outputs parameter

By default, the extracted text is written in plain text. If you want the extracted text to be written in another format, such as Markdown, specify the following parameter in the API request body:

"parameters": {
  "requested_outputs": [
    "md"
  ]
}

The following table provides details about the different output formats generated by the text extraction process when you specify the requested_outputs paramater in your API request:

Output formats supported by the text extraction API
Requested output Generated file type Description
md Markdown Extracted information is serialized in Markdown format. Data structures such as section titles, tables, and paragraphs are represented using Markdown tags. The result does not contain key-value pair data.
html HTML Extracted information is serialized in HTML format. Data structures such as section titles, tables, and paragraphs are represented using HTML tags. The result does not contain key-value pair data.
plain_text Plain text Extracted information is serialized in plain text format. The result only contains unstructured text. The result does not contain tables, section titles, or key-value pair data.
assembly JSON Extract text into a JSON format. The result contains all unstructured text and data structures such as tables, key-value pairs, and visual bounding box information.
page_images PNG Extract each page of the document into a separate image.

Setting the processing mode with the mode parameter

You can control the speed at which your text extraction request is processed by setting the mode parameter in your API request.

"parameters": {
  "mode": "standard"
}

The high_quality processing mode preserves all data structures in your document but may take longer to process than the standard mode. In the standard mode, the extraction request completes faster but generates lower quality output that may lack details.

Specifying how to represent embedded images with the create_embedded_images parameters

You can configure how to process images embedded in your document and convert them to Markdown and JSON formats.

The embedded image is the area on a page of the document that represents only the picture without including portions of the page that contain text or tables. Text and tables in the original document are processed with optical character recognition (OCR). The embedded images extraction mode is used to specify how to serialize images in the document and preserve them in the extracted output.

Based on the embedded images extraction mode you specify, you can choose how embedded images are represented in the output:

  • Whether to include images in the extracted output. If images are included, they are stored in the embedded_images_assembly folder as .png files
  • Whether generic placeholder text or the text extracted by OCR directly from the image appears in the Markdown and JSON output formats
  • Whether image is verbalized by describing the image in natural language. For example, an image of a cat may be verbalized as The image displays a cat resting on the floor.

To extract embedded images including text that describes the images, specify the following parameter in the API request body:

"parameters": {
  "create_embedded_images": "enabled_verbalization"
}

Images extracted in a JSON output format are represented in the Picture object. Based on the embedded images mode you specify, the following attributes in the JSON object are used to store the image details:

  • text : Stores a string that contains the text extracted directly from the image
  • verbalization : Stores a string that contains the textual description of the image.
  • children_ids : Each word in the text releated to an image is represented as tokens and stored as a list of token IDs.

For details about the JSON output schema, see Text extraction JSON schema.

The following table provides details about the different modes you can use in your API request to extract embedded images:

Embedded images extraction modes in the text extraction API
Mode Usage Image (in bytes) in output Markdown output details JSON output details
disabled Suited for an application that does not need to include images in the output. OCR processes tables and other data structures in the document. No None None
enabled_placeholder Suited for an application that needs to process images, but does not require image description and use a custom im,age verbalizer to generate image descriptions. ✓ Link to image location • Image in the pictures structure
• picture.text is empty
• List of token IDs that represent generic placeholder text in picture.children_ids
enabled_text Suited for an application that needs to process images, but does not require image description and use a custom im,age verbalizer to generate image descriptions. ✓ Text is extracted from the image • Image in the pictures structure
• Text extracted directly from the image in picture.text
• List of token IDs that represent text extracted from the image in picture.children_ids
enabled_verbalization Suited for an application that uses image descriptions to implements image search. ✓ • Link to image location
• Textual description of the image		 • Image in the pictures structure
• Textual description of the image in picture.verbalization only if the image was verbalized in the original document
• List of token IDs that represent the textual description of the image
enabled_verbalization_all Suited for an application that uses image descriptions to implements image search. ✓ • Link to image location
• Textual description of the image		 • Image in the pictures structure
• Textual description of the image in picture.verbalization only if the image was verbalized in the original document
• List of token IDs that represent the textual description of the image

Specifying how to extract data in key-value pairs with the kvp_mode parameter

The extracted text is stored in a format where each piece of data (the value) is associated with a unique identifier (the key). Key-value pair data is extracted by using a general-purpose foundation model or a model that is tuned for specific document formats.

For details about how key value pairs are processed by the document understanding technology, see Processing text as key-value pairs.

The following restrictions apply when you use the key-value pair extraction capability:

  • Key-value pair data extraction is only supported for English language documents.
  • The result of the key-value pair extraction is only available in the assembly output format. Key-value pairs are not extracted in the html, markdown, or plain_text output formats.

For details about the various key-value pair extraction methods to process structured data in your documents, see Key-value pair extraction modes.

Learn more