واجهة البث عبر HTTP
استدعِ مسارات البث عبر HTTP في HUMAIN Voice مباشرة لنسخ مقطع، وبث الصوت المباشر للنسخ أو تمييز المتحدثين، والتقاط إطارات تحويل النص إلى كلام.
تستخدم حزم SDK Socket.IO ولا تستدعي هذه المسارات. استخدمها من خلفية تحتفظ بمفتاح API، وأرسله في x-api-key. لا تحتاج إلى ترويسة Origin (المصادقة).
المسارات
تقبل كل المسارات POST تحت $API_URL/realtime/http/.
| المسار | جسم الطلب | الاستجابة | استخدمه لـ |
|---|---|---|---|
stt | multipart/form-data مع file واحد | سجلات نسخ بصيغة NDJSON | مقطع واحد قصير مكتمل، مثل دور مستخدم منتهٍ |
stt-stream | قطعة PCM مؤطرة واحدة (application/octet-stream) | سجلات نسخ بصيغة NDJSON | النسخ المباشر أثناء وصول الصوت |
diarization-stream | قطعة PCM مؤطرة واحدة | سجلات مقاطع متحدثين بصيغة NDJSON | الخط الزمني المباشر للمتحدثين، بلا نص |
tts | JSON | PCM مؤطر بتردد 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 بلا بت التمييز.
| الحقل | البايتات | القيمة والمعنى |
|---|---|---|
| UUID | 0–15 | UUID نفسه غير الصفري لكل إطار في تدفق واحد. |
| Flags | 16 | البت 0 للبدء، والبت 1 للنهاية؛ وبقية البتات 0. |
| Language | 17 | 0 = ar، 1 = en، 2 = codeswitch، 255 = auto. يقبل التمييز أيًا من هذه القيم ويتجاهلها. |
| PCM | 18–end | PCM16 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 لكل قطعة.
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.
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 سلسلة من إطارات الخدمة، لكل منها التخطيط أدناه، بلا حقل طول أو فاصل بينها:
| الحقل | البايتات | القيمة والمعنى |
|---|---|---|
| UUID | 0–15 | معرّف الطلب. |
| Final | 16 | 1 في الإطار الأخير؛ وإلا 0. |
| PCM | 17–end | PCM16 little-endian، بتردد 16 kHz وأحادي القناة. |
لا يمكن تشغيل tts-frames.bin كـPCM خام أو WAV: ترويسات الإطارات داخل الصوت، ولا تتوافق قراءات HTTP مع حدود الإطارات، فلا يمكنك إزالتها بموثوقية. للحصول على صوت قابل للتشغيل، استخدم SDK أو TTS عبر Socket.IO، الذي يسلّم إطارات 24 kHz بإطار واحد لكل حدث. إلغاء الطلب يلغي توليفه.
الأخطاء
تصل الأخطاء قبل بدء الخرج كجسم JSON من نوع ErrorResponse. اتخذ القرار من code وretryable.
| الحالة | على هذه المسارات |
|---|---|
400 | id أو محدد أو ترويسة إطار أو PCM غير صالح، أو تدفق تمييز بلا إطار بدء، أو إدخال TTS غير صالح. |
408 | SESSION_IDLE_TIMEOUT: توقف التدفق عن إرسال الصوت. ابدأ بـUUID جديد. |
409 | SESSION_EXPIRED: لم يبدأ UUID قط، أو انتهى، أو بدأ مرتين. |
413 | الجسم يتجاوز حد البايتات للمسار. |
422 | الصوت المفكوك أو صوت الجلسة أو نص TTS يتجاوز حده. |
500 | فشل الاستدلال (ASR_TRANSCRIPTION_FAILED أو DIARIZATION_FAILED أو TTS_SYNTHESIS_FAILED). |
429 | SESSION_BYTE_RATE_EXCEEDED: انتظر Retry-After ثم أعد إرسال الإطار نفسه؛ تبقى الجلسة حية. CONCURRENCY_LIMIT_EXCEEDED / SESSION_SLOTS_EXHAUSTED: راجع الأخطاء والحدود. |
503 | تعذر على تبعية مثل الفوترة أو إشراف TTS أن تقرر؛ قابل لإعادة المحاولة. |
504 | TTS_DEADLINE_EXCEEDED: تجاوز التوليف 25 s قبل بدء الخرج؛ قابل لإعادة المحاولة. |
الفشل بعد بدء الخرج ينهي استجابة 200 بلا JSON للخطأ: يتوقف NDJSON قبل is_final: true، ويتوقف جسم TTS قبل إطاره النهائي. اعتبر ذلك ناقصًا، وافصل النتائج الجزئية، وأعد المحاولة بـUUID جديد (وبعد تقييد 429 أعد إرسال الإطار نفسه). لا توجد إعادة تشغيل ولا idempotency في هذه المسارات، فلا تعد إرسال رفع stt مكتمل دون تحقق. الرموز والحدود ومصادر 429 وقواعد إعادة المحاولة في الأخطاء والحدود.