Text extraction parameters

Specifying 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:

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.

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

Specifying the languages of the input document in the languages parameter

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.

Specifying how to extract text from images with the ocr_mode and create_embedded_images parameters

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.

The following table provides details about the different OCR modes you can use to specify how to process images in your API request:

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:

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

You can identify and extract structured information into key-value pairs from unstructured or semi-structured documents such as invoices, forms, contracts, or receipts. 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.

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

Learn more

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