Skip to main content
الإعداد المسبق هو تكوين عرض قابل لإعادة الاستخدام — الخلفية، نمط الترجمة، التخطيط — يمكنك تطبيقه على أي مشروع أو تصدير. استخدم الإعدادات المسبقة عندما تريد مظهراً متسقاً عبر العديد من المقاطع. اطّلع على مرجع إعدادات العرض للحصول على البنية الكاملة لـ preset وكل خيار مدعوم بقيم enum.

​
متى تستخدم إعداداً مسبقاً

استخدم إعداداً مسبقاً عندما…

تريد المظهر نفسه عبر العديد من المشاريع وتحتاج إلى تحديثه في مكان واحد.

استخدم إعدادات المشروع عندما…

تحتاج إلى تجاوزات محلية خاصة بالمشروع لا تستحق مشاركتها.

​
نقاط النهاية

MethodPathPurpose
GET/presetsسرد الإعدادات المسبقة للحساب المُصادَق عليه.
POST/presetsإنشاء إعداد مسبق جديد.
GET/presets/{presetId}جلب إعداد مسبق واحد.
PATCH/presets/{presetId}تحديث الاسم أو المحتوى أو تعيينه كافتراضي.
DELETE/presets/{presetId}حذف إعداد مسبق.
تتوفر مخططات الطلب والاستجابة الكاملة ضمن API reference في الشريط الجانبي.

​
إنشاء إعداد مسبق

curl -X POST https://api.youka.io/ar/api/v1/presets \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: create-neon-night-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night",
    "preset": {
      "background": {
        "type": "gradient",
        "colors": ["#12001f", "#2f0a57"],
        "angle": 90
      },
      "singerTextStyles": {
        "0": {
          "fontFamily": "Inter",
          "textColor": "#00f5ff",
          "effectColor": "#ff4fd8"
        }
      }
    },
    "isDefault": false
  }'
تتضمن الاستجابة قيمة presetId الجديدة. خزّنها وأشِر إليها من المشاريع أو عمليات التصدير.
اربط كل طلب POST بمفتاح idempotency. إعادة استخدام المفتاح نفسه مع الحمولة نفسها يُرجع الإعداد المسبق الأصلي بدلاً من إنشاء نسخة مكررة.

​
اكتشاف حقول الإعداد المسبق الصالحة

تُتحقَّق الإعدادات المسبقة على جانب الخادم مقابل KaraokePresetSchema. تُصدّر SDK هذا المخطط لتتمكن من تحويله إلى JSON Schema وقت التشغيل: 
import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();
من خلال CLI: 
youka preset schema --json
ينبغي لمؤلفي الوكلاء استدعاء هذا قبل تعديل الإعدادات المسبقة حتى يعرف النموذج كل حقل صالح ونوع قيمته. مرجع سهل القراءة:

​
تحديث إعداد مسبق

curl -X PATCH https://api.youka.io/ar/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night v2",
    "preset": {
      "singerTextStyles": {
        "0": {
          "textColor": "#ff2a2a"
        }
      }
    }
  }'
مرّر أي مجموعة فرعية من name وpreset. الحقول التي لا تُضمّنها تبقى دون تغيير.

​
تعيين الإعداد المسبق الافتراضي

لكل حساب إعداد مسبق افتراضي واحد كحد أقصى، ويُطبَّق تلقائياً على المشاريع الجديدة. 
curl -X PATCH https://api.youka.io/ar/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isDefault": true
  }'
يؤدي تعيين افتراضي جديد إلى إلغاء تعيين السابق تلقائياً.

​
تطبيق إعداد مسبق

أشِر إلى إعداد مسبق في ثلاثة مواضع:
WhereField
عند إنشاء المشروعpresetId في POST /projects
في أي وقت على المشروعpresetId في PATCH /projects/{projectId}/settings
وقت التصديرpresetId في POST /projects/{projectId}/exports
مثال عند التصدير: 
curl -X POST https://api.youka.io/ar/api/v1/projects/prj_abc/exports \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "preset_abc123",
    "resolution": "1080p",
    "quality": "high"
  }'

​
حذف إعداد مسبق

curl -X DELETE https://api.youka.io/ar/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-preset_abc123"
حذف إعداد مسبق لا يؤثر على المشاريع أو عمليات التصدير التي تم عرضها سابقاً باستخدامه. ستفشل عمليات التصدير المستقبلية التي تشير إلى الإعداد المسبق المحذوف.

​
ما التالي