Text extraction parameters

Specifying the output format

By default, the extracted text is written in plain text. If you want the extracted text to be written in another format, like 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:

Processing mode

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.

For details about the different processing modes, see the watsonx.ai API reference documentation.

Supported languages

If your document is in a language other than English, you must specify the language by its ISO 639 language code in the languages parameter of your API request.

"parameters": {
  "languages": "de"
}

If the document has a mix of languages, list each language separately.

For example, you can extract text from images in a document with a mix of English and French text because both languages are Latin based. However, you cannot extract text from images in a document with a mix of Japanese and French text.

The language code you specify differs based on whether your document contains machine-printed text or handwriting.

Extracting text from images

You can specify how you to process text in images in your document by using optical character recognition (OCR). Specify the following parameter in the API request body:

"parameters": {
  "ocr_mode": "enabled"
}

For details about the different OCR modes, see the watsonx.ai API reference documentation.

You can also 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 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:

Extracting text in key-value pairs

You can choose to extract text as key-value pairs from documents that contain domain-specific structured data. 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.

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.

Based on the contents of your input document, you can extract key-value pair data with one of the following methods:

Generic key-value pair extraction

The generic extraction process identifies and extracts all key-value pairs in a document. This method is useful for extracting labeled information without needing to know details about specific fields in advance.

Schema-based (Fixed) extraction

The schema-based process targets specific, pre-defined fields in documents by using built-in schemas for common document types like invoices, utility bills, passports, and more. Every page is classified into one of the supported schema types. Based on the classification, text is extracted into the key-value pair format defined in the schema for the specific document type. By classifying the document first, this method increases accuracy for known document types without requiring dedicated model training.

For example, if you want to extract text as key-value pair data with a general purpose foundation model, specify the following parameter in the API request body

"parameters": {
  "kvp_mode": "generic_with_semantic"
}

If you do not specify the kvp_mode parameter in your text extraction API request, no key-value pairs are extracted from your document.

Learn more

• watsonx.ai API reference documentation
• Extracting text from documents
• Parsing extracted JSON structures

Parent topic: Text extraction