> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# استخدام Youka من مساعدي الذكاء الاصطناعي (MCP)

> اربط Claude Code أو Cursor أو Codex أو أي عميل MCP بـ Youka وأنشئ فيديوهات كاريوكي وفيديوهات كلمات عبر الدردشة.

لدى Youka خادم MCP. ‏[MCP](https://modelcontextprotocol.io) (Model Context Protocol) هي الطريقة القياسية التي يتصل بها مساعدو الذكاء الاصطناعي بالأدوات الخارجية. بمجرد توصيله، يمكنك أن تطلب من مساعدك أشياء مثل "أنشئ فيديو كاريوكي للملف \~/Music/song.mp3"، فينشئ المشروع في حساب Youka الخاص بك، وينتظر حتى يكتمل، ثم يعطيك رابط المحرر أو رابط التنزيل.

يعمل الخادم مع أي عميل MCP يدعم الخوادم البعيدة (Streamable HTTP) مع ترويسة مخصّصة، مثل Claude Code وCursor وCodex.

> [!NOTE]
>
> تطبيقات Youka الرسمية لـ ChatGPT وClaude قادمة قريبًا. وحتى ذلك الحين، استخدم
> عميلًا من هذه الصفحة مع مفتاح Youka API.

## ما الذي تحتاجه

* حساب Youka يحتوي على أرصدة. يستخدم خادم MCP نفس الأرصدة مثل تطبيق الويب. راجع [Understanding credits](https://docs.youka.io/ar/web/understanding-credits.md).
* مفتاح Youka API. أنشئ واحدًا من [online.youka.io/account](https://online.youka.io/account) ضمن **API keys**. راجع [Authentication](https://docs.youka.io/ar/api/authentication.md).

تفاصيل الخادم:

| الإعداد | القيمة |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> يمنح مفتاح API وصولًا كاملًا إلى حساب Youka الخاص بك وأرصدته. احرص على إبقائه
> خارج الملفات والمستودعات المشتركة. إذا تسرّب مفتاح، احذفه من صفحة حسابك
> وأنشئ واحدًا جديدًا.

## ربط مساعدك

> [tab] Claude Code
>
> شغّل هذا في الطرفية لديك، مع استبدال `YOUR_API_KEY` بمفتاحك:
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> تحقّق من أنه تم الاتصال:
>
> ```bash theme={null}
> claude mcp list
> ```
>
> ينبغي أن ترى `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`.
>
> افتراضيًا تتم إضافة الخادم للمجلد الحالي فقط. أضِف `--scope user` لاستخدام Youka في كل المجلدات.

> [tab] Cursor
>
> افتح `~/.cursor/mcp.json` (لكل المشاريع) أو `.cursor/mcp.json` داخل مجلد مشروعك، وأضِف خادم `youka`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> عيّن `YOUKA_API_KEY` في البيئة التي يبدأ منها Cursor، أو استبدل `${env:YOUKA_API_KEY}` بمفتاحك. ثم افتح قسم MCP في إعدادات Cursor وتحقق من أن `youka` مفعّل.

> [tab] Codex
>
> شغّل:
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> أو أضِف هذا إلى `~/.codex/config.toml` بنفسك:
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> يقرأ Codex المفتاح من متغير البيئة `YOUKA_API_KEY`، لذا عيّنه قبل تشغيل Codex:
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> شغّل `codex mcp list` للتحقق من أن `youka` مفعّل.

> [tab] Other clients
>
> أي عميل MCP يدعم الخوادم البعيدة مع ترويسات مخصّصة سيعمل. استخدم:
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP (ويُسمّى أحيانًا "HTTP")
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> لا يستخدم الخادم جلسات، لذا لا حاجة لأي إعدادات أخرى.

## جرّبه

اطلب من مساعدك بلغة طبيعية. على سبيل المثال:

```text theme={null}
How many Youka credits do I have?
```

```text theme={null}
Make a karaoke video of ~/Music/song.mp3. Transcribe the lyrics automatically.
```

```text theme={null}
Make a lyric video of ./demo.wav using my "Neon" preset, then export it in 1080p and give me the download link.
```

```text theme={null}
In my latest Youka project, the second verse should be "..." instead of "...". Fix the lyrics and sync them again.
```

يسير طلب كاريوكي نموذجي على النحو التالي:

**1. Upload**

يطلب المساعد من Youka رابط رفع ويقوم برفع ملفك. الرفع
مجاني.

**2. Check the cost**

يتحقق من عدد الأرصدة التي سيستخدمها المشروع ويقارن ذلك مع
رصيدك.

**3. Create the project**

يزيل Youka الغناء ويزامن الكلمات. يستغرق ذلك بضع دقائق. يقوم
المساعد بالتحقق من الحالة حتى يصبح المشروع جاهزًا.

**4. Edit or export**

تحصل على رابط لفتح المشروع في محرر Youka. وإذا طلبت ملف
الفيديو، يقوم المساعد بتصديره ويعطيك رابط تنزيل.

إنشاء مشروع لا يقوم بعمل Render للفيديو تلقائيًا. أنت تقرر متى تقوم بالتصدير، حتى تتمكن من تصحيح الكلمات أو النمط أولًا، سواءً عبر الدردشة أو في [Youka editor](https://docs.youka.io/ar/web/using-studio.md).

## ما الذي يستطيع المساعد فعله

| الأداة | ما الذي تفعله | تستخدم أرصدة |
| - | - | - |
| `get_account` | يعرض حسابك ورصيد الأرصدة وحدود الرفع. | No |
| `list_presets` | يسرد [presets](https://docs.youka.io/ar/web/presets.md) الأنماط المحفوظة لديك. | No |
| `prepare_upload` | ينشئ رابط رفع لملف صوت أو فيديو واحد على جهازك. | No |
| `quote_project` | يعرض تكلفة مشروع جديد. | No |
| `create_karaoke_video` | ينشئ مشروع كاريوكي قابلًا للتحرير (إزالة الغناء، مزامنة الكلمات) من ملف واحد. | Yes |
| `create_lyric_video` | ينشئ مشروع فيديو كلمات قابلًا للتحرير (الصوت الأصلي، مزامنة الكلمات) من ملف واحد. | Yes |
| `list_projects` | يسرد مشاريعك، الأحدث أولًا. | No |
| `get_project` | يعرض حالة المشروع (processing أو ready أو failed) والكلمات والمسارات المنفصلة والتصديرات ورابط المحرر. | No |
| `sync_lyrics` | يعيد مزامنة الكلمات بعد تصحيحها، أو يعيد نسخ الأغنية تلقائيًا. | Yes |
| `get_task` | يعرض حالة مزامنة الكلمات. | No |
| `quote_export` | يعرض تكلفة التصدير. | No |
| `export_video` | يقوم بعمل Render للمشروع كما هو محفوظ حاليًا، بما في ذلك تعديلاتك في المحرر. | Yes |
| `get_export` | يعرض حالة التصدير وعندما يصبح جاهزًا يعطي رابط تنزيل. | No |

## الأرصدة والسلامة

* **نفس الأرصدة مثل تطبيق الويب.** إنشاء مشروع، وإعادة مزامنة الكلمات، والتصدير تكلفتها هي نفسها كما على [online.youka.io](https://online.youka.io).
* **يتم التحقق من التكلفة أولًا.** إذا لم تكن لديك أرصدة كافية، يرفض Youka الطلب ويذكر ذلك. لا يتم خصم شيء.
* **لا توجد رسوم مزدوجة.** إذا أعاد المساعد محاولة تنفيذ طلب بعد انتهاء المهلة، يتعرف Youka على إعادة المحاولة ويعيد النتيجة الأصلية بدلًا من الخصم مجددًا.
* **تُشترى الأرصدة على Youka.** لا يستطيع المساعد شراء الأرصدة. لإضافة المزيد، راجع [Buy more credits](https://docs.youka.io/ar/web/buy-credits.md).
* **الأدوات المدفوعة تعمل فقط عندما تطلب.** يتم توجيه المساعد لإنشاء المشاريع أو مزامنة الكلمات أو التصدير فقط عندما تطلب ذلك.

## استكشاف الأخطاء وإصلاحها

> [accordion] 401 Unauthorized, or the server shows as failed
>
> مفتاح API مفقود أو غير صالح. تحقق من أن الترويسة هي بالضبط
> `Authorization: Bearer yk_...`، مع مسافة واحدة بعد `Bearer` ودون
> مسافات إضافية أو علامات اقتباس داخل المفتاح. إذا حذفت المفتاح من صفحة حسابك، أنشئ مفتاحًا جديدًا
> وحدّث إعدادات عميلك. بالنسبة لإعدادات Codex وCursor التي تقرأ
> `YOUKA_API_KEY`، تأكد من تعيين المتغير في البيئة التي يبدأ منها
> التطبيق.

> [accordion] Not enough credits
>
> اطلب من المساعد رصيدك، أو تحقّق منه على
> [online.youka.io](https://online.youka.io). ثم [buy more
> credits](https://docs.youka.io/ar/web/buy-credits.md) واطلب مجددًا.

> [accordion] The project failed
>
> اطلب من المساعد عرض المشروع. يتضمن ذلك الخطأ. تأكد من أن
> الملف ملف صوت أو فيديو مدعوم وضمن حدود الرفع التي يعرضها
> حسابك.

> [accordion] The lyrics are wrong
>
> أخبر المساعد بالكلمات الصحيحة واطلب منه مزامنتها مجددًا، أو افتح
> رابط المحرر و[edit the lyrics](https://docs.youka.io/ar/web/edit-lyrics.md) بنفسك. ثم
> صدّر مرة أخرى.

## مستندات ذات صلة

* [AI agents](https://docs.youka.io/ar/agents.md) — استخدم Youka CLI والمهارة من داخل وكيل
* [Authentication](https://docs.youka.io/ar/api/authentication.md) — أنشئ مفاتيح API واستخدمها
* [Understanding credits](https://docs.youka.io/ar/web/understanding-credits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.