Extract text from documents by file ID

POST 
/api/v2/Ocr/file

Used by the AI Services catalog: files are uploaded to the file manager first and then referenced by id. A failure on one file is reported as a per-file error and does not abort the others.

Request

Query Parameters

culture string

Use this param to override the culture of the response. Options: - en (default) - es

application/json

Body

The OCR request with the file ids, the model selection and optional instructions.

fileIds uuid[]nullable

The ids of the files to process. The files must already exist in the system.

instructions stringnullable

Possible values: <= 4000 characters

Optional instructions guiding the extraction. If not provided, the system will attempt to extract all text from the documents.

userIdentifier stringnullable

Possible values: <= 256 characters

Optional user identifier for tracking and cost management purposes.

channel stringnullable

Possible values: <= 64 characters

The channel used in the execution.

aiModelId uuidnullable

The unique identifier of the AI model to use. Used instead of Vendor and ModelCode.

modelCode stringnullable

The model code to use. Used together with Vendor when AIModelId is not provided.

vendor stringnullable

The vendor of the model to use. Used together with ModelCode when AIModelId is not provided.

text/json

Body

The OCR request with the file ids, the model selection and optional instructions.

fileIds uuid[]nullable

The ids of the files to process. The files must already exist in the system.

instructions stringnullable

Possible values: <= 4000 characters

Optional instructions guiding the extraction. If not provided, the system will attempt to extract all text from the documents.

userIdentifier stringnullable

Possible values: <= 256 characters

Optional user identifier for tracking and cost management purposes.

channel stringnullable

Possible values: <= 64 characters

The channel used in the execution.

aiModelId uuidnullable

The unique identifier of the AI model to use. Used instead of Vendor and ModelCode.

modelCode stringnullable

The model code to use. Used together with Vendor when AIModelId is not provided.

vendor stringnullable

The vendor of the model to use. Used together with ModelCode when AIModelId is not provided.

application/*+json

Body

The OCR request with the file ids, the model selection and optional instructions.

fileIds uuid[]nullable

The ids of the files to process. The files must already exist in the system.

instructions stringnullable

Possible values: <= 4000 characters

Optional instructions guiding the extraction. If not provided, the system will attempt to extract all text from the documents.

userIdentifier stringnullable

Possible values: <= 256 characters

Optional user identifier for tracking and cost management purposes.

channel stringnullable

Possible values: <= 64 characters

The channel used in the execution.

aiModelId uuidnullable

The unique identifier of the AI model to use. Used instead of Vendor and ModelCode.

modelCode stringnullable

The model code to use. Used together with Vendor when AIModelId is not provided.

vendor stringnullable

The vendor of the model to use. Used together with ModelCode when AIModelId is not provided.

Responses

200

Returns the OCR result per file, plus the execution instance id and cost.

text/plain

Schema

Schema

instanceId uuid

files

object[]

nullable

Array [

index int32

source stringnullable

success boolean

result

object

model stringnullable

provider stringnullable

pages

object[]

nullable

Array [

index int32required

markdown stringnullablerequired

images

object[]

nullable

Array [

id stringnullablerequired

base64 stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

tables

object[]

nullable

Array [

content stringnullablerequired

format int32

Possible values: [0, 1]

The table content format. 0 = Html, 1 = Markdown.

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

hyperlinks

object[]

nullable

Array [

url stringnullablerequired

text stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

header stringnullable

footer stringnullable

dimensions

object

width int32

height int32

dpi int32nullable

confidence

object

averagePageScore doublenullable

minimumPageScore doublenullable

wordScores

object[]

nullable

Array [

word stringnullable

score double

]

blocks

object[]

nullable

Array [

label stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

]

usage

object

inputTokenCount int64nullable

outputTokenCount int64nullable

totalTokenCount int64nullable

cachedInputTokenCount int64nullable

reasoningTokenCount int64nullable

additionalCounts

object

nullable

property name* int64

markdown stringnullable

error stringnullable

]

tokenUsage

object

promptTokens int32

completionTokens int32

totalTokens int32

cost

object

amount double

currency stringnullable

Example (from schema)

{
  "instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "files": [
    {
      "index": 0,
      "source": "string",
      "success": true,
      "result": {
        "model": "string",
        "provider": "string",
        "pages": [
          {
            "index": 0,
            "markdown": "string",
            "images": [
              {
                "id": "string",
                "base64": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "tables": [
              {
                "content": "string",
                "format": 0,
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "hyperlinks": [
              {
                "url": "string",
                "text": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "header": "string",
            "footer": "string",
            "dimensions": {
              "width": 0,
              "height": 0,
              "dpi": 0
            },
            "confidence": {
              "averagePageScore": 0,
              "minimumPageScore": 0,
              "wordScores": [
                {
                  "word": "string",
                  "score": 0
                }
              ]
            },
            "blocks": [
              {
                "label": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ]
          }
        ],
        "usage": {
          "inputTokenCount": 0,
          "outputTokenCount": 0,
          "totalTokenCount": 0,
          "cachedInputTokenCount": 0,
          "reasoningTokenCount": 0,
          "additionalCounts": {}
        },
        "markdown": "string"
      },
      "error": "string"
    }
  ],
  "tokenUsage": {
    "promptTokens": 0,
    "completionTokens": 0,
    "totalTokens": 0
  },
  "cost": {
    "amount": 0,
    "currency": "string"
  }
}

application/json

Schema

Schema

instanceId uuid

files

object[]

nullable

Array [

index int32

source stringnullable

success boolean

result

object

model stringnullable

provider stringnullable

pages

object[]

nullable

Array [

index int32required

markdown stringnullablerequired

images

object[]

nullable

Array [

id stringnullablerequired

base64 stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

tables

object[]

nullable

Array [

content stringnullablerequired

format int32

Possible values: [0, 1]

The table content format. 0 = Html, 1 = Markdown.

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

hyperlinks

object[]

nullable

Array [

url stringnullablerequired

text stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

header stringnullable

footer stringnullable

dimensions

object

width int32

height int32

dpi int32nullable

confidence

object

averagePageScore doublenullable

minimumPageScore doublenullable

wordScores

object[]

nullable

Array [

word stringnullable

score double

]

blocks

object[]

nullable

Array [

label stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

]

usage

object

inputTokenCount int64nullable

outputTokenCount int64nullable

totalTokenCount int64nullable

cachedInputTokenCount int64nullable

reasoningTokenCount int64nullable

additionalCounts

object

nullable

property name* int64

markdown stringnullable

error stringnullable

]

tokenUsage

object

promptTokens int32

completionTokens int32

totalTokens int32

cost

object

amount double

currency stringnullable

Example (from schema)

{
  "instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "files": [
    {
      "index": 0,
      "source": "string",
      "success": true,
      "result": {
        "model": "string",
        "provider": "string",
        "pages": [
          {
            "index": 0,
            "markdown": "string",
            "images": [
              {
                "id": "string",
                "base64": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "tables": [
              {
                "content": "string",
                "format": 0,
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "hyperlinks": [
              {
                "url": "string",
                "text": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "header": "string",
            "footer": "string",
            "dimensions": {
              "width": 0,
              "height": 0,
              "dpi": 0
            },
            "confidence": {
              "averagePageScore": 0,
              "minimumPageScore": 0,
              "wordScores": [
                {
                  "word": "string",
                  "score": 0
                }
              ]
            },
            "blocks": [
              {
                "label": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ]
          }
        ],
        "usage": {
          "inputTokenCount": 0,
          "outputTokenCount": 0,
          "totalTokenCount": 0,
          "cachedInputTokenCount": 0,
          "reasoningTokenCount": 0,
          "additionalCounts": {}
        },
        "markdown": "string"
      },
      "error": "string"
    }
  ],
  "tokenUsage": {
    "promptTokens": 0,
    "completionTokens": 0,
    "totalTokens": 0
  },
  "cost": {
    "amount": 0,
    "currency": "string"
  }
}

text/json

Schema

Schema

instanceId uuid

files

object[]

nullable

Array [

index int32

source stringnullable

success boolean

result

object

model stringnullable

provider stringnullable

pages

object[]

nullable

Array [

index int32required

markdown stringnullablerequired

images

object[]

nullable

Array [

id stringnullablerequired

base64 stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

tables

object[]

nullable

Array [

content stringnullablerequired

format int32

Possible values: [0, 1]

The table content format. 0 = Html, 1 = Markdown.

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

hyperlinks

object[]

nullable

Array [

url stringnullablerequired

text stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

header stringnullable

footer stringnullable

dimensions

object

width int32

height int32

dpi int32nullable

confidence

object

averagePageScore doublenullable

minimumPageScore doublenullable

wordScores

object[]

nullable

Array [

word stringnullable

score double

]

blocks

object[]

nullable

Array [

label stringnullable

boundingBox

object

Bounding box in coordinates normalised 0-1 relative to the page.

x double

y double

width double

height double

]

]

usage

object

inputTokenCount int64nullable

outputTokenCount int64nullable

totalTokenCount int64nullable

cachedInputTokenCount int64nullable

reasoningTokenCount int64nullable

additionalCounts

object

nullable

property name* int64

markdown stringnullable

error stringnullable

]

tokenUsage

object

promptTokens int32

completionTokens int32

totalTokens int32

cost

object

amount double

currency stringnullable

Example (from schema)

{
  "instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "files": [
    {
      "index": 0,
      "source": "string",
      "success": true,
      "result": {
        "model": "string",
        "provider": "string",
        "pages": [
          {
            "index": 0,
            "markdown": "string",
            "images": [
              {
                "id": "string",
                "base64": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "tables": [
              {
                "content": "string",
                "format": 0,
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "hyperlinks": [
              {
                "url": "string",
                "text": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ],
            "header": "string",
            "footer": "string",
            "dimensions": {
              "width": 0,
              "height": 0,
              "dpi": 0
            },
            "confidence": {
              "averagePageScore": 0,
              "minimumPageScore": 0,
              "wordScores": [
                {
                  "word": "string",
                  "score": 0
                }
              ]
            },
            "blocks": [
              {
                "label": "string",
                "boundingBox": {
                  "x": 0,
                  "y": 0,
                  "width": 0,
                  "height": 0
                }
              }
            ]
          }
        ],
        "usage": {
          "inputTokenCount": 0,
          "outputTokenCount": 0,
          "totalTokenCount": 0,
          "cachedInputTokenCount": 0,
          "reasoningTokenCount": 0,
          "additionalCounts": {}
        },
        "markdown": "string"
      },
      "error": "string"
    }
  ],
  "tokenUsage": {
    "promptTokens": 0,
    "completionTokens": 0,
    "totalTokens": 0
  },
  "cost": {
    "amount": 0,
    "currency": "string"
  }
}

400

If the request validation fails (no files, unsupported format).

application/json

Schema

Schema

message stringnullable

errors

object

nullable

property name* string

Example (from schema)

{
  "message": "string",
  "errors": {}
}

401

The user is unauthorized or the session expired

403

The user does not have permission

404

If the specified model or a file is not found, or the model does not support OCR.

500

There was an unexpected error

Loading...