General OCR Markdown

Convert an image or PDF into Markdown using a vision-language model, with OCR grounding returned alongside the result for each page.

Extract Markdown and OCR grounding from an image or PDF, returned as a single Markdown string per page.

Extract Markdown from a document

POST https://api.aigen.online/aiscript/general-ocr-md/v1

Request Body

Name	Type	Description
image*	string	Base64-encoded image or PDF (without a data: URL prefix). Supports multi-page PDF.
grounding_text	string | string[] | object	Caller-provided OCR grounding, to be used instead of automatic OCR.
text	string | string[] | object	Alias for grounding_text.
grounding	string | string[] | object	Alias for grounding_text.
use_artata_grounding	boolean	Set to false to run the VLM without automatic OCR grounding.

Normally, consumers only need to send image. The service performs OCR grounding automatically and returns it together with the Markdown result.

Response Schema

Top-level response

Key	Type	Description
status	string	HTTP-style status code as a string, e.g. "200".
response_id	string	Echoes the caller's x-aigen-request-id, or a generated ID.
error	list[ErrorObject]	List of errors. Empty on success.
data	list[PageResult]	One item per page.

PageResult schema

Key	Type	Description
markdown	string	Markdown content for the page.
page_number	int	One-based page number.
grounding	GroundingObject | null	OCR grounding used as a reference by the VLM. null when automatic grounding is disabled or unavailable.

GroundingObject schema

Key	Type	Description
bboxes	list[BboxObject]	Detected text regions.
text_page	string	Combined OCR text for the page.
page	int	One-based page number.
max_page	int	Total number of pages.

BboxObject schema

Key	Type	Description
bbox	number[][]	Four pixel-coordinate corner points.
bbox_norm	number[][]	Four normalized corner points in the range 0–1.
char_pos_norm	number[]	Normalized character positions within the text region.
text	string	OCR text detected in the region.
confidence	number	OCR confidence score.

200: OK Successful Response

{
  "status": "200",
  "response_id": "request-001",
  "error": [],
  "data": [
    {
      "markdown": "# Document title\n\nDocument content",
      "page_number": 1,
      "grounding": {
        "bboxes": [
          {
            "bbox": [
              [20, 25],
              [464, 25],
              [464, 84],
              [20, 84]
            ],
            "bbox_norm": [
              [0.0278, 0.0546],
              [0.6453, 0.0546],
              [0.6453, 0.1834],
              [0.0278, 0.1834]
            ],
            "char_pos_norm": [0.0, 0.0331, 0.0496],
            "text": "Document title",
            "confidence": 0.9953
          }
        ],
        "text_page": "Document title\nDocument content",
        "page": 1,
        "max_page": 1
      }
    }
  ]
}

500: Internal or upstream service error

{
  "status": "500",
  "response_id": "request-001",
  "error": [
    {
      "object": "error",
      "code": "INTERNAL_ERROR",
      "message": "Error details"
    }
  ],
  "data": []
}

422: Unprocessable Entity Validation error

{
  "detail": [
    {
      "loc": ["string"],
      "msg": "string",
      "type": "string"
    }
  ]
}

Multi-page PDF response

For a PDF, data contains one item per page. Results are associated using page_number and grounding.page.

{
  "status": "200",
  "response_id": "request-002",
  "error": [],
  "data": [
    {
      "markdown": "Markdown for page 1",
      "page_number": 1,
      "grounding": {
        "bboxes": [],
        "text_page": "OCR text for page 1",
        "page": 1,
        "max_page": 2
      }
    },
    {
      "markdown": "Markdown for page 2",
      "page_number": 2,
      "grounding": {
        "bboxes": [],
        "text_page": "OCR text for page 2",
        "page": 2,
        "max_page": 2
      }
    }
  ]
}

Caller-provided grounding

Consumers may supply their own OCR grounding instead of relying on automatic OCR.

One page

{
  "image": "base64-encoded image",
  "grounding_text": "Caller-provided OCR text"
}

Multiple pages as a list

{
  "image": "base64-encoded PDF",
  "grounding_text": ["Text for page 1", "Text for page 2"]
}

Multiple pages as an object

{
  "image": "base64-encoded PDF",
  "grounding_text": {
    "1": "Text for page 1",
    "2": "Text for page 2"
  }
}

When caller-provided grounding is used, the response contains that text in grounding.text_page. The grounding.bboxes array is empty because the caller did not provide localization data.

Example code

Python

import requests

api = "https://api.aigen.online/aiscript/general-ocr-md/v1"
headers = {"x-aigen-key": "<key>"}
data = {"image": "<base64_string>"}

res = requests.post(api, json=data, headers=headers)
print(res.json())

Nodejs

const axios = require("axios");

const api = "https://api.aigen.online/aiscript/general-ocr-md/v1";
const headers = {
  "x-aigen-key": "<key>",
};
const data = { image: "<base64_string>" };

axios
  .post(api, data, { headers: headers })
  .then((res) => {
    console.log(res.data);
  })
  .catch((err) => {
    console.error(err.response.data);
  });

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.aigen.online/aiscript/general-ocr-md/v1',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
    "image" => "<base64_string>"
  )),
  CURLOPT_HTTPHEADER => array(
    'X-AIGEN-KEY: <aigen-key>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
?>

cURL

curl --location 'https://api.aigen.online/aiscript/general-ocr-md/v1' \
--header 'X-AIGEN-KEY: <aigen-key>' \
--header 'Content-Type: application/json' \
--data '{
    "image": "<base64_string>"
}'