أدلة API

واجهة البث عبر HTTP

استدعِ مسارات البث عبر HTTP في HUMAIN Voice مباشرة لنسخ مقطع، وبث الصوت المباشر للنسخ أو تمييز المتحدثين، والتقاط إطارات تحويل النص إلى كلام.

تستخدم حزم SDK Socket.IO ولا تستدعي هذه المسارات. استخدمها من خلفية تحتفظ بمفتاح API، وأرسله في x-api-key. لا تحتاج إلى ترويسة Origin (المصادقة).

المسارات

تقبل كل المسارات POST تحت $API_URL/realtime/http/.

المسارجسم الطلبالاستجابةاستخدمه لـ
sttmultipart/form-data مع file واحدسجلات نسخ بصيغة NDJSONمقطع واحد قصير مكتمل، مثل دور مستخدم منتهٍ
stt-streamقطعة PCM مؤطرة واحدة (application/octet-stream)سجلات نسخ بصيغة NDJSONالنسخ المباشر أثناء وصول الصوت
diarization-streamقطعة PCM مؤطرة واحدةسجلات مقاطع متحدثين بصيغة NDJSONالخط الزمني المباشر للمتحدثين، بلا نص
ttsJSONPCM مؤطر بتردد 16 kHz (application/octet-stream)تسجيل بروتوكول للكلام المولّف

للتسجيلات الطويلة، استخدم النسخ الدفعي. أي سير عمل يناسب أي مهمة في المفاهيم.

المحددات والأسبقية

يقبل stt وحده معاملات الاستعلام. تحمل مسارات البث اللغة في ترويسة الإطار، وتختار الخدمة النموذج.

المعاملمطلوبالقيمة
idنعمUUID جديد لكل طلب، يُعاد في كل سجل. إعادة استخدامه لا تزيل التكرار.
languageلاen أو ar أو codeswitch أو auto. عند حذفه أو auto تُستخدم القيمة الافتراضية للبيئة.
langلااسم بديل لـlanguage، يُقرأ عندما تكون language مفقودة أو فارغة.
asrلامفتاح نموذج ASR. عند حذفه تستخدم الخدمة الافتراضي للغة.
modelلااسم بديل لـasr، يُقرأ عندما تكون asr مفقودة أو فارغة.

تتقدم language غير الفارغة على lang، وتتقدم asr غير الفارغة على model. القيمة غير الصالحة في المعامل الغالب تعيد 400 حتى لو كان البديل صالحًا. قيم اللغات ومفاتيح النماذج في النماذج.

curl -sS -N -X POST "$API_URL/realtime/http/stt?id=$(uuidgen)&language=codeswitch&asr=bayan_cs_ar_en" \
  -H "x-api-key: $API_KEY" \
  -F "[email protected]"

الاستجابة بصيغة NDJSON. اقرأ السجلات حتى يظهر سجل فيه is_final: true:

{"id":"8b356f13-1caa-4487-a06c-48728c46906d","seq":0,"transcription":"Yeah, I mean, look, …","words":[{"start_time":0.14,"end_time":0.38,"word":"Yeah,"}],"is_final":true}

صيغ الملفات المقبولة وحدود الحجم في المفاهيم والحدود.

صيغة الإطار

كل جسم POST إلى stt-stream وdiarization-stream هو إطار واحد: ترويسة من 18 بايت يتبعها PCM خام. وهو التخطيط نفسه لإطار audio_stream في Socket.IO بلا بت التمييز.

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

يحمل كل إطار صوتًا؛ ولا يوجد إطار إنهاء فارغ، فاضبط بت النهاية في آخر قطعة فعلية. يعيد الإطار الأقصر من 18 بايت، أو الذي يحمل بتًا محجوزًا، أو UUID صفريًا، أو بايت لغة غير معروف، أو PCM فارغًا أو بطول فردي، الخطأ 400. حوّل التسجيل إلى recording.pcm بأمر ffmpeg في النسخ الفوري.

يؤطر هذا المثال recording.pcm كتدفق من إطار واحد ويكتب frame.bin. لتدفق أطول، أعد استخدام STREAM_ID واضبط IS_START=0 أو IS_FINAL=0 لكل قطعة.

http-realtime-frame.ts
import { randomUUID } from 'node:crypto';
import { readFile, writeFile } from 'node:fs/promises';

const languageBytes = {
  ar: 0,
  en: 1,
  codeswitch: 2,
  auto: 255,
} as const;

function uuidBytes(id: string): Uint8Array {
  const hex = id.replaceAll('-', '');
  if (!/^[0-9a-f]{32}$/i.test(hex) || /^0{32}$/.test(hex)) {
    throw new Error('STREAM_ID must be a nonzero UUID');
  }
  return Uint8Array.from(hex.match(/.{2}/g)!, (byte) => Number.parseInt(byte, 16));
}

function frame(
  id: string,
  pcm16le: Uint8Array,
  options: { language: keyof typeof languageBytes; isStart: boolean; isFinal: boolean },
): Uint8Array {
  if (pcm16le.byteLength === 0 || pcm16le.byteLength % 2 !== 0) {
    throw new Error('PCM16 payload must be nonempty and contain an even number of bytes');
  }

  const output = new Uint8Array(18 + pcm16le.byteLength);
  output.set(uuidBytes(id), 0);
  output[16] = (options.isStart ? 1 : 0) | (options.isFinal ? 2 : 0);
  output[17] = languageBytes[options.language];
  output.set(pcm16le, 18);
  return output;
}

async function main(): Promise<void> {
  const inputPath = process.argv[2] ?? 'recording.pcm';
  const outputPath = process.argv[3] ?? 'frame.bin';
  const streamId = process.env.STREAM_ID ?? randomUUID();
  const pcm = await readFile(inputPath);

  // Defaults frame a one-chunk stream; reuse STREAM_ID and set IS_START/IS_FINAL for longer ones.
  const body = frame(streamId, pcm, {
    language: 'codeswitch',
    isStart: process.env.IS_START !== '0',
    isFinal: process.env.IS_FINAL !== '0',
  });
  await writeFile(outputPath, body);
  console.info('status:', 'framed', streamId, body.byteLength, outputPath);
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي):

status: framed f2e3e25d-f091-4a96-a5ab-7c8468529d3a 2323490 frame.bin

استخدم إطارات مدتها 1 s لـstt-stream وdiarization-stream؛ ويبني هذا المثال إطارًا واحدًا للتوضيح.

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

أرسل إطارًا واحدًا لكل POST إلى stt-stream فور وصول الصوت وبالترتيب، مع إعادة استخدام UUID التدفق.

  • أرسل نحو 1 s من الصوت (32,000 بايت) لكل POST. بينما ينتظر POST استجابته، ضع الصوت الجديد في طابور وأرسل كل ما تجمع كالإطار التالي.
  • أرسل POST واحدًا في كل مرة لكل UUID تدفق، كما تفعل الأمثلة. في diarization-stream، لا تُدعم طلبات POST المتزامنة لـUUID واحد؛ ولا يعرّفها عقد stt-stream.
  • اضبط مهلة لكل POST (تستخدم الأمثلة 30 s). انتهاء مهلة الاستجابة النهائية يلغي التدفق.
curl -sS -N -X POST "$API_URL/realtime/http/stt-stream" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/octet-stream" \
  --data-binary @frame.bin

تحمل كل استجابة 200 صفرًا أو أكثر من سجلات NDJSON فيها id وseq وtranscription وwords وis_speech_final وis_final:

{"id":"f2e3e25d-f091-4a96-a5ab-7c8468529d3a","seq":0,"transcription":"وبالتالي بنجاح تام","words":[{"start_time":20.19,"end_time":20.67,"word":"وبالتالي"},{"start_time":20.67,"end_time":21.27,"word":"بنجاح"},{"start_time":21.27,"end_time":22.13,"word":"تام"}],"is_final":false,"is_speech_final":true}
{"id":"f2e3e25d-f091-4a96-a5ab-7c8468529d3a","seq":0,"transcription":"في الفضاء","words":[{"start_time":71.48,"end_time":71.64,"word":"في"},{"start_time":71.64,"end_time":72.55,"word":"الفضاء"}],"is_final":true,"is_speech_final":true}
  • خزّن الجسم مؤقتًا وقسّمه عند أسطر جديدة؛ فقد تحمل قراءة شبكة واحدة جزءًا من سجل أو عدة سجلات.
  • تُغلق استجابة قطعة غير نهائية بعد ثانيتين على الأكثر. هذا طبيعي: تبقى الجلسة مفتوحة، وتصل السجلات اللاحقة على استجابات لاحقة.
  • تبقى استجابة القطعة النهائية مفتوحة حتى ترسل الخدمة is_final: true. استجابة 200 فارغة أو استجابة مغلقة لا تعني نهاية التدفق.
  • بعد وصول أول مقطع صوت إلى الاستدلال، ينتهي تدفق ASR غير المكتمل بعد 60 ثانية من دون تمرير مقطع صوت آخر. لا تعيد استجابات الاستدلال ضبط هذه المهلة.
  • إلغاء POST يلغي التدفق. بعد فشل POST لا يُستأنف شيء، فابدأ من جديد بـUUID جديد. الاستثناء هو تقييد 429 SESSION_BYTE_RATE_EXCEEDED، إذ تبقى الجلسة حية.

يستخدم مثال التمييز أدناه حلقة الإرسال نفسها. لـstt-stream، غيّر المسار وعالج سجلات النسخ كما في المفاهيم.

تمييز المتحدثين المباشر

يقبل diarization-stream الإطارات نفسها ويعيد خطًا زمنيًا للمتحدثين. لا معاملات استعلام له ولا محدد نموذج.

أبقِ POST واحدًا على الأكثر قيد التنفيذ لكل UUID تدفق: قد تُسلَّم السجلات إلى استجابة خاطئة عند تزامن طلبات POST لـUUID نفسه. اجعل مرسلًا واحدًا يقرأ كل استجابة حتى نهايتها قبل إرسال الإطار التالي. يمكن لتدفقات ذات UUID مختلفة أن تعمل بالتوازي.

لكل سجل id وfinal_segments وactive_segments وis_final. أضف final_segments من كل سجل إلى خطك الزمني، واستبدل active_segments السابقة، وانته عند is_final: true. قد يحمل السجل النهائي مقاطع نشطة؛ فاحتفظ بها كمؤقتة. التسميات نسبية للتدفق (الخطوط الزمنية للمتحدثين).

يبث هذا المثال recording.pcm بإطارات مدتها 1 s (32,000 بايت)، بطلب POST واحد في كل مرة، مستخدمًا حلقة الإرسال من النسخ المتدفق، ويكتب الخط الزمني في recording.rttm.

http-diarization-stream.ts
import { randomUUID } from 'node:crypto';
import { readFile, writeFile } from 'node:fs/promises';

type Segment = { start_time: number; end_time: number; speaker: string };
type DiarizationRecord = {
  final_segments?: Segment[];
  active_segments?: Segment[];
  is_final?: boolean;
};

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

function frame(
  id: string,
  pcm: Uint8Array,
  isStart: boolean,
  isFinal: boolean,
): Uint8Array<ArrayBuffer> {
  const hex = id.replaceAll('-', '').match(/.{2}/g)!;
  const output = new Uint8Array(18 + pcm.byteLength);
  output.set(Uint8Array.from(hex, (byte) => Number.parseInt(byte, 16)), 0);
  output[16] = (isStart ? 1 : 0) | (isFinal ? 2 : 0);
  output[17] = 2; // code-switch; ignored by diarization but must be valid.
  output.set(pcm, 18);
  return output;
}

function toRttm(segments: Segment[], uri: string): string {
  return segments
    .map(
      (s) =>
        `SPEAKER ${uri} 1 ${s.start_time.toFixed(3)} ` +
        `${(s.end_time - s.start_time).toFixed(3)} <NA> <NA> ${s.speaker} <NA> <NA>\n`,
    )
    .join('');
}

async function main(): Promise<void> {
  const inputPath = process.argv[2] ?? 'recording.pcm';
  const outputPath = process.argv[3] ?? 'recording.rttm';
  const url = `${requiredEnv('API_URL')}/realtime/http/diarization-stream`;
  const apiKey = requiredEnv('API_KEY');
  const pcm = await readFile(inputPath);
  const streamId = randomUUID();
  const chunkBytes = 32_000;

  const finalized: Segment[] = [];
  let active: Segment[] = [];
  let done = false;

  for (let offset = 0; offset < pcm.byteLength && !done; offset += chunkBytes) {
    const chunk = pcm.subarray(offset, offset + chunkBytes);
    const isFinal = offset + chunkBytes >= pcm.byteLength;
    const response = await fetch(url, {
      method: 'POST',
      headers: { 'x-api-key': apiKey, 'content-type': 'application/octet-stream' },
      body: frame(streamId, chunk, offset === 0, isFinal),
      signal: AbortSignal.timeout(30_000),
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);

    for (const line of (await response.text()).split('\n')) {
      if (!line.trim()) continue;
      const record = JSON.parse(line) as DiarizationRecord;
      finalized.push(...(record.final_segments ?? []));
      active = record.active_segments ?? [];
      if (record.is_final) done = true;
    }
  }
  if (!done) throw new Error('stream ended without a final record');

  const timeline = [...finalized, ...active].sort((a, b) => a.start_time - b.start_time);
  await writeFile(outputPath, toRttm(timeline, 'recording'), 'utf8');
  console.info('status:', 'segments', timeline.length);
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

الخرج المتوقع (توضيحي):

status: segments 26

ثم يحوي recording.rttm سطرًا لكل مقطع:

SPEAKER recording 1 0.080 1.680 <NA> <NA> SPEAKER_01 <NA> <NA>
SPEAKER recording 1 1.920 5.840 <NA> <NA> SPEAKER_01 <NA> <NA>

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

يقبل جسم JSON الحقول نفسها لحدث tts في Socket.IO: id وtext وmodel وواحدًا من voice_id أو voice_references (جدول الحقول). أرسل model: "nebula". لا توجد قائمة أصوات عبر HTTP؛ احصل على voice_id من قائمة الأصوات.

curl -sS -X POST "$API_URL/realtime/http/tts" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --data '{"id":"7f51f2c2-e7bc-41c8-a850-f848df2ddfc8","text":"مرحبًا من HUMAIN Voice","model":"nebula"}' \
  --output tts-frames.bin

من دون voice_id أو voice_references، يختار النشر الصوت.

جسم 200 سلسلة من إطارات الخدمة، لكل منها التخطيط أدناه، بلا حقل طول أو فاصل بينها:

إطار خدمة TTS عبر HTTP
الحقلالبايتاتالقيمة والمعنى
UUID0–15معرّف الطلب.
Final161 في الإطار الأخير؛ وإلا 0.
PCM17–endPCM16 little-endian، بتردد 16 kHz وأحادي القناة.

لا يمكن تشغيل tts-frames.bin كـPCM خام أو WAV: ترويسات الإطارات داخل الصوت، ولا تتوافق قراءات HTTP مع حدود الإطارات، فلا يمكنك إزالتها بموثوقية. للحصول على صوت قابل للتشغيل، استخدم SDK أو TTS عبر Socket.IO، الذي يسلّم إطارات 24 kHz بإطار واحد لكل حدث. إلغاء الطلب يلغي توليفه.

الأخطاء

تصل الأخطاء قبل بدء الخرج كجسم JSON من نوع ErrorResponse. اتخذ القرار من code وretryable.

الحالةعلى هذه المسارات
400id أو محدد أو ترويسة إطار أو PCM غير صالح، أو تدفق تمييز بلا إطار بدء، أو إدخال TTS غير صالح.
408SESSION_IDLE_TIMEOUT: توقف التدفق عن إرسال الصوت. ابدأ بـUUID جديد.
409SESSION_EXPIRED: لم يبدأ UUID قط، أو انتهى، أو بدأ مرتين.
413الجسم يتجاوز حد البايتات للمسار.
422الصوت المفكوك أو صوت الجلسة أو نص TTS يتجاوز حده.
500فشل الاستدلال (ASR_TRANSCRIPTION_FAILED أو DIARIZATION_FAILED أو TTS_SYNTHESIS_FAILED).
429SESSION_BYTE_RATE_EXCEEDED: انتظر Retry-After ثم أعد إرسال الإطار نفسه؛ تبقى الجلسة حية. CONCURRENCY_LIMIT_EXCEEDED / SESSION_SLOTS_EXHAUSTED: راجع الأخطاء والحدود.
503تعذر على تبعية مثل الفوترة أو إشراف TTS أن تقرر؛ قابل لإعادة المحاولة.
504TTS_DEADLINE_EXCEEDED: تجاوز التوليف 25 s قبل بدء الخرج؛ قابل لإعادة المحاولة.

الفشل بعد بدء الخرج ينهي استجابة 200 بلا JSON للخطأ: يتوقف NDJSON قبل is_final: true، ويتوقف جسم TTS قبل إطاره النهائي. اعتبر ذلك ناقصًا، وافصل النتائج الجزئية، وأعد المحاولة بـUUID جديد (وبعد تقييد 429 أعد إرسال الإطار نفسه). لا توجد إعادة تشغيل ولا idempotency في هذه المسارات، فلا تعد إرسال رفع stt مكتمل دون تحقق. الرموز والحدود ومصادر 429 وقواعد إعادة المحاولة في الأخطاء والحدود.

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

في هذه الصفحة