OCR API؛ خواندن متن PDF و تصویر، صفحه به صفحه با خروجی Markdown
مسیر POST /v1/ocr در وان ای آی (1ai) یک سند یا تصویر می‌گیرد و متن هر صفحه را جدا و به صورت Markdown برمیگرداند؛ برای وارد کردن متن فاکتور، قرارداد یا گزارش به برنامه‌ی خودتان یا آماده کردن سند برای RAG. سند را با نشانی عمومی یا data URL می‌فرستید و با فیلد pages می‌گویید کدام صفحه‌ها خوانده شوند. هزینه به ازای هر صفحهی خوانده‌شده حساب میشود. این مسیر روی متن چاپی فارسی در تصویر و PDF بررسی شده است؛ دستخط و سند اسکنشده هنوز آزموده نشدهاند.
چرا با 1ai
متن هر صفحه جدا
پاسخ برای هر صفحه یک markdown دارد، همراه با شماره و ابعاد صفحه.
هزینه به ازای صفحهی خوانده‌شده
صفحه‌هایی که از انتهای سند بیرون می‌زنند هزینهای ندارند؛ مصرف در usage.pages می‌آید.
نشانی یا data URL
PDF را با document_url و تصویر را با image_url بفرستید؛ هر دو نشانی http(s) یا data URL می‌پذیرند.
سند بلند، قدم به قدم
با pages صفحههای مشخصی را بخوانید و با truncated بفهمید سند ممکن است ادامه داشته باشد.
در چند قدم
- ۱
کلید API بسازید
از بخش توسعه‌دهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در ONEAI_API_KEY نگه دارید.
- ۲
سند را آماده کنید
نشانی عمومی فایل را بردارید، یا فایل را به data URL با base64 تبدیل کنید.
- ۳
درخواست بفرستید
مدل و سند را به https://1ai.ir/v1/ocr بفرستید و در صورت نیاز pages را هم بگذارید.
- ۴
متن را بردارید
متن هر صفحه در pages[].markdown است. اگر truncated برگشت، صفحههای بعدی را با pages بخواهید.
مدل‌های OCR در API
همه‌ی مدلهانمونه درخواست با curl
curl https://1ai.ir/v1/ocr \
-H "Authorization: Bearer $ONEAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mistralai/mistral-ocr-4",
"document": { "type": "document_url", "document_url": "https://example.com/invoice.pdf" },
"pages": [0, 1]
}'برای تصویر، document را این‌طور بنویسید:
{ "type": "image_url", "image_url": "https://example.com/receipt.png" }فرستادن فایل محلی با Python
# pip install requests
import base64, os, requests
with open("invoice.pdf", "rb") as f:
data = base64.b64encode(f.read()).decode()
res = requests.post(
"https://1ai.ir/v1/ocr",
headers={"Authorization": f"Bearer {os.environ['ONEAI_API_KEY']}"},
json={
"model": "mistralai/mistral-ocr-4",
"document": {"type": "document_url", "document_url": f"data:application/pdf;base64,{data}"},
},
timeout=300,
)
res.raise_for_status()
for page in res.json()["pages"]:
print(page["markdown"])بدنه‌ی JSON با data URL حداکثر ۲۵ مگابایت است؛ برای فایل بزرگ‌تر نشانی فایل را بفرستید.
قالب پاسخ
{
"object": "ocr",
"model": "mistralai/mistral-ocr-4",
"pages": [
{ "index": 0, "markdown": "# فاکتور فروش\n\n…", "dimensions": { … }, "images": [] }
],
"usage": { "pages": 1 }
}usage.pages تعداد صفحهی حساب‌شده است و اعتبار کسرشده در سرآیند x-1ai-credits می‌آید. اگر سند ممکن است ادامه داشته باشد، truncated: true هم در پاسخ هست.
فیلدهای درخواست
| فیلد | نوع | توضیح |
|---|---|---|
model | رشته | شناسه‌ی مدل OCR |
document | شیء | { "type": "document_url", "document_url": "…" } یا { "type": "image_url", "image_url": "…" } |
pages | آرایه‌ی عدد، اختیاری | شمارهی صفحه‌ها، از صفر |
include_image_base64 | بولین، اختیاری | تصویرهای داخل صفحه هم به صورت base64 برگردند |
فیلدهای دیگر پذیرفته نمی‌شوند.
سند چندصفحه‌ای و truncated
تعداد صفحههای سند پیش از خواندن معلوم نیست. پس 1ai پیش از اجرا برای صفحه‌هایی که نام برده‌اید اعتبار رزرو می‌کند؛ اگر pages نفرستید، برای صفحههای اول سند تا سقف هر درخواست و تا جایی که موجودی اجازه دهد. در پایان فقط صفحه‌هایی که واقعاً خوانده شده‌اند حساب می‌شوند و بقیه برمی‌گردد.
اگر truncated: true برگشت، سند ممکن است ادامه داشته باشد؛ صفحههای بعدی را با pages بخواهید:
{ "pages": [100, 101, 102] }فهرست کردن صفحههای بیشتر از سقف هر درخواست، خطای 400 too_many_pages می‌دهد.
نکته‌ها
- این مسیر روی متن چاپی فارسی در تصویر و PDF بررسی شده است. دستخط و سند اسکنشده هنوز آزموده نشدهاند؛ پیش از تکیه بر نتیجه، چند نمونهی واقعی خودتان را امتحان کنید.
- این مسیر استریم ندارد و کتابخانه‌ی openai متدی برای آن ندارد؛ با
requestsیاfetchبفرستید. - برای گرفتن فیلدهای تایپ‌دار از متن یا تصویر، مثل مبلغ و تاریخ فاکتور، Extraction API را ببینید.
سوالات متداول
متن فارسی را درست میخواند؟
روی متن چاپی فارسی در یک تصویر و یک PDF درست خوانده است. دستخط و سند اسکنشده هنوز آزموده نشدهاند، پس برای این نوع سندها اول چند نمونهی واقعی خودتان را امتحان کنید.
هزینهی هر درخواست چطور حساب میشود؟
به ازای هر صفحهای که واقعاً خوانده شده است. اگر صفحهای را نام ببرید که از انتهای سند بیرون است، هزینهای ندارد. قیمت هر مدل در صفحهی همان مدل و اعتبار کسرشده در سرآیند x-1ai-credits است.
truncated یعنی چه؟
یعنی سند ممکن است صفحههای بیشتری داشته باشد که در این درخواست خوانده نشدهاند. برای ادامه، شمارهی صفحههای بعدی را در pages بفرستید.
چه فرقی با Extraction API دارد؟
OCR متن هر صفحه را به صورت Markdown برمیگرداند. Extraction API فیلدهایی را که خودتان تعریف میکنید از متن یا تصویر بیرون میکشد. اگر متن کامل سند را میخواهید OCR مناسب است و اگر چند فیلد مشخص را، Extraction.
مطالب مرتبط
استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
چطور پروژه‌ای را که با کتابخانه‌ی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدل‌ها و مدیریت خطا.
کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدل‌های مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.
صفحههای مرتبط
همه‌ی امکاناتExtraction API
فیلدهایی را که لازم دارید با نوعشان تعریف کنید و از متن یا تصویر، مقدار هر فیلد را با اطمینان آن بگیرید؛ فیلدی که در متن نیست null برمی‌گردد.
Rerank API
یک پرسش و فهرستی از متن‌ها بفرستید و همان متن‌ها را مرتب‌شده بر اساس ارتباط با پرسش، همراه با امتیاز هر کدام، پس بگیرید.
OpenAI SDK
کتابخانه‌ی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.
OCR API؛ خواندن متن PDF و تصویر، صفحه به صفحه با خروجی Markdown
یک PDF یا تصویر را با نشانی یا data URL بفرستید و متن هر صفحه را به صورت Markdown پس بگیرید؛ هزینه فقط به ازای صفحه‌هایی است که واقعاً خوانده شده‌اند.
ساخت کلید API