Appearance
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.
38230isGerman_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)
POST
https://api-staging.transkribus.org/v2/processesRequest 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 Properties
1Responses
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.
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
GET
https://api-staging.transkribus.org/v2/processes/{processId}Parameters
Path Parameters
processId*
The UUID (v7) or integer processId of the job
Type
Requiredstring
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.
Long-poll for job status
GET
https://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
Requiredstring
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.
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
GET
https://api-staging.transkribus.org/v2/processes/{processId}/resultGet the job result as PAGE XML
GET
https://api-staging.transkribus.org/v2/processes/{processId}/pageGet the job result as ALTO XML
GET
https://api-staging.transkribus.org/v2/processes/{processId}/altoErrors
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.