واجهة تحويل النص إلى كلام المتوافقة مع OpenAI
استدعِ POST /v1/audio/speech لتحويل نص إلى كلام بنمط ملف كامل، يعيد ملفًا صوتيًا واحدًا بصيغة MP3 أو WAV أو PCM.
يحوّل POST /v1/audio/speech نصًا واحدًا إلى ملف صوتي واحد. وبالنسبة للحقول التي تقبلها v1
فهو يتبع شكل طلب تحويل النص إلى كلام في OpenAI؛ يوجّه عميل OpenAI عنوان الأساس نحو https://api.voice.humain.com/v1
ويملأ الطلب أدناه (يلزم UUID صوت لأي صوت غير افتراضي). تخزّن الخدمة المقطع كاملًا
وتعيده في جسم واحد، ولا تبثّ هذه الواجهة شيئًا أثناء التوليد. للصوت الذي يجب أن يصل أثناء توليده،
استخدم تحويل النص إلى كلام عبر Socket.IO.
هذه الواجهة متاحة اليوم على voice-dev فقط. ستأتي بيئتا الاختبار والإنتاج لاحقًا؛ ما ورد لاحقًا
في هذه الصفحة يخص بيئة التطوير.
المصادقة
أرسل مفتاحك في الترويسة x-api-key كما في كل مسار HTTP آخر (المصادقة).
تقبل هذه الواجهة أيضًا الترويسة Authorization: Bearer <key>، لأن عملاء OpenAI يرسلون المفتاح
بهذه الطريقة وحدها. وللمفتاح الثابت، تفوز x-api-key عند وصول الترويستين معًا.
الطلب
جسم الطلب بصيغة JSON.
| الحقل | الموضع | مطلوب | القيمة |
|---|---|---|---|
model | الجسم | لا | nebula فقط. عند حذفه، يُطبَّق النموذج الافتراضي للنشر (nebula). القيمة القديمة من مزوّد آخر، مثل tts-1، تعيد 400 TTS_MODEL_NOT_FOUND. |
input | الجسم | نعم | النص العادي المراد نطقه. تُطبَّق حدود نقاط ترميز Unicode على الخادم: 500 نقطة ترميز للحسابات المجانية و1,000 للقياسية والمؤسسية. راجع حدود تحويل النص إلى كلام. |
voice | الجسم | لا | معرّف UUID لملف تعريف صوت، أو كائن {"id": "<uuid>"}. عند حذفه، أو عند سلسلة فارغة، ينطق الصوت الافتراضي للنشر. تعمل أصوات UUID فقط على هذه الواجهة في v1: فهي لا تقبل صوت الاستنساخ المرجعي، وأي قيمة حاضرة أخرى (اسم أو null أو {}) تعيد 400. اختر UUID لبيئتك من قائمة الأصوات؛ فالقيم تختلف بين البيئات، وقد لا توجد قيمة المثال أدناه في بيئتك. ولا يوجد مسار HTTP لقائمة الأصوات؛ اعرض الأصوات عبر حزمة SDK أو عبر حدث الصوت في Socket.IO. |
response_format | الجسم | لا | mp3 (الافتراضي) أو wav أو pcm. تُرفض opus و aac و flac بالخطأ 400. |
speed | الجسم | لا | 1.0 فقط. أي قيمة أخرى تعيد 400. |
stream_format | الجسم | لا | audio (الافتراضي)، ويعيد ملفًا كاملًا واحدًا. تُرفض sse بالخطأ 400. |
instructions | الجسم | لا | غير مدعوم. أي قيمة غير فارغة تعيد 400. |
Idempotency-Key | الترويسة | لا | غيابه أو فراغه يُتجاهَل. المفتاح الحاضر من 1 إلى 255 حرف ASCII مرئي؛ وغير ذلك يعيد 400. وتحمل الاستجابة المُعاد تشغيلها الترويسة X-Idempotent-Replay: true، وتحتفظ بالترويسة X-Request-Id للمحاولة الأولى. راجع Idempotency-Key. |
Idempotency-Key
Idempotency-Key اختياري وبأفضل جهد. تعيش ذاكرة إعادة التشغيل في ذاكرة بود واحد وتُبقي المدخلة حتى 10 دقائق (الوضع الافتراضي الحالي؛ فقد تُطرد مدخلة مكتملة مبكرًا عند امتلاء ميزانية الذاكرة أو عدد المداخل)، فيتحقق الضمان فقط عندما تصل إعادة المحاولة إلى البود نفسه طالما بقيت المدخلة:
- إعادة محاولة مطابقة تصل بينما المحاولة الأولى قيد التنفيذ تنتظرها وتحصل على بايتات الصوت نفسها.
- إعادة محاولة مطابقة بعد انتهاء المحاولة الأولى تعيد البايتات المخزنة. ولا تُفوتر مرتين.
- المفتاح نفسه تحت طلب متغيّر دلاليًا (المدخلات كما هي، أو النموذج أو الصوت أو الصيغة بعد التطبيع؛ فإعادة
ترتيب مفاتيح JSON وحدها لا تغيّره) يعيد
409BILLING_IDEMPOTENCY_CONFLICT. وإعادة استخدام قيمة المفتاح نفسها من مفتاح API آخر للحساب نفسه تتعارض بالطريقة نفسها. أرسل كل طلب مختلف بمفتاحه الخاص. - كل غياب لمدخلة مطابقة في ذاكرة إعادة التشغيل يعمل كطلب جديد ويُفوتر كطلب واحد: إعادة محاولة تصل إلى بود آخر، أو تصل بعد انتهاء صلاحية المدخلة (10 دقائق افتراضيًا)، أو تصل بعد فشل المحاولة الأولى، أو استجابة مُركَّبة تتجاوز حد المدخل الواحد في الذاكرة، 8 MiB (الافتراضي الحالي)، أو تكرار يصل بينما خانات الانتظار في الذاكرة مشبعة، أو مدخلة مكتملة طُردت مبكرًا عند امتلاء ميزانية الذاكرة أو عدد المداخل.
صف إعادة التشغيل مقيَّد بحسابك (وبصمته بمفتاح API الخاص بك)، فلا يمكن لقيمة المفتاح نفسها أن تُحيل إلى نتيجة حساب آخر.
وتحمل الاستجابة المُعاد تشغيلها الترويسة X-Idempotent-Replay: true وتحتفظ بالترويسة X-Request-Id
للمحاولة الأولى. ومن دون Idempotency-Key، قد تُفوتر حزمة SDK تعيد محاولة طلب ملتبس، مثل طلب انتهت
مهلته، مرتين.
الاستجابة
استجابة 200 هي الملف الصوتي الكامل في جسم ثنائي واحد.
response_format | نوع المحتوى |
|---|---|
mp3 | audio/mpeg |
wav | audio/wav |
pcm | audio/pcm |
الصيغة pcm هي PCM16 خام بأسلوب little-endian، بتردد 24 kHz وأحادي القناة، بلا ترويسة WAV.
ويحمل كل رد من هذه الواجهة الترويسة X-Request-Id، ويحمل جسم رد الخطأ الذي يتضمن job_id
القيمة نفسها في هذه الترويسة. وقد يصل رفض من طبقة البوابة (مثل تكرار ترويستي الاعتماد) بلا هذه
الترويسة. ويضبط رد الصوت Cache-Control: no-store. ويعيد الطلب الواحد ملفًا كاملًا
واحدًا، ولا يعيد بثًا جزئيًا.
أمثلة
اضبط $API_URL على أصل API لبيئتك (https://api.voice.humain.com).
curl -sS -X POST "$API_URL/v1/audio/speech" \
-H "x-api-key: $API_KEY" \
-H "content-type: application/json" \
--data '{"model":"nebula","input":"مرحبًا من HUMAIN Voice","voice":{"id":"42e38a63-849a-481a-b5bf-3c1b7a985de3"},"response_format":"mp3"}' \
--output speech.mp3ويرسل المثال الثاني المفتاح كرمز Bearer ويحذف voice، فينطق الصوت الافتراضي للنشر:
curl -sS -X POST "$API_URL/v1/audio/speech" \
-H "Authorization: Bearer $API_KEY" \
-H "content-type: application/json" \
--data '{"model":"nebula","input":"مرحبًا من HUMAIN Voice","response_format":"wav"}' \
--output speech.wavتعمل حزمة OpenAI SDK على المسار نفسه. أرسل Idempotency-Key عبر extra_headers:
from openai import OpenAI
import os
client = OpenAI(base_url=f"{os.environ['API_URL']}/v1", api_key=os.environ["API_KEY"])
speech = client.audio.speech.create(
model="nebula",
voice="af52a907-115e-4b25-9e44-11b70f655b71", # your environment's voice UUID
input="مرحبًا من HUMAIN Voice.",
response_format="mp3",
extra_headers={"Idempotency-Key": "my-request-uuid-1"},
)
speech.stream_to_file("speech.mp3")تعيد حزمة OpenAI SDK المحاولة تلقائيًا (مرتان افتراضيًا) على حالات تختارها، من دون قراءة راية retryable
في الجسم. وينتقل المفتاح Idempotency-Key أعلاه مع تلك المحاولات، فتُعاد الاستجابة المستقرة الأولى بدل أن
تُفوتر مرتين؛ والمفتاح الواحد لطلب منطقي واحد، فأعطِ كل طلب مختلف مفتاحًا جديدًا. ولتتبع قرار retryable
المتعارف عليه بنفسك، ابنِ العميل مع max_retries=0.
القيود
هذه واجهة الإصدار الأول v1. تأخذ نموذجًا واحدًا وسرعة واحدة، وتقبل أصوات UUID فقط، وتخزّن المقطع كاملًا قبل أن تعيد الاستجابة.
وتُعالَج علامات الانفعال بالقواعد نفسها المتّبعة في واجهة Socket.IO (تقود العلامات الصالحة
النطق، وتُرفض المقاطع المتجاوزة للحد وفق قواعد الانفعال في جدول الرموز القياسي). وتسري الحدود
والفئات المشتركة أيضًا: حد جسم الطلب 16 MiB (الافتراضي الحالي، وقابل للضبط حسب البيئة)، وتجاوز مهلة
التوليف يعيد TTS_DEADLINE_EXCEEDED (عائلة 504)، وصوت UUID غير موجود يعيد 400 TTS_VOICE_NOT_FOUND، ورفض التزامن أو الرصيد يعيد الرموز
نفسها في كل مسار صوت عام، والتحقق من الطلب يُنتج أربعة رموز من عائلة VALIDATION_:
VALIDATION_INVALID_FORMAT (JSON معطوب أو بيانات زائدة بعد JSON أو قيمة voice من شكل null أو {})،
وVALIDATION_INVALID_PARAM (قيم غير مدعومة مثل speed أو stream_format أو نص instructions
غير فارغ)، وVALIDATION_INVALID_UUID (قيمة صوت ليست UUID)، وVALIDATION_REQUIRED_FIELD (حقل
input فارغ).
- قيمة
speedغير1.0. - حقل
instructionsغير فارغ. stream_format: "sse"، وأي تسليم متدفق آخر (تحويل النص إلى كلام عبر Socket.IO).- صيغ الإخراج
opusوaacوflac. - صوت الاستنساخ المرجعي؛ يعمل UUID الملف الصوتي فقط.
- أي
modelغيرnebula.
الأخطاء
تستخدم الأخطاء جسم الخطأ JSON المتعارف عليه في المنصة، لا مخطط أخطاء OpenAI. اتخذ القرار من
code و retryable، واحتفظ بالترويسة X-Request-Id للدعم. ويغطي الخطأ 400 القيم غير
المدعومة في الطلب: model غير معروف، أو response_format غير mp3 أو wav أو
pcm، أو speed غير 1.0، أو stream_format غير audio، أو حقل instructions غير فارغ. ويعني 409
إعادة استخدام الترويسة Idempotency-Key مع جسم مختلف، أو من مفتاح API آخر للحساب نفسه.
والرفض قبل التوليف (التحقق والمصادقة والتعارض) يحرّر حجز الرصيد؛ أمّا الفشل بعد بدء التوليف فيستهلكه،
ولا تُفوتر إعادة التشغيل المخزنة مرتين. وكل رمز وحد وقاعدة إعادة محاولة في
الأخطاء والحدود.
الخطوات التالية
واجهة البث عبر HTTP
استدعِ مسارات البث عبر HTTP في HUMAIN Voice مباشرة لنسخ مقطع، وبث الصوت المباشر للنسخ أو تمييز المتحدثين، والتقاط إطارات تحويل النص إلى كلام.
واجهة Socket.IO
اتصل بـHUMAIN Voice عبر Socket.IO وتبادل الأحداث الخام والإطارات الثنائية للنسخ السريع والنسخ الفوري وتمييز المتحدثين المباشر والاستعلام عن الأصوات وتحويل النص إلى كلام.