Baseer OCR
Advanced Arabic OCR — extract structured text from images and PDFs.
Overview
Baseer (بصير) is a vision-to-text model built for Arabic documents. It goes beyond character recognition by understanding document structure, rendering tables as clean HTML, and preserving the semantic layout of classical Arabic texts.
The OCR API is asynchronous — you upload a file, poll for status, and retrieve results when processing completes. This enables handling of large PDFs and complex documents without request timeouts.
Workflow
Upload a file
Submit your image or PDF to POST /v1/ocr. You'll receive a fileId and a Location header pointing to the status endpoint.
Poll for status
Use GET /v1/ocr/{fileId}/status to check whether processing is pending, processing, completed, or failed.
Retrieve results
Once the status is completed, fetch the extracted content from GET /v1/ocr/{fileId}/results. Results can only be consumed once — they are deleted after retrieval.
Endpoints
Upload File
POST /v1/ocrAccepts a file upload and begins asynchronous OCR processing. Returns 202 Accepted with a fileId and a Location header.
Requires an API Key passed via the x-api-key header.
Request
The request must be sent as multipart/form-data.
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | Image (jpg, png, tiff) or PDF file. Images up to 5 MB, PDFs up to 50 MB. |
model | string | Yes | The OCR model to use. See Models. |
options | object | No | Fine-tuning parameters for inference. See Options. |
Response
Status: 202 Accepted
Headers:
Location: /v1/ocr/{fileId}/status
{
"fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}| Field | Type | Description |
|---|---|---|
fileId | string | Unique identifier for the uploaded file. Use this to check status and retrieve results. |
Example
curl -X POST https://api-dev.kawn.io/v1/ocr \
-H "x-api-key: <YOUR_API_KEY>" \
-F "model=baseer/baseer-v2" \
-F "file=@/path/to/document.pdf"Check Status
GET /v1/ocr/{fileId}/statusReturns the current processing status of a previously uploaded file.
Requires an API Key passed via the x-api-key header.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fileId | string | Yes | The file ID returned from the upload endpoint. |
Response
{
"fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed"
}| Field | Type | Description |
|---|---|---|
fileId | string | The file identifier. |
status | string | One of: pending, processing, completed, failed. |
Status Values
| Status | Description |
|---|---|
pending | File has been received and is queued for processing. |
processing | The OCR model is actively extracting text from the file. |
completed | Processing finished successfully. Results are ready to be retrieved. |
failed | Processing failed. The file could not be processed. |
Example
curl https://api-dev.kawn.io/v1/ocr/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
-H "x-api-key: <YOUR_API_KEY>"Retrieve Results
GET /v1/ocr/{fileId}/resultsReturns the extracted content for a completed file. Results can only be retrieved once — the data is deleted immediately after a successful response.
Requires an API Key passed via the x-api-key header.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fileId | string | Yes | The file ID returned from the upload endpoint. |
Response
{
"fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"model": "baseer/baseer-v2",
"pages": [
{
"index": 0,
"content": "<p>بسم الله الرحمن الرحيم</p>"
},
{
"index": 1,
"content": "<p>الحمد لله رب العالمين</p>"
}
],
"creditsConsumed": 2
}| Field | Type | Description |
|---|---|---|
fileId | string | The file identifier. |
model | string | The model that processed the request. |
pages | array | Ordered list of page results. Each page has an index and its extracted content (HTML). |
creditsConsumed | number | Number of credits deducted for this request. |
Results are consumed on retrieval. If you need to keep the extracted content, make sure to persist it on your end after fetching.
Example
curl https://api-dev.kawn.io/v1/ocr/a1b2c3d4-e5f6-7890-abcd-ef1234567890/results \
-H "x-api-key: <YOUR_API_KEY>"Full Example
Here's a complete example using curl and jq to upload a file, poll until completion, and retrieve results:
# 1. Upload the file
FILE_ID=$(curl -s -X POST https://api-dev.kawn.io/v1/ocr \
-H "x-api-key: <YOUR_API_KEY>" \
-F "model=baseer/baseer-v2" \
-F "file=@/path/to/document.pdf" | jq -r '.fileId')
echo "File ID: $FILE_ID"
# 2. Poll for status until completed
while true; do
STATUS=$(curl -s https://api-dev.kawn.io/v1/ocr/$FILE_ID/status \
-H "x-api-key: <YOUR_API_KEY>" | jq -r '.status')
echo "Status: $STATUS"
if [ "$STATUS" = "completed" ]; then
break
elif [ "$STATUS" = "failed" ]; then
echo "Processing failed"
exit 1
fi
sleep 2
done
# 3. Retrieve results (one-time consumption)
curl -s https://api-dev.kawn.io/v1/ocr/$FILE_ID/results \
-H "x-api-key: <YOUR_API_KEY>" | jq .Models
| Model ID | Description |
|---|---|
baseer/baseer-v2 | Default production model. |
Options
| Field | Type | Description |
|---|---|---|
topP | number | Nucleus sampling threshold. |
topK | number | Top-K sampling parameter. |
temperature | number | Controls randomness of output. Higher values produce more varied results. |
How It Works
The Baseer processor runs a quality-assured pipeline before returning results:
- Preprocessing — Images are compressed and normalized for optimal inference accuracy.
- Inference — The file is passed to the Baseer model.
- Validation — Output is checked by validators (e.g. repetition detection, hallucination checks, Quranic ayah validation).
- Retry Logic — If validation fails, the system automatically retries with adjusted parameters (higher temperature or repetition penalty) before surfacing an error.