myocr.app API दस्तावेज़

अवलोकन

myocr.app API दस्तावेज़ फ़ाइलों (PDF, JPG, PNG, WEBP, GIF, BMP, TIFF) को संरचित Excel, CSV, टेक्स्ट या JSON में बदलता है। आप एक फ़ाइल और मॉडल नाम भेजते हैं; हम OCR और लेआउट विश्लेषण चलाते हैं और साफ़ परिणाम लौटाते हैं।

हर रिक्वेस्ट X-API-Key हेडर में दी गई API key से ऑथेंटिकेट होती है। रिस्पॉन्स एक पूर्वानुमेय JSON envelope का उपयोग करते हैं और हर कॉल एक request_id लौटाती है जो सपोर्ट और डिबगिंग में उपयोगी है।

तुरंत चाहिए ऐसी छोटी फ़ाइलों के लिए सिंक्रोनस एंडपॉइंट और बड़ी फ़ाइलों या अधिक वॉल्यूम के लिए एसिंक्रोनस jobs एंडपॉइंट (वैकल्पिक वेबहुक के साथ) का उपयोग करें।

ऑथेंटिकेशन

हर रिक्वेस्ट को X-API-Key हेडर से ऑथेंटिकेट करें। /account/api पर डैशबोर्ड से keys बनाएं और प्रबंधित करें। live key जारी करने के लिए एक सत्यापित भुगतान कार्ड आवश्यक है (दुरुपयोग रोकने हेतु)। अभी कार्ड नहीं है? उसी डैशबोर्ड से मुफ़्त टेस्ट कुंजी बनाएं: कुल 5 पेज, 5 अनुरोध/मिनट, केवल POST /v1/convert — पूर्ण वास्तविक परिणाम, पहली इंटीग्रेशन के लिए आदर्श।

दो प्रकार की keys हैं: test keys (प्रिफ़िक्स sk_test_) उसी पाइपलाइन पर चलती हैं और जहाँ लागू हो वहाँ भुगतान कोटा खर्च नहीं करतीं, और live keys (प्रिफ़िक्स sk_live_) प्रोडक्शन के लिए। keys गोपनीय और सर्वर-साइड रखें — उन्हें कभी क्लाइंट कोड में न डालें।

Key प्रबंधन एंडपॉइंट (/v1/keys) आपकी लॉगिन वेब सेशन का उपयोग करते हैं, API key का नहीं।

curl https://api.myocr.app/v1/status \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx"

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_xxxxxxxxxxxx")
print(client.status())

const res = await fetch("https://api.myocr.app/v1/status", {
  headers: { "X-API-Key": "sk_live_xxxxxxxxxxxx" }
});
console.log(await res.json());

क्विकस्टार्ट

एक मिनट से कम में अपना पहला दस्तावेज़ बदलें। डैशबोर्ड से key लें, फिर अपनी फ़ाइल और इच्छित मॉडल के साथ एक multipart रिक्वेस्ट भेजें।

नीचे दिया उदाहरण तालिकाओं वाले किसी भी PDF या इमेज को .xlsx शीट में बदलकर out.xlsx में सहेजता है।

curl -X POST https://api.myocr.app/v1/convert \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@invoice.pdf" \
  -F "model=tables" \
  -o out.xlsx

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_xxxxxxxxxxxx")
result = client.convert("invoice.pdf", model="tables")
result.save("out.xlsx")

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("invoice.pdf")]), "invoice.pdf");
form.append("model", "tables");

const res = await fetch("https://api.myocr.app/v1/convert", {
  method: "POST",
  headers: { "X-API-Key": "sk_live_xxxxxxxxxxxx" },
  body: form,
});
fs.writeFileSync("out.xlsx", Buffer.from(await res.arrayBuffer()));

सिंक्रोनस रूपांतरण

POST /v1/convert एक फ़ाइल (अधिकतम 5 MB, अधिकतम 10 पेज) स्वीकार करता है और परिणाम फ़ाइल सीधे रिस्पॉन्स बॉडी में लौटाता है — डिफ़ॉल्ट रूप से .xlsx, या output पैरामीटर सेट करने पर टेक्स्ट/JSON/CSV।

जब आपको तुरंत उत्तर चाहिए तब यह सबसे अच्छा एंडपॉइंट है। बड़ी फ़ाइलों या बैच के लिए एसिंक्रोनस jobs का उपयोग करें।

पैरामीटर

एसिंक्रोनस जॉब

50 MB तक की फ़ाइलों (और PDF के लिए 500 पेज तक) या अधिक थ्रूपुट के लिए POST /v1/jobs से एक job बनाएं। कॉल तुरंत एक request_id लौटाती है; फ़ाइल बैकग्राउंड में प्रोसेस होती है। पेज कैप से ऊपर के PDF तुरंत TOO_MANY_PAGES के साथ अस्वीकृत होते हैं — दस्तावेज़ को विभाजित करें।

स्थिति के लिए GET /v1/jobs/{request_id} को पोल करें (pending → processing → done/failed), फिर GET /v1/jobs/{request_id}/result से परिणाम डाउनलोड करें। पोलिंग के बजाय स्वतः सूचना पाने के लिए webhook_url दें।

# 1. create the job
curl -X POST https://api.myocr.app/v1/jobs \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@statement.pdf" -F "model=bank_statement"
# → {"success": true, "data": {"request_id": "abcd1234"}}

# 2. poll status, then download the result
curl https://api.myocr.app/v1/jobs/abcd1234 -H "X-API-Key: sk_live_xxxxxxxxxxxx"
curl https://api.myocr.app/v1/jobs/abcd1234/result -H "X-API-Key: sk_live_xxxxxxxxxxxx" -o out.xlsx

job = client.create_job("statement.pdf", model="bank_statement")
job.wait()                     # polls with backoff until done
job.result().save("out.xlsx")

बैच रूपांतरण

POST /v1/batch एक ही multipart रिक्वेस्ट में 1–20 फ़ाइलें स्वीकार करता है, सभी एक ही मॉडल से प्रोसेस होती हैं। हर फ़ाइल अलग से रिपोर्ट होती है; प्रति-फ़ाइल विफलताएँ errors array में लौटती हैं और पूरा बैच विफल नहीं होता।

curl -X POST https://api.myocr.app/v1/batch \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "files=@a.pdf" -F "files=@b.pdf" -F "files=@c.jpg" \
  -F "model=invoice"

मॉडल

इनमें से एक model मान भेजें। tables और text हमारे OCR इंजन पर चलते हैं; विशेष मॉडल डोमेन-विशिष्ट फ़ील्ड लौटाते हैं।

मिश्रित PDF: बिल या चालान के बाद अक्सर विवरण संलग्नक होते हैं — कॉल लॉग, प्रति-लाइन सारांश, मदवार विवरण — जिनमें वही कॉलम हेडिंग दोहराई जाती हैं। page_range से हर मॉडल को केवल उसके काम के पेज दें।

चालान वाले पेज पर invoice (आमतौर पर पहला पेज) नंबर, तारीख़ें, कुल और VAT देता है; संलग्नक वाले पेजों पर tables पंक्ति-दर-पंक्ति विवरण देता है। दो कॉल, दो साफ़ फ़ाइलें, और छोड़े गए पेज बिल नहीं होते।

# invoice header from page 1, call detail from pages 3 onwards
curl -X POST https://api.myocr.app/v1/convert -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@bill.pdf" -F "model=invoice" -F "page_range=1" -o header.xlsx
curl -X POST https://api.myocr.app/v1/convert -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@bill.pdf" -F "model=tables" -F "page_range=3-" -o detail.xlsx

आउटपुट फ़ॉर्मेट

रिस्पॉन्स फ़ॉर्मेट चुनने के लिए output पैरामीटर सेट करें: xlsx (डिफ़ॉल्ट, संरचित शीट), txt (सादा टेक्स्ट), json (निकाले गए फ़ील्ड JSON में) या csv। text मॉडल हमेशा txt लौटाता है।

model=bank_statement के लिए आप output को csv_quickbooks (बैंक इम्पोर्ट के लिए 4-कॉलम CSV), csv_xero (Xero इम्पोर्ट टेम्पलेट) या ofx (अधिकांश अकाउंटिंग सॉफ़्टवेयर के लिए मानक OFX फ़ाइल) पर भी सेट कर सकते हैं। output=json के साथ रिस्पॉन्स में reconciliation ऑब्जेक्ट भी शामिल होता है: प्रारंभिक/अंतिम बैलेंस, कुल क्रेडिट और डेबिट, परिकलित अंतर और ok=true जब निकाले गए लेनदेन स्टेटमेंट के योग से मेल खाते हैं।

रिस्पॉन्स और हेडर

JSON रिस्पॉन्स एक निश्चित envelope का पालन करते हैं: एक success बूलियन, एक data ऑब्जेक्ट (या error ऑब्जेक्ट) और एक request_id। फ़ाइल रिस्पॉन्स उपयुक्त Content-Type के साथ बाइनरी सीधे लौटाते हैं।

हर रिस्पॉन्स में X-MyOCR-Request-Id हेडर होता है। फ़ाइल रिस्पॉन्स में X-MyOCR-Pages-Used (बिल किए गए पेज) और X-MyOCR-Model (उपयोग किया गया मॉडल) भी होते हैं।

रिस्पॉन्स में एक warnings ऐरे भी आ सकता है: यह वैकल्पिक और अतिरिक्त फ़ील्ड है और परिणाम कभी नहीं बदलता। फ़िलहाल इसका एक ही मामला है, PAGE_RANGE_SUGGESTED, जो तब आता है जब एकल दस्तावेज़ वाले मॉडल (invoice, receipt, business_card) को तीन से ज़्यादा पेज वाली PDF बिना page_range के दी जाए, यानी जब विवरण संलग्नक भी दस्तावेज़ में मिल रहे हों। फ़ाइल रिस्पॉन्स में JSON बॉडी नहीं होती, इसलिए कोड X-MyOCR-Warning हेडर में आता है।

{
  "success": true,
  "data": { "request_id": "abcd1234" },
  "request_id": "abcd1234"
}

एरर

एरर success: false के साथ एक error.code और मानव-पठनीय error.message, और request_id लौटाते हैं। लॉजिक के लिए code (स्थिर) और लोगों के लिए message (बदल सकता है) का उपयोग करें।

रेट लिमिट और कोटा

रेट लिमिट प्रति API key लागू होती हैं (प्रति IP नहीं), इसलिए साझा प्रॉक्सी के पीछे के क्लाइंट लिमिट साझा नहीं करते: /v1/convert 60 req/min, /v1/jobs 120 req/min, /v1/batch 30 req/min।

बिलिंग प्रति पेज, प्रति कॉल नहीं। प्लान: Free कुल 10 पेज (एक बार, कार्ड आवश्यक), Starter €29/माह (2,500), Pro €99/माह (10,000), Scale €190/माह (20,000)। सेवा कभी बाधित नहीं होती: महीने के पेज खत्म होने पर हम ईमेल करते हैं और आपके प्लान की प्रति-पेज दर पर एक अतिरिक्त पैक चार्ज करते हैं — Starter 500 @ €0.0116, Pro 2,000 @ €0.0099, Scale 4,000 @ €0.0095 — आपके द्वारा तय मासिक ऑटो-रिचार्ज सीमा तक (जिसे बंद भी कर सकते हैं)। सीमा पहुँचने पर API 402 और upgrade_url लौटाता है। GET /v1/usage से उपयोग जांचें।

वेबहुक

जब आप /v1/jobs को एक webhook_url देते हैं, तो job के done या failed होने पर हम उस URL पर एक JSON payload POST करते हैं। विफलता पर डिलीवरी बैकऑफ़ के साथ पुनः की जाती है।

हर डिलीवरी हस्ताक्षरित होती है: यह पुष्टि करने के लिए कि रिक्वेस्ट वास्तव में myocr.app से आई है, अपने webhook signing secret (डैशबोर्ड में दिखता है) से सिग्नेचर हेडर सत्यापित करें। Python SDK में verify_webhook_signature हेल्पर शामिल है।

SDK

आधिकारिक Python SDK (myocr-client) हर एंडपॉइंट को टाइप्ड मेथड और एक्सेप्शन, बैकऑफ़ के साथ स्वचालित Job.wait() पोलिंग, और वेबहुक सिग्नेचर सत्यापन के साथ रैप करता है।

रॉ HTTP पसंद है? कोई भी HTTP क्लाइंट काम करता है — इस गाइड में cURL और Node उदाहरण तथा पूर्ण इंटरैक्टिव रेफरेंस देखें।

pip install myocr-client

OpenAPI स्पेक