سجلات توليد الصوت

احتفظ بقيمة X-Request-Id التي يعيدها POST /v1/audio/speech. بعد انتهاء الطلب، استخدم مفتاح مصادقة يملك نطاق tts لاسترجاع سجله النهائي:

curl --fail --show-error \
  "https://api.sawtakarabi.ai/v1/audio/generations/$REQUEST_ID" \
  -H "Authorization: Bearer $SAWTAK_API_KEY"

يتضمن السجل request_id وstatus (completed أو failed أو interrupted)، وoriginal_text ومقاطع engine_segments المرتبة وrequested_settings وmodel وvoice_id وحقول الإصدار وerror_code وbilling_status والتكاليف وكتلة audio التي توضح توفر الصوت. لا يستطيع استرجاع السجل إلا الحساب المالك له. يتلقى أي حساب آخر خطأ 404 نفسه الذي يعاد لمعرّف غير معروف. لا يولّد الاسترجاع صوتًا ولا يفرض رسوم توليد.

يحفظ engine_segments نتائج تسوية النص والتشكيل الاختياري وبادئات توجيه اللهجة. هذه هي المقاطع المعدّة؛ وقد ينتهي الطلب بالفشل قبل إرسالها جميعًا إلى محرك التوليد. تصف الإعدادات الطلب، ولا تضمن أن كل محركات التوليد تستخدم القيم الافتراضية نفسها. تبقى قيمة model_revision هي null إلى أن يتوفر إصدار موثّق لمحرك التوليد. تشير voice_revision_kind: "conditioning_sha256" إلى بصمة بيانات تكييف الصوت الفعلية المستخدمة لهذا الطلب؛ وهي ليست رقم إصدار من مزوّد ولا ضمانًا لإعادة توليد النتيجة نفسها. لا تحمل طلبات zero-shot إصدارًا للصوت.

التكاليف سلاسل نصية تمثل مبالغ بالدولار الأمريكي بست خانات عشرية. يسجل charged_cost_usd المبلغ المخصوم الأصلي، بينما يصبح cost_usd صفرًا بعد اكتمال الاسترداد. تبقي حالة الفوترة refund_pending المبلغ المخصوم ظاهرًا حتى تسوية الاسترداد. تُقرأ هذه القيم من سجلات الفوترة، ولا تُنسخ من سجلات التشغيل.

عندما تكون audio.status هي available، يتيح رابط url النسبي تنزيل ملف PCM WAV كامل:

curl --fail --show-error \
  "https://api.sawtakarabi.ai/v1/audio/generations/$REQUEST_ID/audio" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  --output generation.wav

يحتوي ملف WAV المحفوظ على بيانات PCM المرسلة إلى العميل بعد إعادة أخذ العينات، سواء كانت صيغة الاستجابة الأصلية PCM أو WAV. لا يُعرض الصوت الجزئي أو المنقطع أو المبتور بسبب حد الالتقاط بوصفه تنزيلًا مكتملًا.

التوفر ومدة الاحتفاظ

تتوفر السجلات بعد حفظها في الخلفية. هذه واجهة لسجل الطلبات المنتهية، وليست واجهة لمهام توليد غير متزامنة: قد يعني خطأ 404 أن الطلب لا يزال قيد التنفيذ، أو لم يُحفظ سجله، أو انتهت مدة الاحتفاظ به، أو أنه يخص حسابًا آخر. لا تُضاف بأثر رجعي سجلات للطلبات التي أُجريت قبل نشر هذه الميزة.

يمكن استرجاع السجلات لمدة 30 يومًا، بشكل مستقل عن سجل لوحة التحكم الذي يحتفظ بآخر 20 عنصرًا. تُحذف صفوف SQL المنتهية في الخلفية على دفعات محدودة، بما فيها صفوف الحسابات غير النشطة. يعيد الصوت استخدام تخزين المراقبة الحالي؛ ولا يغيّر تنظيف SQL سياسة الاحتفاظ المنفصلة لذلك التخزين.

يبقى الالتقاط محدودًا وغير مضمون حتى لا تعطل مشكلات التخزين بثًا مدفوعًا. قد يؤدي تعطل العملية أو امتلاء الطابور أو فشل الكتابة إلى فقدان سجل. يقتصر التقاط الصوت على 10 MiB من بيانات PCM، ويخضع أيضًا لحد مشترك لاستهلاك الذاكرة. لذلك قد يكتمل التوليد دون أن يتوفر صوته المحفوظ. تميّز audio.status صراحةً بين available وpending_or_missing وcapture_limit_exceeded وunavailable وinvalid وstorage_unavailable. لا يُعاد رابط تنزيل يوحي بأنه يعمل إذا كان الملف مفقودًا.

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