Quickstart - TextIn Intelligent Document Parsing

Use the Document Crop & Enhance API to turn document photos and scans into clean, corrected images before OCR, parsing, archiving, printing, or display. With a single request, the API can automatically detect document edges, crop away the surrounding background, correct perspective and orientation, and apply optional image enhancements.

What it does

Auto crop documents

Automatically detect the document boundary and crop away the surrounding background.The response also returns the four corner points of the detected document region, which can be used for downstream processing or visualization.Typical inputs include documents photographed on desks, receipts captured with extra background, and pages taken from imperfect distances or angles.

Correct perspective and orientation

Straighten document photos captured at an angle and correct geometric distortion so the page appears flat and rectangular.You can also enable orientation correction for sideways or incorrectly rotated document images.

Enhance document images

Apply optional image enhancements based on the source image and desired output.Available processing options include:

Deblur
Brighten
Sharpen
Black and white
Grayscale
Shadow removal
Bitmap

These options can help improve readability and produce cleaner images for OCR, archiving, printing, or display.

Common use cases

The Document Crop & Enhance API can be used to prepare:

smartphone photos for OCR and text recognition;
receipts, forms, contracts, and other paper documents for digital archiving;
photographed pages for printing or copying;
cleaner document images for sharing or display;
document images before downstream parsing or data extraction.

Typical processing flow

A single request can combine the processing steps you need: Document photo → Auto crop → Perspective correction → Orientation correction → Enhance → Clean document image Each processing option can be enabled or disabled independently.

Before you start

You need:

Your TextIn App ID and Secret Code. Find them in the TextIn console under API Keys, and send them in the x-ti-app-id and x-ti-secret-code request headers.
A document image (jpg, png, bmp, webp, pdf, tiff, or single-frame gif).

For PDF input, only the first page is processed. Multi-page PDFs are accepted, but only the first page is cropped, corrected, and enhanced.

Set your credentials

export TEXTIN_APP_ID="your-app-id"
export TEXTIN_SECRET_CODE="your-secret-code"

On Windows PowerShell:

$env:TEXTIN_APP_ID="your-app-id"
$env:TEXTIN_SECRET_CODE="your-secret-code"

Send a request

The endpoint accepts input in one of two ways. Send the raw file bytes with Content-Type: application/octet-stream, or send a file URL as plain text with Content-Type: text/plain.

The API always responds with HTTP 200. Check the code field in the response body to determine success (200) or failure.

cURL
Python
Node.js

# Option 1: upload a local file (binary stream)
curl --location --request POST "https://api.textin.ai/ai/service/v1/crop_enhance_image" \
  --header "x-ti-app-id: $TEXTIN_APP_ID" \
  --header "x-ti-secret-code: $TEXTIN_SECRET_CODE" \
  --header "Content-Type: application/octet-stream" \
  --data-binary "@/path/to/example.jpg"

# Option 2: pass a file URL (plain text)
curl --location --request POST "https://api.textin.ai/ai/service/v1/crop_enhance_image" \
  --header "x-ti-app-id: $TEXTIN_APP_ID" \
  --header "x-ti-secret-code: $TEXTIN_SECRET_CODE" \
  --header "Content-Type: text/plain" \
  --data-raw "https://example.com/example.jpg"

# Option 3: enable enhancements with query parameters
curl --location --request POST "https://api.textin.ai/ai/service/v1/crop_enhance_image?correct_direction=1&enhance_mode=5" \
  --header "x-ti-app-id: $TEXTIN_APP_ID" \
  --header "x-ti-secret-code: $TEXTIN_SECRET_CODE" \
  --header "Content-Type: application/octet-stream" \
  --data-binary "@/path/to/example.jpg"

import os
import requests

def get_file_content(file_path):
    with open(file_path, "rb") as fp:
        return fp.read()

class CropEnhanceClient:
    def __init__(self, img_path=None, is_url=False, params=None):
        self._url = "https://api.textin.ai/ai/service/v1/crop_enhance_image"
        self._app_id = os.environ["TEXTIN_APP_ID"]
        self._secret_code = os.environ["TEXTIN_SECRET_CODE"]
        self._img_path = img_path
        self._is_url = is_url
        # Processing options, sent as query parameters. See the Configuration page.
        self._params = params or {}

    def process(self):
        headers = {
            "x-ti-app-id": self._app_id,
            "x-ti-secret-code": self._secret_code,
        }
        if self._is_url:
            headers["Content-Type"] = "text/plain"
            body = self._img_path
        else:
            headers["Content-Type"] = "application/octet-stream"
            body = get_file_content(self._img_path)
        resp = requests.post(self._url, params=self._params, data=body, headers=headers, timeout=60)
        resp.raise_for_status()
        result = resp.json()
        # The API always responds with HTTP 200. Check the `code` field to detect errors.
        if result.get("code") != 200:
            raise RuntimeError(f"API error {result.get('code')}: {result.get('message')}")
        return result

if __name__ == "__main__":
    # Option 1: upload a local file (default crop + dewarp)
    print(CropEnhanceClient(img_path="example.jpg").process())
    # Option 2: pass a file URL
    print(CropEnhanceClient(img_path="https://example.com/example.jpg", is_url=True).process())
    # Option 3: enable orientation correction and shadow-removal enhancement
    print(CropEnhanceClient(
        img_path="example.jpg",
        params={"correct_direction": 1, "enhance_mode": 5},
    ).process())

// Requires Node.js 18+, which includes the Fetch API by default.
const fs = require("fs");

const appId = process.env.TEXTIN_APP_ID;
const secretCode = process.env.TEXTIN_SECRET_CODE;
const url = "https://api.textin.ai/ai/service/v1/crop_enhance_image";

async function cropEnhance(input, isUrl = false, params = {}) {
  const contentType = isUrl ? "text/plain" : "application/octet-stream";
  const body = isUrl ? input : fs.readFileSync(input);
  // Processing options, sent as query parameters. See the Configuration page.
  const query = new URLSearchParams(params).toString();
  const requestUrl = query ? `${url}?${query}` : url;

  const response = await fetch(requestUrl, {
    method: "POST",
    headers: {
      "x-ti-app-id": appId,
      "x-ti-secret-code": secretCode,
      "Content-Type": contentType,
    },
    body,
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
  const data = await response.json();
  // The API always responds with HTTP 200. Check the `code` field to detect errors.
  if (data.code !== 200) {
    throw new Error(`API error ${data.code}: ${data.message}`);
  }
  console.log(data);
}

// Option 1: upload a local file (default crop + dewarp)
cropEnhance("example.jpg", false);
// Option 2: pass a file URL
cropEnhance("https://example.com/example.jpg", true);
// Option 3: enable orientation correction and shadow-removal enhancement
cropEnhance("example.jpg", false, { correct_direction: 1, enhance_mode: 5 });

By default, the endpoint crops and dewarps the document. To control cropping, correction, and enhancement, pass query parameters such as ?correct_direction=1&enhance_mode=5. See Configuration for the full list.

Read the response

The response returns the processed image as a Base64-encoded JPG, plus dimensions and crop coordinates. The image value below is truncated for readability.

{
  "code": 200,
  "message": "success",
  "msg": "success",
  "version": "v2.0.8",
  "duration": 100,
  "x_request_id": "7596b8c9d2ddbc9924b66651e9efc174",
  "result": {
    "origin_width": 2000,
    "origin_height": 3000,
    "image_list": [
      {
        "cropped_width": 1500,
        "cropped_height": 1800,
        "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD",
        "position": [0, 10, 500, 10, 500, 300, 0, 300],
        "angle": 90
      }
    ]
  }
}

Parse the response and decode the image field to save the processed image:

import base64

result = CropEnhanceClient(img_path="example.jpg").process()
image_base64 = result["result"]["image_list"][0]["image"]

with open("output.jpg", "wb") as f:
    f.write(base64.b64decode(image_base64))

Next steps

Configuration

Control cropping, correction, and enhancement with query parameters.

API Reference

Every parameter, response field, and an interactive playground.

Supported Files & Limits

Supported formats, file size, and image dimensions.

Errors

Error codes and how to resolve them.

​What it does

Auto crop documents

Correct perspective and orientation

Enhance document images

​Common use cases

​Typical processing flow

​Before you start

​Set your credentials

​Send a request

​Read the response

​Next steps

Configuration

API Reference

Supported Files & Limits

Errors

What it does

Common use cases

Typical processing flow

Before you start

Set your credentials

Send a request

Read the response

Next steps