SnapOtter/apps/docs/id/tools/image/ocr.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
Ekstrak teks dari gambar secara lokal dengan Tesseract bawaan atau runtime RapidOCR opsional dengan akurasi tinggi.	18a92d67d692	0d453b49db02	human

OCR / Text Extraction

Ekstrak teks dari gambar tanpa mengirim gambar ke layanan eksternal. Tingkat fast bawaan menggunakan Tesseract. Tingkat opsional balanced dan best menggunakan RapidOCR dengan model PP-OCR ONNX yang disematkan.

::: info Kompatibilitas OCR bahasa Korea OCR Cepat mendukung auto, en, de, es, fr, zh, dan ja, tetapi tidak mendukung bahasa Korea (ko). Bahasa Korea memerlukan paket OCR Akurat dan balanced atau best. Paket berjalan pada kontainer resmi Linux amd64 dan arm64, termasuk host NVIDIA dengan OCR tetap memakai CPU. Sistem yang tidak didukung menerima kesalahan kompatibilitas yang jelas dan tidak pernah diam-diam kembali ke fast. Bahasa Korea dengan fast atau alias lama tesseract ditolak sebelum antre dengan FEATURE_INCOMPATIBLE dan fast-korean-unsupported. :::

API Endpoint

POST /api/v1/tools/image/ocr

Pemrosesan: OCR selalu berjalan secara asinkron. Setelah validasi dan pengantrean, endpoint segera mengembalikan 202 Accepted dengan jobId. Ikuti aliran kemajuan SSE pekerjaan hingga peristiwa terminal complete atau failed; result dari peristiwa yang berhasil berisi bidang OCR.

Paket OCR yang akurat: Waktu proses ocr opsional (sekitar 208-234 MiB untuk diunduh dan 409-488 MiB diinstal, bergantung pada target). fast tidak memerlukan paket ini; penginstal memverifikasi ukuran pasti yang terikat oleh indeks yang ditandatangani.

Parameters

Parameter	Type	Required	Default	Description
file	file	Ya	-	File gambar (multibagian), hingga 512 MiB dikodekan dan 40 megapiksel dikodekan; batas unggah operator yang lebih rendah masih berlaku
quality	string	TIDAK	Dinamis	Tingkat kualitas: fast (Tesseract), balanced (RapidOCR dengan model PP-OCRv6 kecil), atau best (model PP-OCRv6 medium dengan akurasi lebih tinggi dengan penilaian varian yang dikalibrasi)
language	string	No	"auto"	Petunjuk bahasa: auto, en, de, fr, es, zh, ja, ko
enhance	boolean	TIDAK	Bergantung pada tingkatan	Tingkatkan kontras lokal sebelum pengenalan. Fast menerapkannya secara langsung; Seimbang dan Terbaik mempertahankan varian hanya jika penilaian yang dikalibrasi meningkatkan hasilnya. Defaultnya adalah true untuk best dan false untuk fast/balanced
engine	string	TIDAK	-	Alias ​​​​kompatibilitas yang tidak digunakan lagi. Gunakan quality sebagai gantinya. tesseract dipetakan ke fast; nilai paddleocr lama dipetakan ke balanced tetapi tidak memuat PaddlePaddle

Jika quality dan engine tidak diberikan, SnapOtter memilih tingkat terbaik yang tersedia dengan urutan best, balanced, lalu fast. Untuk bahasa Korea, fast tidak pernah dipilih; sistem memakai best, lalu balanced, atau mengembalikan kesalahan instalasi maupun kompatibilitas runtime akurat.

Example Request

curl -X POST http://localhost:1349/api/v1/tools/image/ocr \
  -F "file=@document.png" \
  -F 'settings={"quality":"best","language":"en","enhance":true}'

Respons diterima (202)

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "async": true
}

Kemajuan dan hasil (SSE)

Hubungkan ke GET /api/v1/jobs/{jobId}/progress dengan jobId yang dikembalikan oleh respons 202 (atau clientJobId yang diberikan). Biarkan aliran tetap terbuka hingga peristiwa terminal complete atau failed. Frame terminal yang berhasil memuat keluaran OCR di result:

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "single",
  "phase": "complete",
  "stage": "complete",
  "percent": 100,
  "result": {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/document_ocr.txt",
    "originalSize": 12345,
    "processedSize": 47,
    "text": "Extracted text content from the image...",
    "engine": "rapidocr-onnx",
    "requestedQuality": "best",
    "actualQuality": "best",
    "device": "cpu",
    "provider": "CPUExecutionProvider",
    "degraded": false,
    "warnings": [],
    "runtimeVersion": "2.2.0",
    "modelVersion": "PP-OCRv6-best-v1-medium"
  }
}

Kegagalan pemrosesan dikirim melalui bidang error pada peristiwa terminal failed; kegagalan tersebut tidak dikembalikan sebagai HTTP 422 setelah pengantrean.

Notes

• fast selalu tersedia dalam gambar SnapOtter yang didukung. balanced dan best memerlukan paket OCR opsional yang akurat.
• Tesseract bawaan menambahkan sekitar 25 MiB ke gambar resmi. Paket akurat disimpan di /data/ai, bukan dimasukkan ke dalam gambar.
• Paket akurat diterbitkan untuk wadah resmi Linux amd64 dan arm64. Sengaja menggunakan penyedia ONNX Runtime CPU, termasuk pada host NVIDIA, sehingga tidak bergantung pada pustaka CUDA atau kompatibilitas GPU. Penginstalan bare-metal sumber dan bawaan menggunakan Fast OCR kecuali mereka menyediakan runtime yang kompatibel.
• result terminal yang berhasil memuat teks yang diekstraksi di text dan artefak .txt yang dapat diunduh di downloadUrl.
• SnapOtter menghormati tingkatan yang diminta secara eksplisit. Jika balanced atau best tidak tersedia, API mengembalikan 501 dengan FEATURE_NOT_INSTALLED atau FEATURE_INCOMPATIBLE; itu tidak pernah secara diam-diam menurunkan versi permintaan ke tingkat lain.
• Hasil kosong yang berhasil tetap merupakan hasil kosong. Kegagalan waktu proses menghasilkan kesalahan alih-alih mencoba ulang dengan mesin berkualitas rendah.
• result terminal yang berhasil melaporkan requestedQuality dan actualQuality, ditambah mesin, perangkat, penyedia, waktu proses dan versi model, serta peringatan apa pun.
• Mendukung format input HEIC/HEIF, RAW, TGA, PSD, EXR, dan HDR via dekode otomatis.
• Input berkode berukuran besar mengembalikan 413. Gambar di atas 40 megapiksel dan respons OCR yang melampaui batas keluarannya akan ditolak dan bukan diproses sebagian.