أدلة API

واجهة Socket.IO

اتصل بـHUMAIN Voice عبر Socket.IO وتبادل الأحداث الخام والإطارات الثنائية للنسخ السريع والنسخ الفوري وتمييز المتحدثين المباشر والاستعلام عن الأصوات وتحويل النص إلى كلام.

استخدم هذا البروتوكول مباشرة عندما لا تملك بيئة التشغيل حزمة SDK لـHUMAIN Voice. تبني حزم SDK لـJavaScript وPython هذه الإطارات نيابة عنك.

الاتصال

يخدم اتصال واحد كل سير عمل. أرسل x-api-key وOrigin كترويسات HTTP في طلب ترقية WebSocket، واستخدم وسيلة نقل WebSocket؛ فالاستعلام الدوري غير مدعوم. التفاصيل والمسار القديم: المصادقة.

import { io } from "socket.io-client";

const API_URL = process.env.API_URL!;
const socket = io(API_URL, {
  path: process.env.API_PATH ?? "/socket.io",
  transports: ["websocket"],
  extraHeaders: {
    "x-api-key": process.env.API_KEY!,
    Origin: new URL(API_URL).origin,
  },
});

// Binary frames carry the request UUID as 16 raw bytes.
const uuidBytes = (id: string) => Buffer.from(id.replaceAll("-", ""), "hex");

socket.on("error", (err) => console.error("error:", err));
await new Promise((resolve, reject) => {
  socket.once("connect", resolve);
  socket.once("connect_error", reject);
});

يتحدث الخادم بروتوكول Socket.IO الإصدار 5 (Engine.IO الإصدار 4، أي socket.io-client الإصدار 3.x أو 4.x) على فضاء الأسماء الافتراضي /. تحمل الإطارات الثنائية معرفات UUID بوصفها 16 بايت بترتيب RFC 4122، وهو ترتيب السلسلة السداسية عشرية نفسه.

أعطِ كل طلب أو تدفق UUID خاصًا به؛ تعيده الاستجابات في id، فوجّه النتائج به. تصل الإخفاقات على الحدث error مع code وretryable وid عندما يمكن تحليله؛ راجع الأخطاء والحدود.

أحداث النسخ السريع

الحدثالاتجاهالحمولة
audio_fileإرسالالحزمة الثنائية أدناه.
audio_file_upload_successاستقبال{ id }. إيصال فقط: قد يتبعه خطأ error في الصيغة أو المدة.
transcription_resultاستقبالid، seq، transcription، words (start_time، end_time، word)، is_final.
errorاستقبالخطأ منظم.

أرسل الملف كاملًا بايتات خامًا، لا JSON ولا base64. حقول الأطوال أعداد صحيحة بلا إشارة بحجم 16 بت بترتيب little-endian.

حزمة audio_file
الحقلالبايتاتالقيمة والمعنى
UUID0–15معرّف الطلب.
Language160 = ar، 1 = en، 2 = codeswitch، 255 = auto.
ASR key length17–18طول مفتاح النموذج N؛ القيمة 0 تختار النموذج الافتراضي للغة.
ASR keyN bytesمفتاح النموذج بترميز UTF-8، مثل bayan_cs_ar_en.
Reserved keys19+N–24+Nأطوال مفاتيح التمييز وITN والتنقيح. أرسل 6 بايتات أصفار.
Audio25+N–endملف الصوت كاملًا بصيغة AAC أو FLAC أو MP3 أو MP4 أو WAV.

ضع العنصر moov في ملف MP4 في المقدمة: يُقرأ الرفع للأمام فقط، فيفشل فك ترميز ملف يقع moov فيه في النهاية. قيم اللغات ومفاتيح النماذج في النماذج.

import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";

const key = Buffer.from("bayan_cs_ar_en");
const len = (n: number) => { const b = Buffer.alloc(2); b.writeUInt16LE(n); return b; };
const fastId = randomUUID();

socket.on("transcription_result", (r) => {
  if (r.id === fastId && r.is_final) console.log("final:", r.transcription);
});
socket.emit("audio_file", Buffer.concat([
  uuidBytes(fastId), Buffer.of(2), len(key.length), key,
  len(0), len(0), len(0), readFileSync("recording.wav"),
]));

ينتهي الطلب عند transcription_result مع is_final: true. المخططات الكاملة: أحداث النسخ السريع.

أحداث النسخ الفوري

الحدثالاتجاهالحمولة
audio_streamإرسالالإطار الثنائي أدناه؛ يعيد transcription_result.
diarization_streamإرسالالإطار نفسه؛ يعيد diarization_result فقط.
transcription_resultاستقبالid، seq، transcription، words، is_final، is_speech_final.
diarization_resultاستقبالid، final_segments، active_segments (start_time، end_time، speaker)، is_final.
errorاستقبالخطأ منظم.

يعيد الحدث المتقادم speaker_id الخطأ METHOD_NOT_ALLOWED.

إطار audio_stream وdiarization_stream
الحقلالبايتاتالقيمة والمعنى
UUID0–15UUID نفسه لكل إطار في تدفق واحد.
Flags16البت 0 للبدء، والبت 1 للنهاية، والبت 2 لتفرع التمييز؛ وبقية البتات 0.
Language170 = ar، 1 = en، 2 = codeswitch، 255 = auto. يقبل التمييز أيًا من هذه القيم ويتجاهلها.
PCM18–endPCM16 little-endian، بتردد 16 kHz وأحادي القناة؛ بطول زوجي غير صفري.
الإطارعلامات audio_streamمع تفرع التمييز
الأول15
الأوسط04
الأخير26
إطار وحيد37

يرسل البت 2 صوت ذلك الإطار إلى التمييز، وتصل أحداث diarization_result على الاتصال نفسه بالقيمة id نفسها. اضبطه في كل إطار من التدفق: الإطارات التي لا تحمله لا تصل إلى التمييز، والتدفق المتفرع جزئيًا لا يحصل على نتيجة تمييز نهائية وينتهي بالخطأ DIARIZATION_FAILED. في diarization_stream، استخدم البتين 0 و1 فقط. أرسل 3,200 بايت (100 ms) لكل إطار بوتيرة الزمن الحقيقي. يرفض الخادم الإطار الأقصر من 18 بايت، أو ذا UUID كله أصفار، أو بت علامة غير معرّف، أو بايت لغة غير معروف، أو صوتًا فارغًا أو بطول فردي.

const streamId = randomUUID();
socket.on("transcription_result", (r) => {
  if (r.id === streamId) console.log(r.is_final ? "final:" : "partial:", r.transcription);
});
const pcm = readFileSync("recording.pcm");
for (let off = 0; off < pcm.length; off += 3200) {
  const flags = (off === 0 ? 1 : 0) | (off + 3200 >= pcm.length ? 2 : 0);
  socket.emit("audio_stream", Buffer.concat([uuidBytes(streamId), Buffer.of(flags, 2 /* codeswitch */), pcm.subarray(off, off + 3200)]));
  await new Promise((r) => setTimeout(r, 100));
}

بعد الإطار الأخير، واصل الاستماع حتى تصل نتيجة مع is_final: true. مع التفرع، يرسل transcription_result وdiarization_result كل منهما is_final: true خاصًا به، وقد تصل نتيجة التمييز لاحقًا، فانتظر الاثنتين. لتطبيق النتائج المؤقتة والنهائية ودمج مقاطع المتحدثين، راجع المفاهيم. المخططات الكاملة: أحداث Realtime.

أحداث تحويل النص إلى كلام

الحدثالاتجاهالحمولة
ttsإرسالطلب JSON أدناه.
tts_audioاستقبالالإطار الثنائي أدناه.
errorاستقبالخطأ منظم.
الحقلمطلوبالقيمة
idنعمUUID الطلب.
textنعمنص عادي، لا SSML، يحوي حرفًا أو رقمًا واحدًا على الأقل. حدود الطول.
modelلا (أرسل nebula)nebula. عند حذفه يُطبَّق الافتراضي للنشر.
voice_idأحدهماid لملف صوت من قائمة الأصوات.
voice_referencesأحدهماعنصر واحد { audio, text }: ملف WAV بصيغة PCM16 أحادي القناة بترميز base64 القياسي (بلا فواصل أسطر وغير آمن للعناوين) ونصه المنسوخ.
إطار tts_audio
الحقلالبايتاتالقيمة والمعنى
UUID0–15معرّف الطلب.
Header16البت 0 مضبوط في الإطار الأخير؛ وبقية البتات 0.
PCM17–endPCM16 little-endian، بتردد 24 kHz وأحادي القناة، بلا ترويسة WAV.

أضف البايتات من 17 فصاعدًا من كل إطار يخص id الخاص بك، بما فيها الإطار الأخير. تأتي voiceId من قائمة الأصوات.

const ttsId = randomUUID();
const chunks: Buffer[] = [];
socket.on("tts_audio", (data: ArrayBuffer) => {
  const frame = Buffer.from(data);
  if (!frame.subarray(0, 16).equals(uuidBytes(ttsId))) return;
  chunks.push(frame.subarray(17));
  if (frame[16] & 1) console.log("done:", Buffer.concat(chunks).length, "bytes");
});
socket.emit("tts", { id: ttsId, text: "مرحبًا من HUMAIN Voice", model: "nebula", voice_id: voiceId });

ينتهي التوليف الذي يتجاوز 25 ثانية بالخطأ TTS_DEADLINE_EXCEEDED القابل لإعادة المحاولة؛ فتخلص من الصوت الجزئي. لجعل PCM قابلًا للتشغيل، راجع تحويل النص إلى كلام: الحفظ أو البث. المخططات الكاملة: أحداث TTS.

قائمة الأصوات

أرسل tts_voice_list مع {}؛ يجيب الخادم بحدث tts_voice_list_result واحد يحمل مصفوفة من ملفات الأصوات. لكل عنصر id وlabel وprofile:

[
  {
    "id": "42e38a63-849a-481a-b5bf-3c1b7a985de3",
    "label": "mul_nourah",
    "profile": { "speaker": { "gender": "female", "dialect": "ars" }, "languages": ["ar", "en"] }
  }
]
const voices = await new Promise<{ id: string; label: string }[]>((resolve) => {
  socket.once("tts_voice_list_result", resolve);
  socket.emit("tts_voice_list", {});
});
const voiceId = voices[0]?.id;

يصدر فشل الاستعلام الخطأ TTS_VOICE_LIST_FAILED على error بلا id، فقيّد الانتظار بمهلة. تختلف المعرفات بين البيئات، والمصفوفة الفارغة إجابة صالحة. معاني الحقول والأصوات الحالية في النماذج.

انقطاع الاتصال

تذهب النتائج إلى الاتصال الذي أرسل الطلب فقط. لا يُستأنف شيء بعد إعادة الاتصال؛ ولا يوجد عقد لإعادة التشغيل.

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

يقطع الخادم اتصالك بعد هذه الأخطاء، ويصدر الحدث error دائمًا أولًا:

الخطأالمحفز
PAYLOAD_TOO_LARGEرفع سريع يتجاوز 64 MiB، أو إطار فوري يتجاوز 16 MiB.
CREDITS_EXHAUSTEDنفد رصيد الحساب في منتصف التدفق.
BILLING_AUTHORIZATION_UNAVAILABLEتعذر على الفوترة ترخيص التدفق في منتصفه.

لا يحمل انقطاع Socket.IO رمز إغلاق على مستوى التطبيق؛ فاعتبر الحدث error هو الإشارة.

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

في هذه الصفحة