Realtime HTTP API

بث النسخ السريع لوحدة صوت مكتملة

ارفع وحدة صوت مكتملة ومحدودة، مثل دور وكيل، واستقبل تحديثات النسخ المتدفقة.

POST/http/stt

انسخ وحدة صوتية مكتملة ومحدودة وحساسة لزمن الاستجابة، مثل دور مستخدم منتهٍ في محادثة وكيلية أو أمر صوتي. استخدم Batch للتسجيلات المكتملة الطويلة أو الكبيرة، واستخدم ASR المباشر ما دام الصوت يصل.

هذه عملية مباشرة عبر HTTP. يستخدم عملاء Fast في SDK 0.18.0 بروتوكول Socket.IO؛ ولا يستدعون هذا المسار. أرسل الطلب من خلفية موثوقة مع X-Api-Key وقدرة ASR الفوري.

قدّم UUID فريدًا في id وملفًا صوتيًا مكتملًا واحدًا في حقل multipart المسمى file. تتقدم language غير الفارغة على lang، وتتقدم asr غير الفارغة على model. تستخدم اللغة المحذوفة أو auto والنموذج المحذوف الإعدادات الافتراضية المضبوطة للبيئة. يطبق Fast اختيار اللغة ونموذج ASR فقط؛ استخدم Batch عند الحاجة إلى تمييز المتحدثين أو ITN أو التنقيح.

الاستجابة بصيغة NDJSON. قد يصدر الطلب سجلات نسخ جزئية قبل السجل النهائي. إذا فشل استدعاء لاحق بعد إرسال الخرج، ينتهي بث 200 الجزئي من دون إلحاق خطأ JSON. لا تعد العملية مكتملة إلا بعد ملاحظة is_final: true صراحة، وعامل EOF أو الإلغاء أو انقضاء مهلة التطبيق من دون سجل نهائي على أنه عدم اكتمال. seq بيانات تشخيصية مبهمة لا تضمن ترتيبًا ولا تفردًا.

الحدود

ينطبق حدّان مستقلان، وهما يقيسان أمرين مختلفين.

يجب ألا يتجاوز جسم طلب multipart كاملًا 64 MiB (67108864 بايت). وتجاوزه هو الحالة 413 برمز PAYLOAD_TOO_LARGE وdata.bound: fast_audio_bytes.

ويجب ألا يزيد الصوت بعد فك الترميز على 1800 ثانية (30 دقيقة). وتجاوزه هو الحالة 422 برمز AUDIO_DURATION_EXCEEDED و data.bound: fast_audio_duration. وهذا حد منفصل لأن رفعًا مضغوطًا صغيرًا قد يُفك إلى ساعات كثيرة: فالطلب المقبول تمامًا بالبايتات قد يطلب مع ذلك عملًا صوتيًا أكبر مما تؤديه هذه النقطة. والحدان شاملان — النجاح عند الحد بالضبط، والفشل عند تجاوزه فقط.

وتفرض الخدمة حد المدة من ترويسة الحاوية حيث يعلن الملف طوله بنفسه، ومن بيانات الحاوية الوصفية حيث يستطيع مفكك الترميز قراءتها، وإلا فأثناء فك الترميز مع التوقف عند السقف. ولذلك يُرفض الصوت المفرط في الطول قبل أي استدلال، ولا يستهلك أي رصيد من سعة الصوت. ويمكن للنشر تغيير الحدّين معًا عبر REALTIME_MAX_BODY_BYTES_FAST_TRANSCRIPTION و REALTIME_MAX_FAST_AUDIO_DURATION_SEC، ولذلك لا يعلن هذا المخطط قيمة maxLength ثابتة.

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

تنسيق الصوت

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

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

ومعدل العينات وعدد القنوات غير مقيدين: يُعاد تشكيل الصوت ويُدمج إلى قناة أحادية عند معدل العينات المضبوط لنموذج ASR المختار، وهو معدل لا يختاره العميل.

طبّق مهلًا نهائية محدودة للاتصال وعدم النشاط والعملية كاملة. لا تدعم هذه العملية عقد idempotency أو إعادة تشغيل؛ فلا تعد الإرسال عشوائيًا بعد مهلة أو انقطاع ملتبس.

المصادقة

ApiKeyAuth
X-Api-Key<token>

الموضع: header

معاملات الاستعلام

id*string

UUID ارتباط جديد ينشئه العميل. وهو ليس مفتاح idempotency.

language?string

لغة النسخ. يُقبل lang أيضًا اسمًا مستعارًا. تتقدم language غير الفارغة على lang. تستخدم القيمة الفارغة أو auto الإعداد التلقائي الافتراضي المضبوط للبيئة.

asr?string

مفتاح دقيق اختياري لنموذج ASR؛ ويُقبل model أيضًا اسمًا مستعارًا. تتقدم asr غير الفارغة. إذا حُذف الحقلان، تستخدم الخدمة الإعداد الافتراضي المضبوط للغة المختارة.

model?string

اسم مستعار لـ asr.

lang?string

اسم مستعار لا يُستخدم إلا عند حذف language أو كونها فارغة.

جسم الطلب

multipart/form-data

تعريفات TypeScript

استخدم هذا النوع في TypeScript.

جسم الاستجابة

application/x-ndjson

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -sS --fail-with-body --connect-timeout 10 --max-time 120 -X POST \  "https://example.com/http/stt?id=497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Origin: https://example.com" \  -F "file=@meeting.wav"

صفر أو أكثر من سجلات النسخ بصيغة NDJSON. بعد بدء الخرج، ينهي أي فشل لاحق البثَّ الجزئي من دون إلحاق خطأ JSON. ويتطلب الاكتمال ملاحظة سجل يحتوي is_final: true.

application/x-ndjson

المثال partial

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "seq": 0,
  "transcription": "hello wor",
  "words": [
    {
      "start_time": 0,
      "end_time": 0.45,
      "word": "hello"
    }
  ],
  "is_final": false
}

المثال final

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "seq": 0,
  "transcription": "hello world",
  "words": [
    {
      "start_time": 0,
      "end_time": 0.45,
      "word": "hello"
    },
    {
      "start_time": 0.46,
      "end_time": 0.9,
      "word": "world"
    }
  ],
  "is_final": true
}

معرّف طلب أو لغة أو رفع multipart أو حاوية صوت أو نموذج ASR غير صالح. وكل حالة هنا قابلة للإصلاح من جهة العميل، لذلك لا يُبلَّغ عن أي منها أبدًا كخطأ 5xx.

application/json

معرّف طلب غير صالح

{
  "error": "invalid request id",
  "code": "VALIDATION_INVALID_UUID",
  "detail": "invalid request id",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

لغة غير صالحة

{
  "error": "invalid language",
  "code": "VALIDATION_INVALID_LANGUAGE",
  "detail": "invalid language",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

رفع ملف multipart غير صالح

{
  "error": "invalid file upload",
  "code": "VALIDATION_FILE_CORRUPT",
  "detail": "invalid file upload",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

حاوية الصوت خارج المجموعة المنشورة

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

{
  "error": "audio container is not supported; use AAC, FLAC, MP3, MP4 or WAV",
  "code": "ASR_UNSUPPORTED_CODEC",
  "detail": "audio container is not supported; use AAC, FLAC, MP3, MP4 or WAV",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

نموذج ASR غير مضبوط

{
  "error": "ASR model not found",
  "code": "ASR_MODEL_NOT_FOUND",
  "detail": "ASR model not found",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

غير مصرح

application/json

المثال missing_key

{
  "error": "Invalid authentication",
  "code": "AUTH_UNAUTHORIZED",
  "detail": "Invalid authentication",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

لا يمنح مفتاح API صلاحية الوصول إلى قدرة الصوت المطلوبة

application/json

المثال scope_denied

{
  "error": "scope not permitted",
  "code": "AUTH_FORBIDDEN",
  "detail": "scope not permitted",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

الطريقة غير مسموحة

application/json

المثال wrong_method

{
  "error": "method not allowed",
  "code": "METHOD_NOT_ALLOWED",
  "detail": "method not allowed",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

تجاوز جسم الطلب حد البايتات المضبوط لهذا المسار الصوتي: 64 MiB لرفع Fast، و16 MiB لإطارات ASR الفوري، و16 MiB لإطارات تمييز المتحدثين الفوري. وهو غير قابل لإعادة المحاولة بالحجم نفسه؛ أعد إرسال وحدة أو مقطع أصغر.

ويسمّي data.bound حد البايتات الذي تم بلوغه — fast_audio_bytes أو realtime_asr_frame_bytes أو realtime_diarization_frame_bytes. و data.observed هو حجم الطلب الدقيق عندما يعلن العميل Content-Length، وهو فيما عدا ذلك حد أدنى (الحد زائد بايت واحد)، لأن الجسم الذي لا يعلن طوله يُقطع في أثناء القراءة ولا يُعرف حجمه الحقيقي أبدًا.

ولا تُبلَغ هذه الحالة إلا من عدّ بايتات. أما الطلب المقبولة بايتاته والذي يطول صوته بعد فك الترميز فهو الحالة 422 برمز AUDIO_DURATION_EXCEEDED بدلًا منها.

application/json

أُعلن `Content-Length`، فالقيمة المرصودة دقيقة

{
  "error": "request body too large",
  "code": "PAYLOAD_TOO_LARGE",
  "detail": "request body too large",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 16777216,
    "observed": 20971520,
    "unit": "bytes",
    "bound": "realtime_asr_frame_bytes"
  }
}

لا طول معلن، فالقيمة المرصودة هي الحد زائد بايت واحد

{
  "error": "request body too large",
  "code": "PAYLOAD_TOO_LARGE",
  "detail": "request body too large",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 67108864,
    "observed": 67108865,
    "unit": "bytes",
    "bound": "fast_audio_bytes"
  }
}

حُلِّل الطلب بصورة صحيحة وكانت بايتاته مقبولة، لكن مقدار الصوت الذي يطلب من الخدمة معالجته يتجاوز سقف هذه النقطة (RFC 9110 15.5.21). ورفع مضغوط صغير يُفك إلى ساعات كثيرة هو هذه الحالة بالضبط، ولهذا لا تكون الحالة 413.

ويسمّي data.bound السقف الصوتي الذي تم بلوغه:

  • fast_audio_duration — إرسال Fast واحد فُك إلى أكثر من 1800 ثانية. قسّم التسجيل أو استخدم واجهة النسخ الدفعي.
  • session_audio_duration — أرسلت جلسة فورية الآن محتوى صوتيًا إجماليًا يزيد على حصتها البالغة 14400 ثانية (4 ساعات). وقد أُنهيت الجلسة؛ فابدأ جلسة جديدة.

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

وهي غير قابلة لإعادة المحاولة: فإعادة إرسال الصوت نفسه لا يمكن أن تنجح. قصّر الوحدة، أو انتقل إلى واجهة النسخ الدفعي.

application/json

المثال fast_decoded_audio_too_long

{
  "error": "decoded audio duration exceeds the maximum for this endpoint; split the recording or use the batch transcription API",
  "code": "AUDIO_DURATION_EXCEEDED",
  "detail": "decoded audio duration exceeds the maximum for this endpoint; split the recording or use the batch transcription API",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 1800,
    "observed": 3601,
    "unit": "seconds",
    "bound": "fast_audio_duration"
  }
}

المثال session_audio_allowance_spent

{
  "error": "session maximum audio duration exceeded; start a new session",
  "code": "AUDIO_DURATION_EXCEEDED",
  "detail": "session maximum audio duration exceeded; start a new session",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 14400,
    "observed": 14401,
    "unit": "seconds",
    "bound": "session_audio_duration"
  }
}

تحديد المعدل في البوابة. تعتمد تفاصيل الاستجابة وترويسات إعادة المحاولة على النشر.

فشل نسخ Fast قبل إصدار سجل نهائي

application/json

المثال transcription_failed

{
  "error": "STT transcription failed",
  "code": "ASR_TRANSCRIPTION_FAILED",
  "detail": "STT transcription failed",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

الخطوات التالية

استخدم Fast فقط بعد اكتمال وحدة صوت حوارية محدودة واحدة. حلّل كل سجل NDJSON، ولا تثبّت الناتج إلا من سجل نهائي، وأبقِ التسجيلات الطويلة مثل البودكاست والاجتماعات على Batch.

نفّذ تدفق HTTP

تعامل مع إدخال multipart وسجلات NDJSON والنهائية والمواعيد والتنظيف.

قارن وسيلة SDK

استخدم Socket.IO عندما تناسب SDK المنشورة لـJavaScript أو Python بيئة تشغيلك.

تعامل مع إخفاقات التدفق

تعرّف على أخطاء التدفق المنظمة وإخفاقات HTTP على مستوى البوابة.

واجهة Realtime HTTP

عمليات HTTP مباشرة لوحدة Fast المكتملة والصوت الذي ما زال يصل وتمييز المتحدثين وتسجيل بروتوكول TTS.

بث ASR مباشر من صوت ما زال يصل

أرسل إطارات PCM16 متسلسلة واستقبل صفرًا أو أكثر من نتائج النسخ الجزئية والنهائية لكل طلب.

في هذه الصفحة

الخطوات التالية