Skip to content

Recognise text ​

Turns an image of handwritten or printed text into a transcription with coordinates for every region, line and word.

What it does ​

Recognises the text on a single document image using a Transkribus model, returning the transcription together with the layout: regions, lines, baselines, coordinates and, where available, words.

It is an asynchronous job: submit, track, download. The shared contract (statuses, links, errors, retention) is on How jobs work; this page is the full reference for text recognition, each operation rendered from the API document with its schemas and a playground.

Choosing a model ​

Two families of model do this, and which you pick matters more than any parameter. See Model types for the full picture:

  • Super models are large general-purpose models that work across many hands, languages and centuries without any training. Use these when you have mixed or unfamiliar material, or no ground truth. They are the right default. Text Titan II is 579509.
  • PyLaia models are small, fast and trained on a specific hand, collection or script: considerably cheaper at volume, and a well-trained one beats a general model on its own material. 38230 is German_Kurrent_XIX-XX_M6-2.

Both are addressed the same way, by model ID (htrId). See Models for how to find one.

Submit a job ​

config.textRecognition.htrId and image are required. The image is JPEG, PNG or TIFF, up to 20 MB, one per job, as a base64 string or a public URL; it is used for that job only and is not stored, see Images. config.lineDetection is optional and selects a layout model; the field name is historical. content is optional pre-existing layout to recognise within. An id you set on a region, line or word is kept and returned.

Submit a text recognition job for a single image (base64 or URL) ​

POSThttps://api-staging.transkribus.org/v2/processes

Request Body​

application/json

Request data for a single-image processing job

Specifies how the submitted image shall be processed

Optional preliminary layout information

The image to process: either the base64-encoded binary data or a reference to a publicly available image

Max Properties1

Responses​

The request was accepted

application/json

Response shape for a processing job

The integer ID of the job

Format"int32"

The status of the job

Valid values"CREATED""WAITING""RUNNING""FINISHED""FAILED""CANCELLED"

Optional preliminary layout information

HATEOAS navigation links. Use rel, not title, as the stable machine-readable identifier.

Try it out

Playground​

Authorization
Body

Samples​

Track the job ​

Either poll the status on an interval, every few seconds is sensible, or longpoll: the request waits until the status changes and answers 408 when the window expires, in which case you repeat it. The longpoll link is present only while the job is not terminal; its absence is the signal to stop. Use rel, not title, to find links.

Get the status of a job, identified by its processId ​

GEThttps://api-staging.transkribus.org/v2/processes/{processId}

Parameters​

Path Parameters

processId*

The UUID (v7) or integer processId of the job

Type
string
Required

Responses​

The request was accepted

application/json

Response shape for a processing job

The integer ID of the job

Format"int32"

The status of the job

Valid values"CREATED""WAITING""RUNNING""FINISHED""FAILED""CANCELLED"

Optional preliminary layout information

HATEOAS navigation links. Use rel, not title, as the stable machine-readable identifier.

Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

Long-poll for job status ​

GEThttps://api-staging.transkribus.org/v2/processes/longpoll/{processId}

Waits until the job status changes to a terminal state (FINISHED, FAILED, CANCELLED) or until the polling timeout expires. Returns the same response shape as GET /v2/processes/{processId}. Prefer this over repeated polling for efficient status tracking.

Parameters​

Path Parameters

processId*

The UUID (v7) or integer processId of the job

Type
string
Required

Query Parameters

interval

Polling interval in milliseconds

Type
integer
Format
"int32"

Responses​

The job reached a terminal status within the polling window

application/json

Response shape for a processing job

The integer ID of the job

Format"int32"

The status of the job

Valid values"CREATED""WAITING""RUNNING""FINISHED""FAILED""CANCELLED"

Optional preliminary layout information

HATEOAS navigation links. Use rel, not title, as the stable machine-readable identifier.

Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

Read the result ​

A finished job offers its result in three forms, retained for 24 hours after completion: inline in the content field of the status response (the text, and regions with coords.points as the bounding polygon, each with lines with coords, baseline and text, and words where the model provides them), as a ZIP archive, and as PAGE XML or ALTO XML.

Download result archive for a job ​

GEThttps://api-staging.transkribus.org/v2/processes/{processId}/result

Downloads a ZIP archive containing the result files for a finished job.

Parameters​

Path Parameters

processId*

The UUID (v7) or integer processId of the job

Type
string
Required

Responses​

The result archive for the process

application/zip
Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

Get the job result as PAGE XML ​

GEThttps://api-staging.transkribus.org/v2/processes/{processId}/page

Retrieves the result of a job, identified by its processId, as PAGE XML (PRImA 2013-07-15 schema).

Parameters​

Path Parameters

processId*

The UUID (v7) or integer processId of the job

Type
string
Required

Responses​

The result as PAGE XML

application/xml
Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

Get the job result as ALTO XML ​

GEThttps://api-staging.transkribus.org/v2/processes/{processId}/alto

Retrieves the result of a job, identified by its processId, as ALTO XML.

Parameters​

Path Parameters

processId*

The UUID (v7) or integer processId of the job

Type
string
Required

Responses​

The result as ALTO XML

application/xml
Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

Errors ​

Errors are JSON with statusCode, reasonPhrase and message. 400 malformed body, 401 missing or expired token, 404 unknown processId or model, or result not yet available, 408 longpoll window expired, 429 processing volume depleted or account limit reached. See Errors.

Cost ​

Credits at 50% of the rate of the same job in the Transkribus platform. See Credits and cost.

Limits ​

See Limits: 20 MB per image, one image per job, results retained 24 hours.

Transkribus Developer Platform