مرجع حدث النسخ السريع

يرفع حدث audio_file ملفًا كاملًا عبر Socket.IO كحمولة ثنائية واحدة. يرد الخادم بإقرار رفع ثم أحداث transcription_result جزئية ونهائية. أسماء الحقول والنماذج تبقى كما هي في البروتوكول.

الاتصال

• المسار: /socket.io
• النقل: websocket فقط
• المصادقة: ترويسة x-api-key
• ترويسة Origin: مطلوبة على الإنتاج؛ اضبطها على https://api.voice.humain.com

الحدود

ينطبق حدّان مستقلان على كل رفع لحدث audio_file، وهما يقيسان أمرين مختلفين. وكلاهما شامل: النجاح عند الحد بالضبط، والفشل عند تجاوزه فقط.

يُقاس سقف البايتات على بايتات الوسائط وحدها، بعد ترويسة التأطير وسلاسل مفاتيح النماذج الأربعة. أما مسار HTTP المكافئ فيحدّ جسم طلب multipart كاملًا بالرقم نفسه، لذلك يمر ملف بحجم 64 MiB بالضبط هنا لكنه لا يتسع داخل جسم HTTP بحجم 64 MiB.

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

ويُرفض الصوت المفرط في الطول قبل أي استدلال ولا يستهلك أي رصيد من سعة الصوت. وللتسجيلات الأطول من 30 دقيقة أو الأكبر من 64 MiB، قسّم الصوت إلى وحدات أقصر أو استخدم واجهة النسخ الدفعي التي يبلغ سقفها 4 ساعات لكل ملف.

تنسيق الصوت

يجب أن تكون الحمولة الكاملة AAC (ADTS) أو FLAC أو MP3 أو WAV أو ملف ISO base media. ويتعرف الخادم على الحاوية من الحمولة نفسها، لا من اسم ملف ولا من نوع وسيط، ويُرفض أي شيء آخر بالرمز ASR_UNSUPPORTED_CODEC حتى عندما يكون قابلًا لفك الترميز.

ومدخل ISO base media عائلة: فصيغة MP4 هي الشكل المقصود والمدعوم، أما MOV وM4A و3GP و3G2 وMJ2 فتشترك معها في مفكك حاويات واحد ولذلك يقبلها الفحص نفسه. وMP4 وحدها مدعومة بمعنى أنها مختبرة ومقصودة؛ فلا تبنِ على غيرها.

وضع الذرة moov في مقدمة ملف ISO base media. وهذه ليست سياسة يفحصها الخادم ويرفض على أساسها — بل مطلب عملي: فالرفع يُقرأ إلى الأمام فقط، ولا يمكن الوصول إلى moov في نهايته فيفشل فك ترميز الملف.

اللغات والنماذج

الأحداث

تخطيط audio_file

حقول الطول تستخدم uint16 بترتيب little-endian. اضبط طول أي مفتاح نموذج إلى 0 لتجاوزه.

مثال إرسال

socket.emit("audio_file", packet);

socket.on("audio_file_upload_success", ({ id }) => {
  // إيصال بايتات فقط؛ انتظر transcription_result مع is_final للتأكد من النسخ.
  console.log("received", id);
});

socket.on("transcription_result", (response) => {
  console.log(response.transcription, response.is_final);
});

نتيجة النسخ

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "seq": 0,
  "transcription": "مرحبا بكم",
  "words": [
    { "start_time": 0.0, "end_time": 1.1, "word": "مرحبا" },
    { "start_time": 1.1, "end_time": 2.4, "word": "بكم" }
  ],
  "is_final": true
}

الحقول id وseq وtranscription وwords وis_final كلها مطلوبة. توجد أزمنة start_time وend_time داخل كل عنصر في words فقط، لا على المستوى الأعلى. عامل seq بوصفه بيانات تشخيصية؛ فترتيبها وتجميعها ليسا جزءًا من عقد Fast العام.

الأخطاء

استخدم حدث error لالتقاط فشل المصادقة، أو payload غير صالح، أو تجاوز أحد الحدود. وحقل code معدود؛ فرّع عليه لا على نص الرسالة:

ويحمل رفض الحدود كائن data يسمّي الحد وقيمته المضبوطة والقيمة المرصودة، حتى تعرف أي حد بلغته دون تحليل نص. ولحد fast_audio_duration تكون unit هي seconds، وحيث توقفت الخدمة عن فك الترميز عند السقف تكون observed حدًا أدنى. ولحد fast_audio_bytes تكون unit هي bytes وobserved هي حجم الوسائط الدقيق.

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "AUDIO_DURATION_EXCEEDED",
  "message": "decoded audio duration exceeds the maximum for this endpoint; split the recording or use the batch transcription API",
  "retryable": false,
  "timestamp": "2025-05-07T10:00:00.000Z",
  "data": {
    "limit": 1800,
    "observed": 3601,
    "unit": "seconds",
    "bound": "fast_audio_duration"
  }
}