Skip to main content
استخدم @youka/sdk و@youka/cli بالإصدار 0.2.0 أو أحدث لهذه الأمثلة. تظل المشاريع التي يتم إنشاؤها عبر واجهة API متاحة في مكتبة Youka لديك.

اختيار سير عمل ونموذج

تحدد kind سير عمل المشروع. يقوم karaoke بفصل المسارات (stems). يستخدم lyric-video الصوت الأصلي ولا يفرض رسومًا على الفصل. إن لم تُحدَّد kind فسيتم الإبقاء على سلوك karaoke الحالي. معالجة الكلمات هي خيار منفصل: محاذاة (alignment) أو تفريغ (transcription) أو بدون معالجة. اكتشف النماذج وأهلية الحساب قبل اختيار نموذج.
يصف الرد معرّفات النماذج، العمليات، مداخل الصوت، دلالات النص المزوّد، سير العمل، دعم اللغات، والميزات المطلوبة. يميّز suppliedTextHandling بين المحاذاة، والكلمات المفتاحية لدى المزوّد، والتصحيح بعد التفريغ. تعكس الأهلية الحساب المُصادَق عليه. يصف الاكتشاف الدعم المُهيّأ، وليس ضمانًا لتوفّر المزوّد. تظل صلاحية التحقق من الطلب وتسعيرات الأسعار (price quotes) هي المرجع النهائي. النماذج التي تتطلب عزلاً لصوت الغناء لا يمكنها معالجة فيديو كلمات بدون فصل. استخدمها ضمن سير عمل karaoke مع نموذج فصل يُنتج مسار vocals. Wav2Vec2 هو نموذج محاذاة. ElevenLabs Scribe هو نموذج تفريغ. النص المُزوَّد للتفريغ هو إرشاد، وليس ضمانًا لتطابق النص الناتج حرفيًا.

إنشاء المشاريع والحصول على تسعير

قم بمحاذاة الكلمات المزوّدة باستخدام نموذج مُعلن لفيديوهات الكلمات.
احتفِظ بالفصل لمشاريع karaoke. احذف --kind أو مرّر --kind karaoke واختر --split-model. استخدم --mode none للإنشاء بدون معالجة الكلمات. طلبات lyric-video ترفض خيارات الفصل. اطلب تسعير المصدر نفسه وسير العمل وخيارات المعالجة قبل الإنشاء.
يتحقق التسعير من توافق النموذج، وسياسة اللغة، وميزات الحساب، والمدة، وقواعد التخزين نفسها كما في الإنشاء. يحتوي تفصيل الأرصدة فيه على صفر من أرصدة الفصل لفيديوهات الكلمات. لا يحجز التسعير سعة أو أرصدة؛ قد تتغير حالة الحساب قبل الإنشاء.

تصحيح التوقيتات دون تشغيل وظائف معالجة

اقرأ المحاذاة عبر GET /projects/{projectId}/alignments، ثم احصل على المورد المختار عبر GET /projects/{projectId}/alignments/{alignmentId}. تحتوي القائمة على alignments وselectedAlignmentId وselectionRevision. يتضمن كل مورد حمولة التوقيت وrevision وselected وselectionRevision. تستبدل التحديثات كائن alignment كاملًا. وهي لا تُجري مزامنة ولا تُنشئ حجزًا لأرصدة المعالجة. احتفِظ بالمعرّفات والنص وفهارس السطر/الكلمة/تحت-الكلمة (subword) ومعلومات المغني والترجمات عند التحرير. الأوقات هي ثوانٍ عشرية مطلقة. طبّق أي تصحيح مطلوب مرة واحدة ضمن القيم المُرسلة. لا تُضِف التصحيح نفسه مرة أخرى كإزاحة تصدير.
استخدم select: true للحفظ والاختيار بشكل ذري (atomically). لاختيار توقيتات موجودة دون استبدالها، استدعِ client.projects.alignments.select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision }). تحمي مراجعة المحاذاة (alignment revision) محتويات التوقيت. وتحمي مراجعة الاختيار (selection revision) أي محاذاة هي النشطة. ينتج عن رمز قديم HTTP 409. اجلب أحدث مورد، وقارن التعديلات، وقدّم استبدالًا مقصودًا. لا تُحدِّث الرمز تلقائيًا وتكتب فوق تغييرات محرر آخر. تقبل CLI ملف JSON أو الإدخال القياسي. يحتوي ملف الاستيراد على { "alignment": { "items": [...] }, "expectedRevision": "..." }. ضمّن select وexpectedSelectionRevision عند الاختيار بشكل ذري. تحتوي الموارد المُصدَّرة أيضًا على بيانات وصفية للاستجابة، لذا استخرج حقول الطلب قبل الاستيراد.
تقبل عمليات الاستيراد حتى 100,000 عنصر. يجب أن يكون كل وقت نهاية أكبر بشكل صارم من وقت بدايته. تُرفض الأرقام غير الصالحة، والأوقات السلبية، والفهارس غير الصالحة، والنطاقات ذات الطول الصفري أو المعكوسة، والتوقيتات التي تتجاوز مدة مشروع معروفة. ما تزال التداخلات المشروعة وتوقيتات الدويتو (duet) مدعومة. أعد فتح أو حدّث مشروع تطبيق مفتوح مسبقًا بعد تعديل خارجي.

تصدير إصدار مُختار

يُعد versionId اختياريًا في طلبات التصدير وتحديثات الإعدادات، وكذلك في استعلام GET للإعدادات. يؤدي حذفه إلى الإبقاء على سلوك الإصدار الأساسي. تنتمي المحاذاة المحددة إلى المشروع، بينما ينتمي التنسيق والإعدادات إلى الإصدار المختار.
تتضمن مقابض عمليات التصدير السحابي وحمولات التصدير المحلي versionId وalignmentId وalignmentRevision. تحدد هذه الحقول لقطة التوقيت المستخدمة لذلك التصدير أو الحمولة المُحضّرة. كل عملية تحضير تقرأ الحالة الحالية، لذا قد يلاحظ تصدير منفصل لاحق تعديلات أحدث. احفظ الحمولة المُعادة عندما يجب على مُصيّر خارجي أن يُصيّر بالضبط تلك اللقطة المُحضّرة، وقم بتحديثها عند انتهاء صلاحية عناوين URL الموقّعة للوسائط. يستخدم الإخراج المحلي الشفاف ProRes 4444 ضمن حاوية MOV. يقوم --mute-all بتعيين جميع stems الخاصة بالمشروع إلى مستوى صوت صفر. الصمت وغياب مسار الصوت خاصيتان مختلفتان في الإخراج؛ افحص الملف المُصيّر إذا كانت أداة لاحقة تتطلب إحداهما. لا يستهلك التصيير المحلي أرصدة تصدير سحابية ويظل خاضعًا لأهلية الميزات الحالية. توقيت الكلمات، وإزاحات الصوت العامة، واستباق الكلمات (lyric anticipation) هي إعدادات منفصلة. تتحكم التخطيطات الحالية في ظهور الأسطر. لا يعد هذا الإصدار بفاصل كشف ثابت لكل سطر ولا يضيف واجهة API منفصلة لإرفاق مسار backing-track.

تشغيل كتالوج بأمان

احتفِظ ببيان (manifest) يتضمن معرّف عنصر ثابت، وبصمة المصدر، وإعدادات العملية، ومفتاح idempotency، ومعرّفات المشروع/المهمة، وآخر نتيجة نهائية. أعد استخدام المفتاح فقط لإعادات محاولة الطلب نفسه. خزّن نتائج الإنشاء قبل انتظار الاكتمال حتى يتمكن أي إعادة تشغيل من استئناف الاستطلاع. الرفع وتحضير الملفات محليًا لهما دورة حياة خاصة بهما؛ مفتاح idempotency للإنشاء لا يزيل تكرار كل عملية رفع. يقبل المثال التنفيذي catalogue example معرّفات ملفات إدخال مرفوعة مسبقًا ويخزّن نقطة تحقق واحدة لكل عنصر. يبدو البيان كالتالي.
نزّل المثال باسم catalogue.ts. ثبّت تبعياته واضبط YOUKA_API_KEY. استخدم مشروع Node.js مع "type": "module" في package.json الخاص به.
أعد التشغيل باستخدام البيان نفسه ودليل الحالة نفسه لاستئناف الاستطلاع للوظائف المقبولة أو لإعادة محاولة إرسال غير مؤكد باستخدام مفتاحه الأصلي. تُسجّل الوظائف المكتملة والفاشلة وتُتخطّى. تتطلب الطلبات المتغيرة معرّفات عناصر جديدة. يمنع قفل الدليل عمليتين من إرسال البيان نفسه بالتزامن. بعد تعطل قاسٍ، احذف .lock القديم فقط بعد التأكد من أن PID المخزن فيه لم يعد قيد التشغيل. ابدأ بعنصر واحد قيد التنفيذ. زد عدد العمال ضمن حدّ (bounded) فقط بعد قياس زمن معالجة الاستجابة واستجابات حدود المعدل (rate-limit) لحسابك. أعد محاولة أخطاء النقل وحدود المعدل مع تراجع (backoff)، مع احترام Retry-After. لا تُعِد المحاولة بشكل أعمى لأخطاء التحقق، أو تعارضات التوقيت، أو إخفاقات المعالجة النهائية. تتطلب أخطاء المصادقة بيانات اعتماد صالحة؛ ولا تعني أن وظيفة المعالجة فشلت. احتفِظ باستطلاع مهام السحابة الحالي ومعالجة أرصدة الفشل. لا يتم تقديم نقطة نهاية دفعية (batch endpoint)، ولا وعد webhook، ولا تغيير في التسعير، ولا تغيير في الترخيص، ولا سياسة احتفاظ جديدة هنا.