تخطَّ إلى المحتوى

أدخل سير عمل المستندات إلى تطبيقك

بدءًا من رفع ملف واحد وحتى ترجمته، ومتابعة التقدم وتنزيل النتيجة. يتم شرح كل خطوة بالترتيب الذي تدمج به الأدوات، مع نقاط دخول لإدارة الملفات ومعالجة المستندات وخدمات الصوت والفيديو.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · مصادقة مفتاح API · تتم عمليات ترجمة الملفات كمهام غير متزامنة

يصف هذا الموقع واجهة برمجة تطبيقات السحابة HTTP.

01 ابدأ بطلب لا يكلف أي رصيد

Section titled “01 ابدأ بطلب لا يكلف أي رصيد”

تأكد من أن المفتاح والشبكة يعملان قبل تحميل الملفات. فحص الرصيد لا يكلف أي رصيد ولا ينشئ مهمة ترجمة.

  1. احصل على مفتاح واجهة برمجة التطبيقات

    سجّل الدخول إلى وحدة تحكم API وأنشئ مفتاحًا يبدأ بـ sk_. استخدم مفتاحًا منفصلاً لكل تطبيق وحدد له ميزانية.

    المفتاح يعمل لصالح الحساب الذي أنشأه. احتفظ به على الخادم واقرأه من متغير بيئة؛ ولا تضعه أبداً في مصدر صفحة الويب أو في مستودع عام.

  2. تحقق من الرصيد

    عيّن المتغير البيئي OMNIDOC_API_KEY، ثم شغّل أيًا من الأمثلة أدناه. يُشير النجاح إلى JSON؛ أما 401 فتعني أن المفتاح به مشكلة ويحتاج إلى فحص. لا تُظهر أبدًا المفتاح الكامل في التذاكر أو لقطات الشاشة أو السجلات.

    Terminal window
    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"

إن نجاح عملية الرفع يعني فقط أن الملف قد تم تخزينه. بعد إنشاء مهمة، انتظر حتى تصل إلى حالة نهائية، ثم قم بإدراج نتائجها وتنزيلها.

الخطوةالطريقة والمسارما الذي يجب الحفاظ عليه
اطلب تحميلPOST /upload/presignupload_url, upload_headers, finalize_token
أرسل الملفPUT إلى upload_url المُعاد إرجاعهاستجابة ناجحة؛ لا يحتوي هذا الطلب على مفتاح API
تأكيد التحميلPOST /upload/finalizedocument.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 الكامل و حقول طلب الترجمة .

03 اعثر على نقطة النهاية لمهامتك

Section titled “03 اعثر على نقطة النهاية لمهامتك”

يعرض كل إدخال المسارات وحقول الطلبات والأمثلة. ينطبق حالة خدمة حسابك وحدود مفتاحك على جميعها.

04 المصادقة وملكية الموارد

Section titled “04 المصادقة وملكية الموارد”

مفتاح API يحدد حسابًا. وهو ليس كلمة مرور تنزيل عامة لملف.

رأس الطلب

استخدم X-API-Key: sk_… أو Authorization: Bearer sk_…، واحد من الاثنين لكل طلب. أرسل Content-Type: application/json مع هياكل JSON.

ما يمكن أن يصل إليه المفتاح

تقتصر وصول المفتاح إلى الموارد التي يُسمح لحسابه باستخدامها فقط؛ ولا تزال حالة الخدمة وميزانية المفتاح وإعدادات الترجمة المسموح بها سارية المفعول. تتم عمليات تعديل الحساب وإنشاء المفاتيح أو تدويرها أو إلغاء صلاحيتها من خلال وحدة التحكم.

انظر المصادقة، والميزانيات، والتناوب و الخدمات والأذونات .

05 تضمين معالجة فشل البناء في عملية التكامل

Section titled “05 تضمين معالجة فشل البناء في عملية التكامل”

إن انتهاء المهلة لا يعني عدم إنشاء المهمة. ميّز بين الأخطاء القابلة لإعادة المحاولة وبين الطلبات التي تحتاج إلى تصحيح، لضمان عدم تقديم أو معالجة أي شيء مرتين.

  • إنشاء مطابق للتأثير : قم بإنشاء Idempotency-Key لكل عملية إنشاء جديدة؛ وعند إعادة محاولة نفس العملية، أعد استخدام المفتاح الأصلي ونصّ الطلب نفسه بالضبط. تتطلب عمليات الوثائق والوظائف الإعلامية وإنشاء الصوت المفتاح؛ وللحصول على تفاصيل نقاط النهاية الأخرى الخاصة بالإنشاء، راجع صفحات المرجع الخاصة بها.
  • إشعارات غير متزامنة : يعد الاستعلام الدوري مناسبًا للتكامل الأولي؛ ولتتبع التقدم المستمر استخدم SSE ، ولتلقي الحالات النهائية في الخلفية استخدم webhook . .
الحالةتحقق أولاًماذا يجب فعله
401 / 403المفتاح، الأذونات، ملكية المواردقم بتصحيح بيانات الاعتماد أو الأذونات؛ ولا تُعد المحاولة بشكل أعمى
402الاعتمادات المتاحةأعد الشحن، ثم أرسل مرة أخرى
409مفتاح التكرارية وجسم الطلب، حالة المورداستعلام عن العملية الأصلية قبل بدء عملية جديدة
422أخطاء الحقول في الاستجابةقم بتصحيح المعلمات أو الملف
429الأعمال code و Retry-Afterيمكن انتظار انتهاء حدود المعدل والطابور؛ يجب أولاً زيادة ميزانية المفاتيح المستهلكة.
5xxخطأ مؤقت في الخدمةإرجاع أسي محدود؛ احتفظ بمفتاح التكرارية لطلبات الإنشاء

احتفظ بعنوان الاستجابة X-Request-Id ووقت الطلب والمسار لاستكشاف الأخطاء وإصلاحها؛ ولا تسجل المفتاح الكامل أبداً. جميع رموز الأخطاء وأمثلة إعادة المحاولة موجودة في مرجع الأخطاء . .

06 تحقق من كيفية عمل الفوترة قبل التكامل

Section titled “06 تحقق من كيفية عمل الفوترة قبل التكامل”

لا توجد رصيد

لا تُحتسب رسوم التحميل، وفحص المهام، وتنزيل النتائج، وقراءة الرصيد وسجلات التسوية؛ وكذلك لا تُحتسب رسوم القواميس والمشاريع والوسوم والبحث والمشاركة.

يتم الفوترة حسب الاستخدام

تُحتسب أسعار ترجمة الملفات وأدوات المستندات والترجمة الفورية وخدمات الصوت والفيديو بناءً على الاستخدام الفعلي؛ ولا يُعد إنشاء مهمة بمثابة الرسوم النهائية.

قبل بدء أي مهمة، يتم التحقق فقط من عتبة الرصيد؛ وبعد انتهاء المهمة، يتم تحصيل الاستخدام الفعلي. إذا نفد الرصيد، تُسجَّل الفرق كدين، وتُسدَّد الأرصدة الائتمانية الواردة لاحقًا أولاً. يمكنك مطابقة الرسوم والمبالغ المستردة حسب كل مهمة أو حسب كل عملية ائتمانية. وعند استنفاد ميزانية المفتاح، يظل بإمكانك الاستعلام عن المهام والنتائج والسجلات الخاصة بذلك المفتاح.