Skip to content

Your first job ​

Three requests: submit an image, poll the job, download the result. Get an access token first, see Authentication. All examples call https://api-staging.transkribus.org, the host this documentation is built for.

1. Submit an image ​

Send the image (base64 or URL) with the ID of the text recognition model to apply. 38230 is German_Kurrent_XIX-XX_M6-2, a public PyLaia model for German Kurrent handwriting of the 19th and 20th century; for mixed or unfamiliar material use the super model Text Titan II, id 579509. How to pick one is on Models.

bash
curl -X POST https://api-staging.transkribus.org/v2/processes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "config": { "textRecognition": { "htrId": 38230 } },
    "image": { "imageUrl": "https://example.org/scan.jpg" }
  }'
python
import requests

API = "https://api-staging.transkribus.org"
headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

job = requests.post(f"{API}/v2/processes", headers=headers, json={
    "config": {"textRecognition": {"htrId": 38230}},
    "image": {"imageUrl": "https://example.org/scan.jpg"},
}).json()
process_id = job["processId"]
js
const API = "https://api-staging.transkribus.org";
const headers = { Authorization: `Bearer ${ACCESS_TOKEN}` };

let job = await fetch(`${API}/v2/processes`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    config: { textRecognition: { htrId: 38230 } },
    image: { imageUrl: "https://example.org/scan.jpg" },
  }),
}).then((r) => r.json());
const processId = job.processId;

The response is the job, in status CREATED, with its processId and the links to follow:

json
{
  "processId": 47725,
  "status": "CREATED",
  "links": [
    { "rel": "status", "href": "https://api-staging.transkribus.org/v2/processes/47725", "title": "Status" },
    { "rel": "longpoll", "href": "https://api-staging.transkribus.org/v2/processes/longpoll/47725", "title": "Status Longpoll" }
  ]
}

2. Poll the job ​

$PROCESS_ID is the processId from the response above. Poll until the status is FINISHED, FAILED or CANCELLED; every few seconds is a sensible interval, the samples use five. See How jobs work for all statuses and the longpoll alternative, which waits for the change instead.

bash
curl https://api-staging.transkribus.org/v2/processes/$PROCESS_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"
python
import time

while job["status"] not in ("FINISHED", "FAILED", "CANCELLED"):
    time.sleep(5)
    job = requests.get(f"{API}/v2/processes/{process_id}", headers=headers).json()
js
while (!["FINISHED", "FAILED", "CANCELLED"].includes(job.status)) {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  job = await fetch(`${API}/v2/processes/${processId}`, { headers }).then((r) => r.json());
}

3. Download the result ​

A finished job carries its text and layout inline in content:

json
{
  "processId": 47725,
  "status": "FINISHED",
  "content": {
    "text": "Eisenschrott",
    "regions": [
      {
        "id": "region_1",
        "coords": { "points": "0,0 282,0 280,109 0,108" },
        "lines": [
          { "id": "line_1", "coords": { "points": "0,109 55,89 ... 1,8" }, "baseline": { "points": "6,64 276,65" }, "text": "Eisenschrott" }
        ]
      }
    ]
  },
  "links": [
    { "rel": "self", "href": "https://api-staging.transkribus.org/v2/processes/47725", "title": "Status" },
    { "rel": "result", "href": "https://api-staging.transkribus.org/v2/processes/47725/result", "title": "Multiple Pages Result" }
  ]
}

Follow the result link for a ZIP archive, or call the page or alto endpoint for PAGE XML or ALTO XML. Results are retained for 24 hours after completion. What every field means is on Recognise text.

bash
curl -o result.zip https://api-staging.transkribus.org/v2/processes/$PROCESS_ID/result \
  -H "Authorization: Bearer $ACCESS_TOKEN"
python
print(job["content"]["text"])

archive = requests.get(f"{API}/v2/processes/{process_id}/result", headers=headers)
open("result.zip", "wb").write(archive.content)
js
console.log(job.content.text);

const archive = await fetch(`${API}/v2/processes/${processId}/result`, { headers });
const bytes = new Uint8Array(await archive.arrayBuffer());

Transkribus Developer Platform