مهام تحويل الكلام إلى نص والترجمة

استبدل SERVICE في الأمثلة أدناه بـ speech_to_text أو translate، واستبدل JOB_ID بمعرّف UUID الذي يُعاد إليك. تتطلب جميع العمليات بيانات اعتماد لحسابك، كما هو موضح في قسم المصادقة، ويقتصر نطاقها على الحساب المالك للمهمة. يمكن قراءة المهمة من أي من خادمَي API، لكن لكل خادم بنية خارجية خاصة للاستجابة، لذا استخدم الخادم نفسه باستمرار.

على api.multitel.net، تُعاد أخطاء المصادقة (401) قبل تطبيق هذه البنية الخارجية، وقد يكون لها متن مختلف، لذا تحقق من رمز حالة HTTP قبل تحليل الاستجابة.

المصادقة

يجب أن يتضمن كل طلب بيانات اعتماد لحسابك. تنتمي المهام ومفاتيح عدم التكرار والحدود والاستخدام والرسوم إلى الحساب الذي يملك بيانات الاعتماد. وهي مشتركة بين جميع بيانات اعتماد ذلك الحساب على كلا الخادمَين، بغض النظر عن بيانات الاعتماد المستخدمة لإرسال الطلب.

• مصادقة HTTP Basic (Authorization: Basic أو curl --user). تُقبل بيانات اعتماد حساب API من نوع كلمة المرور، أو حساب فرعي، أو بيانات تسجيل الدخول إلى حسابك. نوصي باستخدام حساب API مخصص. لا يجوز أن يحتوي اسم المستخدم على نقطتين رأسيتين، ولا يجوز أن يكون اسم المستخدم أو كلمة المرور فارغًا.
• رمز Bearer المميز (Authorization: Bearer YOUR_TOKEN). يُقبل لحساب API من نوع الرمز المميز. يجب أن تكون حسابات API من هذا النوع مقيدة بعناوين IP، ويجب أن تأتي الطلبات من عنوان مسموح به. يقبل كلا خادمَي API عناوين IPv4 ونطاقات CIDR المهيأة للحساب. لا يمكن إرسال رمز مميز بوصفه كلمة مرور Basic. تأكد من أن رمزك المميز يعمل على الخادم الذي تستخدمه.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

إذا كان حساب API مقيدًا بعنوان IP، فأرسل الطلبات من عنوان مسموح به. تُعيد بيانات الاعتماد المفقودة أو غير الصالحة الرمز 401. على api.multitel.net، تُعيد بيانات الاعتماد الصالحة التي لا يمكنها استخدام هذه الخدمات، مثل بيانات اعتماد حساب رمز مميز تُرسل باستخدام Basic، الرمز 403 مع unsupported_transcription_principal أو unsupported_translation_principal. قد تؤدي محاولات المصادقة الفاشلة المتكررة من عنوان واحد على api.multitel.net إلى حظر ذلك العنوان، لذا صحح بيانات الاعتماد قبل المحاولة مجددًا.

استعلم دوريًا عن اكتمال المهمة

أرسل الطلب GET /v3/SERVICE/JOB_ID. نوصي بالاستعلام عن الحالة بمعدل لا يتجاوز مرة كل 3 ثوانٍ. تصف البنية الخارجية للاستجابة الطلب نفسه؛ افحص الحقل status للمهمة داخلها لتحديد ما إذا كانت المعالجة قد انتهت.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

على api.multitel.net، اضبط HOST على https://api.multitel.net واقرأ .response.id بدلًا من .data.id.

أعد بأمان الطلبات ذات النتيجة غير المؤكدة

إذا انتهت مهلة إرسال المهمة أو أُعيد الرمز 429 أو رمز حالة 5xx، فأعد إرسال المدخلات نفسها بمفتاح عدم التكرار نفسه. قد تضيع استجابة أي من الخادمَين أو تُستبدل بخطأ بعد قبول المهمة؛ وإعادة الإرسال بالمفتاح نفسه تُعيد المهمة إذا كانت موجودة. تُعيد إعادة استخدام مفتاح مع مدخلات مختلفة الرمز 409 مع idempotency_conflict. تتكرر بعض الأخطاء في كل محاولة، مثل 503 عندما تكون خدمة مدفوعة معطلة، أو 500 لملف صوتي لا يمكن قراءته، لذا توقف بعد بضع محاولات.

تختلف آثار تغيير المفتاح باختلاف الخدمة.

• في تحويل الكلام إلى نص، ينشئ المفتاح الجديد مهمة جديدة تُفرض عليها رسوم منفصلة إذا اكتملت المعالجة بنجاح. يظل المفتاح الأصلي يُعيد المهمة الأصلية، حتى بعد تحديث المعالجة.
• في الترجمة، يُعيد مفتاح جديد بمحتوى مطابق مهمة مطابقة في قائمة الانتظار أو قيد المعالجة أو مكتملة أو بانتظار الدفع، دون رسوم جديدة. ينشئ مهمة جديدة إذا فشلت المهمة السابقة أو تغير إصدار المعالجة. تُعيد محاولة الترجمة بالمفتاح الأصلي الرمز 409 بعد تغيير إصدار المعالجة، لذا احتفظ بمعرّف المهمة الأصلي واقرأ المهمة مباشرة.

أفرج عن النتيجة بعد إضافة رصيد

لمهمة في حالة awaiting_payment، أضف رصيدًا بحيث لا يقل رصيدك عن قيمة costUsd للمهمة بعد تقريبها صعودًا إلى المضاعف التالي لـ $0.00001، ثم أرسل POST /v3/SERVICE/JOB_ID/settle. تتم الخصومات بمضاعفات صحيحة من $0.00001 وتشمل أي جزء متبقٍ مُرحّل من مهام سابقة للخدمة نفسها، لذا قد يتجاوز المبلغ المخصوم قيمة costUsd بمقدار أقل من $0.00001. على api.multi.tel، أرسل JSON {} أو متنًا فارغًا؛ وتُرفض أي خاصية في المتن بالرمز 400. أما api.multitel.net فيتجاهل المتن. تُفرج عملية التسوية عن النتيجة المحفوظة دون إعادة تشغيل التفريغ النصي أو الترجمة. تحتوي الاستجابة على المهمة؛ تحقق من أن حالتها هي completed. إذا ظل الرصيد غير كافٍ، تبقى المهمة في حالة awaiting_payment، وتظل الاستجابة تحمل رمز HTTP 200.

في تحويل الكلام إلى نص، تُعيد تسوية مهمة مكتملة بالفعل المهمة مع duplicate: true، وتُعيد تسوية مهمة في قائمة الانتظار أو قيد المعالجة أو فاشلة الرمز 409 مع transcription_not_awaiting_payment. في الترجمة، تُعيد تسوية مهمة في أي حالة أخرى المهمة دون تغيير. لا تتاح التسوية إلا عند تمكين المعالجة المدفوعة (وإلا يُعاد 503). تُحتسب المهام التي تنتظر الدفع ضمن التكلفة المحجوزة، لذا قد تمنع الحسابات المدفوعة مقدمًا من إرسال مهام مدفوعة جديدة بالرمز 402 حتى تتم تسوية تلك المهام.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

تحقق من الاستخدام

استخدم GET /v3/SERVICE/usage. المعلمتان الاختياريتان from وto هما تاريخان بتوقيت UTC بالتنسيق YYYY-MM-DD، ويُحتسب تاريخا بداية النطاق ونهايته ضمنه. إذا لم تُحددا، تكون القيمة الافتراضية لـ from هي تاريخ اليوم ناقص 30 يومًا، ولـ to هي تاريخ اليوم (UTC). يجب ألا يكون to أسبق من from، ويجب ألا يزيد الفارق بين التاريخين على 366 يومًا (حتى 367 تاريخًا). تُعيد التواريخ التقويمية غير الصالحة أو النطاق المعكوس أو الأطول الرمز 400، وكذلك معلمات الاستعلام الأخرى على api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

تحتوي الاستجابة على mode, currency (USD), from, to وdays، وهي قائمة مرتبة من الأحدث إلى الأقدم.

• تُجمع سجلات تحويل الكلام إلى نص حسب التاريخ والمصدر. وتحتوي على date, source (api أو hpbx لتسجيلات Hosted PBX)، files, audioSeconds, billedSeconds, accruedUsd وdebitedUsd.
• تُجمع سجلات الترجمة حسب التاريخ والمصدر والمحرك. وتحتوي على date, source, engine, jobs, sourceCharacters, accruedUsd وdebitedUsd.

accruedUsd يمثّل التكلفة الدقيقة بتسع منازل عشرية، وdebitedUsd يمثّل المبلغ المخصوم بخمس منازل عشرية. يُسجل الاستخدام في تاريخ تسوية رسوم كل مهمة بتوقيت UTC، لذا لا تظهر المهام في قائمة الانتظار أو قيد المعالجة أو الفاشلة أو التي تنتظر الدفع.

الحدود

يمكن لكل حساب أن يضم بحد أقصى 50 مهمة معلقة من تحويل الكلام إلى نص والترجمة مجتمعتين: في قائمة الانتظار أو قيد المعالجة أو بانتظار الدفع، بما في ذلك معالجة تسجيلات Hosted PBX. عند بلوغ هذا الحد أو السعة الإجمالية للخدمة، تُعيد عمليات الإرسال الرمز 429 مع transcription_queue_full أو translation_queue_full. يحدد api.multi.tel أيضًا حدًا لكل عنوان IP عميل يبلغ 300 طلب في الدقيقة، ويشمل جميع الطلبات إلى ذلك الخادم. يُعيد هذا الحد الرمز 429 مع ترويسات تحديد معدل الطلبات ومتن نصي عادي بدلًا من البنية الخارجية لخطأ JSON.

تعامل مع أخطاء الطلبات

على الخادم الرئيسي، تُعيد حالات الفشل رمز خطأ HTTP وJSON يحتوي على status: "error", code, message وrequestId. تتضمن كل استجابة أيضًا ترويسة X-Request-ID. يمكنك تقديم قيمة خاصة بك؛ وتُقتطع القيم الأطول من 128 محرفًا. لا يُعيد خادم التوافق إلا رمز الخطأ في response.code. سجّل معرّف الطلب، حيثما يتوفر، ورمز الخطأ، ولا تسجل الصوت أو النص أو بيانات الاعتماد في السجلات.

رموز الحالة الشائعة:

اعتمد على رمز الخطأ المُعاد بدلًا من افتراض أن كل فشل في التحقق من صحة المدخلات له رمز حالة واحد.

عند تلقي 429 أو 503، انتظر ثم أعد المحاولة مع زيادة مدة الانتظار وبمفتاح الإرسال نفسه؛ والتزم بترويسة Retry-After عند وجودها. إذا كانت المدخلات أو بيانات الاعتماد غير صالحة، فصحح السبب أولًا. لا تُرسل مفاتيح جديدة بصورة متكررة ما دامت المهام السابقة في قائمة الانتظار.