رأس الطلب
استخدم X-API-Key: sk_… أو Authorization: Bearer sk_…، واحد من الاثنين لكل طلب. أرسل Content-Type: application/json مع هياكل JSON.
Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · مصادقة مفتاح API · تتم عمليات ترجمة الملفات كمهام غير متزامنة
يصف هذا الموقع واجهة برمجة تطبيقات السحابة HTTP.
تأكد من أن المفتاح والشبكة يعملان قبل تحميل الملفات. فحص الرصيد لا يكلف أي رصيد ولا ينشئ مهمة ترجمة.
احصل على مفتاح واجهة برمجة التطبيقات
سجّل الدخول إلى وحدة تحكم API وأنشئ مفتاحًا يبدأ بـ sk_. استخدم مفتاحًا منفصلاً لكل تطبيق وحدد له ميزانية.
المفتاح يعمل لصالح الحساب الذي أنشأه. احتفظ به على الخادم واقرأه من متغير بيئة؛ ولا تضعه أبداً في مصدر صفحة الويب أو في مستودع عام.
تحقق من الرصيد
عيّن المتغير البيئي OMNIDOC_API_KEY، ثم شغّل أيًا من الأمثلة أدناه. يُشير النجاح إلى JSON؛ أما 401 فتعني أن المفتاح به مشكلة ويحتاج إلى فحص. لا تُظهر أبدًا المفتاح الكامل في التذاكر أو لقطات الشاشة أو السجلات.
export OMNIDOC_API_KEY="sk_your_key"curl --fail-with-body --silent --show-error \ 'https://omnidoc.top/api/v1/billing/credits/balance' \ -H "X-API-Key: $OMNIDOC_API_KEY"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());إن نجاح عملية الرفع يعني فقط أن الملف قد تم تخزينه. بعد إنشاء مهمة، انتظر حتى تصل إلى حالة نهائية، ثم قم بإدراج نتائجها وتنزيلها.
| الخطوة | الطريقة والمسار | ما الذي يجب الحفاظ عليه |
|---|---|---|
| اطلب تحميل | POST /upload/presign | upload_url, upload_headers, finalize_token |
| أرسل الملف | PUT إلى upload_url المُعاد إرجاعه | استجابة ناجحة؛ لا يحتوي هذا الطلب على مفتاح API |
| تأكيد التحميل | POST /upload/finalize | document.id |
| أنشئ ترجمة | POST /jobs | الوظيفة id |
| تحقق من الحالة | GET /jobs/{job_id} | completed أو failed |
| قائمة بالنتائج | GET /artifacts?job_id={job_id} | معرّفات وتنسيقات المصنوعات |
| تنزيل النتيجة | GET /artifacts/{artifact_id}/download | بايتات الملف واسم ملف الاستجابة |
بالنسبة للتحميل المباشر، أرسل upload_headers من الخادم تمامًا كما تم إرجاعه، ولا ترسل X-API-Key إلى عنوان التخزين أبدًا. إذا انتهت صلاحية عنوان التحميل أو فشل النقل، اطلب واحدًا جديدًا. التفاصيل: بروتوكول التحميل ، البدء السريع ، سير عمل Node.js الكامل و حقول طلب الترجمة .
يعرض كل إدخال المسارات وحقول الطلبات والأمثلة. ينطبق حالة خدمة حسابك وحدود مفتاحك على جميعها.
مفتاح API يحدد حسابًا. وهو ليس كلمة مرور تنزيل عامة لملف.
رأس الطلب
استخدم X-API-Key: sk_… أو Authorization: Bearer sk_…، واحد من الاثنين لكل طلب. أرسل Content-Type: application/json مع هياكل JSON.
ما يمكن أن يصل إليه المفتاح
تقتصر وصول المفتاح إلى الموارد التي يُسمح لحسابه باستخدامها فقط؛ ولا تزال حالة الخدمة وميزانية المفتاح وإعدادات الترجمة المسموح بها سارية المفعول. تتم عمليات تعديل الحساب وإنشاء المفاتيح أو تدويرها أو إلغاء صلاحيتها من خلال وحدة التحكم.
انظر المصادقة، والميزانيات، والتناوب و الخدمات والأذونات .
إن انتهاء المهلة لا يعني عدم إنشاء المهمة. ميّز بين الأخطاء القابلة لإعادة المحاولة وبين الطلبات التي تحتاج إلى تصحيح، لضمان عدم تقديم أو معالجة أي شيء مرتين.
Idempotency-Key لكل عملية إنشاء جديدة؛ وعند إعادة محاولة نفس العملية، أعد استخدام المفتاح الأصلي ونصّ الطلب نفسه بالضبط. تتطلب عمليات الوثائق والوظائف الإعلامية وإنشاء الصوت المفتاح؛ وللحصول على تفاصيل نقاط النهاية الأخرى الخاصة بالإنشاء، راجع صفحات المرجع الخاصة بها.| الحالة | تحقق أولاً | ماذا يجب فعله |
|---|---|---|
401 / 403 | المفتاح، الأذونات، ملكية الموارد | قم بتصحيح بيانات الاعتماد أو الأذونات؛ ولا تُعد المحاولة بشكل أعمى |
402 | الاعتمادات المتاحة | أعد الشحن، ثم أرسل مرة أخرى |
409 | مفتاح التكرارية وجسم الطلب، حالة المورد | استعلام عن العملية الأصلية قبل بدء عملية جديدة |
422 | أخطاء الحقول في الاستجابة | قم بتصحيح المعلمات أو الملف |
429 | الأعمال code و Retry-After | يمكن انتظار انتهاء حدود المعدل والطابور؛ يجب أولاً زيادة ميزانية المفاتيح المستهلكة. |
5xx | خطأ مؤقت في الخدمة | إرجاع أسي محدود؛ احتفظ بمفتاح التكرارية لطلبات الإنشاء |
احتفظ بعنوان الاستجابة X-Request-Id ووقت الطلب والمسار لاستكشاف الأخطاء وإصلاحها؛ ولا تسجل المفتاح الكامل أبداً. جميع رموز الأخطاء وأمثلة إعادة المحاولة موجودة في مرجع الأخطاء . .
لا توجد رصيد
لا تُحتسب رسوم التحميل، وفحص المهام، وتنزيل النتائج، وقراءة الرصيد وسجلات التسوية؛ وكذلك لا تُحتسب رسوم القواميس والمشاريع والوسوم والبحث والمشاركة.
يتم الفوترة حسب الاستخدام
تُحتسب أسعار ترجمة الملفات وأدوات المستندات والترجمة الفورية وخدمات الصوت والفيديو بناءً على الاستخدام الفعلي؛ ولا يُعد إنشاء مهمة بمثابة الرسوم النهائية.
قبل بدء أي مهمة، يتم التحقق فقط من عتبة الرصيد؛ وبعد انتهاء المهمة، يتم تحصيل الاستخدام الفعلي. إذا نفد الرصيد، تُسجَّل الفرق كدين، وتُسدَّد الأرصدة الائتمانية الواردة لاحقًا أولاً. يمكنك مطابقة الرسوم والمبالغ المستردة حسب كل مهمة أو حسب كل عملية ائتمانية. وعند استنفاد ميزانية المفتاح، يظل بإمكانك الاستعلام عن المهام والنتائج والسجلات الخاصة بذلك المفتاح.