أدلة API

واجهة تحويل النص إلى كلام المتوافقة مع 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 وحدها لا تغيّره) يعيد 409 BILLING_IDEMPOTENCY_CONFLICT. وإعادة استخدام قيمة المفتاح نفسها من مفتاح API آخر للحساب نفسه تتعارض بالطريقة نفسها. أرسل كل طلب مختلف بمفتاحه الخاص.
  • كل غياب لمدخلة مطابقة في ذاكرة إعادة التشغيل يعمل كطلب جديد ويُفوتر كطلب واحد: إعادة محاولة تصل إلى بود آخر، أو تصل بعد انتهاء صلاحية المدخلة (10 دقائق افتراضيًا)، أو تصل بعد فشل المحاولة الأولى، أو استجابة مُركَّبة تتجاوز حد المدخل الواحد في الذاكرة، 8 MiB (الافتراضي الحالي)، أو تكرار يصل بينما خانات الانتظار في الذاكرة مشبعة، أو مدخلة مكتملة طُردت مبكرًا عند امتلاء ميزانية الذاكرة أو عدد المداخل.

صف إعادة التشغيل مقيَّد بحسابك (وبصمته بمفتاح API الخاص بك)، فلا يمكن لقيمة المفتاح نفسها أن تُحيل إلى نتيجة حساب آخر. وتحمل الاستجابة المُعاد تشغيلها الترويسة X-Idempotent-Replay: true وتحتفظ بالترويسة X-Request-Id للمحاولة الأولى. ومن دون Idempotency-Key، قد تُفوتر حزمة SDK تعيد محاولة طلب ملتبس، مثل طلب انتهت مهلته، مرتين.

الاستجابة

استجابة 200 هي الملف الصوتي الكامل في جسم ثنائي واحد.

response_formatنوع المحتوى
mp3audio/mpeg
wavaudio/wav
pcmaudio/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 آخر للحساب نفسه. والرفض قبل التوليف (التحقق والمصادقة والتعارض) يحرّر حجز الرصيد؛ أمّا الفشل بعد بدء التوليف فيستهلكه، ولا تُفوتر إعادة التشغيل المخزنة مرتين. وكل رمز وحد وقاعدة إعادة محاولة في الأخطاء والحدود.

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

في هذه الصفحة