MCP

تتيح Krea خادم Model Context Protocol (MCP) مستضافًا للوكلاء ومساعدي البرمجة. استخدمه عندما تريد أن يستدعي عميل متوافق مع MCP خدمة Krea مباشرةً بدلًا من كتابة طلبات API يدويًا.

لست بحاجة إلى مفتاح API للاتصال. أضف https://api.krea.ai/mcp بوصفه عنوان خادم MCP، ثم سجّل الدخول باستخدام حساب Krea الخاص بك من خلال تدفق OAuth في عميلك.

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

الإعداد	القيمة
النقل	Streamable HTTP
العنوان	`https://api.krea.ai/mcp`
المصادقة	OAuth

تعتمد الفوترة على طريقة المصادقة:

طريقة المصادقة	مصدر الفوترة
OAuth	وحدات الحوسبة الخاصة بمساحة العمل التي تختارها أثناء الموافقة
رمز API	رصيد API المنفصل الخاص بمساحة عملك

المصادقة

تستخدم معظم عملاء MCP بروتوكول OAuth تلقائيًا. عندما يطلب منك العميل الاتصال، اتبع تدفق تسجيل الدخول في المتصفح وامنح الإذن لـ Krea.

اختر مساحة عمل أثناء الموافقة

تتضمن شاشة موافقة OAuth منتقي مساحة العمل يعرض كل مساحات العمل التي تنتمي إليها. يتم اختيار مساحة العمل الافتراضية مسبقًا؛ اختر مساحة مختلفة إذا أردت تشغيل جلسة MCP هذه في مكان آخر (على سبيل المثال، مساحة عمل استوديو مشتركة بدلًا من مساحتك الشخصية). ترتبط مساحة العمل التي تختارها بجلسة OAuth وتحدّد:

الفوترة. تُخصم وحدات الحوسبة من مساحة العمل المختارة، وليس فقط من الحساب الذي سجلت الدخول إليه.
نطاق الأصول. تُحفظ الملفات المرفوعة عبر أدوات مثل upload_asset في مساحة العمل المرتبطة، والأدوات التي تتطلب رفعًا (على سبيل المثال، get_upload_url) لا تعمل إلا بعد ربط مساحة عمل.

لتبديل مساحة العمل المرتبطة لاحقًا، افصل Krea في عميل MCP الخاص بك وأعد الاتصال — وسترى المنتقي مرة أخرى.

جلسات OAuth القديمة التي أُنشئت قبل إطلاق منتقي مساحة العمل ليس لها ارتباط صريح. تستخدم تلك الجلسات افتراضيًا مساحة العمل الافتراضية لحسابك. أعد الاتصال لربط الجلسة بمساحة عمل محددة.

إذا كان عميل MCP الخاص بك لا يدعم OAuth، فيمكنك المصادقة باستخدام رمز API بدلًا من ذلك:

مفتاح الترويسة	قيمة الترويسة
`Authorization`	`Bearer KREA_API_TOKEN`

استبدل KREA_API_TOKEN برمز من krea.ai/app/api/tokens. يستطيع مالكو مساحات العمل والمشرفون فقط إنشاء رموز API. تُفوتر استخدامات رمز API على رصيد API الخاص بمساحة عملك، تمامًا كما هو الحال مع استدعاءات API المباشرة. راجع مفاتيح API والفوترة للاطلاع على تفاصيل رصيد API.

خزّن بيانات اعتماد MCP المعتمدة على رمز API بالطريقة نفسها التي تخزّن بها مفاتيح API. لا تُودع ملفات إعداد MCP التي تحتوي على رموز حقيقية في نظام التحكم بالإصدارات.

Claude Code

شغّل هذا الأمر في الطرفية:

claude mcp add --transport http krea-ai https://api.krea.ai/mcp

سجّل الدخول بحساب Krea الخاص بك عندما يطلب منك Claude Code الاتصال. أعد تشغيل Claude Code أو أعد تحميل خوادم MCP بعد إضافة الخادم.

Codex

افتح Settings > MCP servers في Codex.
أضف خادمًا جديدًا.
اختر Streamable HTTP بوصفه طريقة النقل.
الصق عنوان الخادم:

https://api.krea.ai/mcp

احفظ الخادم وسجّل الدخول بحساب Krea عندما يطلب منك Codex الاتصال.

Cursor

افتح لوحة الأوامر، وابحث عن Open MCP settings، ثم أضف هذا الإدخال إلى mcp.json:

{
  "mcpServers": {
    "krea-ai": {
      "url": "https://api.krea.ai/mcp"
    }
  }
}

أعد تشغيل Cursor بعد حفظ الملف، ثم سجّل الدخول بحساب Krea عندما يطلب منك Cursor الاتصال.

استخدام Krea عبر MCP

بمجرد الاتصال، اطلب من وكيلك سرد نماذج Krea أو فحص مخطط نموذج قبل التوليد. تتطابق معرّفات النماذج مع مسارات API المستخدمة في بقية وثائق المطورين، مثل image/krea/krea-2/medium أو video/google/veo-3.1. على سبيل المثال:

List the available Krea image models, then generate an image with Krea 2 using a 16:9 aspect ratio.

إذا كان النموذج موقوفًا، فإن Krea تُرجع بيانات وصفية للإيقاف من خلال اكتشاف نماذج MCP. راجع الإيقافات لإرشادات الترحيل.

الأدوات

يكشف خادم Krea MCP عن أدوات تُقابل واجهة برمجة التطبيقات العامة. يكتشفها وكيلك تلقائيًا عبر tools/list؛ والأكثر شيوعًا منها:

الأداة	ما تقوم به
`list_models`	سرد نماذج الصور والفيديو المتاحة.
`get_model_schema`	فحص مخطط مدخلات النموذج قبل التوليد.
`generate`	إرسال مهمة توليد صورة أو فيديو.
`execute_node_app`	تشغيل تطبيق عقدة (node app).
`get_job`	جلب الحالة الحالية ومخرجات المهمة باستخدام `jobId`.
`cancel_job`	إلغاء مهمة قيد التنفيذ وحذفها من قائمة مهامك.
`get_upload_url`	طلب عنوان URL موقّع مسبقًا قصير الأجل لرفع ملف محلي لاستخدامه كمدخل للنموذج.

تتضمن مخرجات أدوات التوليد وتطبيقات العقد job_id للمهمة المُرسلة إلى جانب حمولة المهمة. مرّر هذا المعرّف إلى get_job لاستطلاع الحالة، أو إلى cancel_job لإيقاف مهمة لم تعد بحاجة إليها.

إلغاء مهمة

تستدعي cancel_job خلف الكواليس DELETE /jobs/{id} وتُرجع { "job_id": "...", "deleted": true } عند النجاح. لا يسري الإلغاء إلا أثناء وجود المهمة في حالة غير نهائية — راجع دورة حياة المهمة للاطلاع على القواعد والتبعات الفوترية (المهام الملغاة لا تُفوتر). مثال على المطالبة:

Cancel job 7f3c9b1a-… because the prompt was wrong.

توفير مدخلات وسائط

أي مدخل نموذج يقبل عنوان URL لوسائط (على سبيل المثال start_image أو image_style_references[].url أو reference_images) يقبل أحد ثلاثة أشكال:

عنوان URL خارجي — رابط https:// يمكن الوصول إليه علنًا لملف صورة أو فيديو أو صوت أو نموذج ثلاثي الأبعاد.
معرّف بيانات base64 — على سبيل المثال data:image/png;base64,iVBORw0KGgo….
عنوان URL لأصل مرفوع — العنوان المُرجَع بعد رفع ملف محلي إلى Krea.

قوائم عناوين URL المفصولة بفواصل غير مدعومة. مرّر كل مدخل بوصفه حقلًا منفصلًا أو عنصر مصفوفة مستقل.

رفع ملف محلي باستخدام `get_upload_url`

عندما يكون الملف الذي تريد استخدامه على جهازك المحلي وغير مستضاف في أي مكان بعد، اطلب من وكيلك استدعاء get_upload_url. تُرجع الأداة عنوان URL موقّعًا مسبقًا صالحًا لمدة ثلاث ساعات. ثم يُرسل عميلك الملف باستخدام POST إلى ذلك العنوان بصيغة multipart/form-data مع حقل file واحد، ويحتوي جسم الاستجابة على عنوان URL للأصل يمكنك تمريره إلى استدعاء generate لاحق. مثال على التدفق:

# 1. Ask the agent to call get_upload_url through MCP. It returns something like:
#    https://api.krea.ai/public-api/assets/presigned/...

# 2. POST the local file to that presigned URL.
curl -X POST "$UPLOAD_URL" -F "file=@/path/to/image.png"

# 3. The response body contains the asset URL. Use it in the next generate call,
#    for example as start_image or image_style_references[].url.

إذا فشل طلب الرفع POST بسبب تقييد منفذ الشبكة الصادر، فأضف api.krea.ai إلى قائمة النطاقات المسموح بها في عميلك. يُقدَّم عنوان URL الموقّع مسبقًا من المضيف نفسه الذي تُقدَّم منه بقية واجهة برمجة التطبيقات العامة.

إذا كان ملفك متاحًا بالفعل عبر عنوان URL عام أو يمكنك تشفيره بوصفه معرّف بيانات base64، فتجاوز get_upload_url ومرّر تلك القيمة مباشرة إلى مدخل التوليد بدلًا من ذلك.

أداة واجهة MCP Apps

تُرفق استدعاءات أدوات التوليد وتطبيقات العقد مورد واجهة MCP Apps. يعرض عملاء MCP الذين يدعمون MCP Apps أداة تفاعلية لنتيجة المهمة مدمجة مع استجابة الأداة، تتضمن:

لوحة تحميل بحجم متناسب مع نسبة العرض إلى الارتفاع للمهمة أثناء وضع المهمة في قائمة الانتظار أو معالجتها.
استطلاع تلقائي لـ get_job بحيث تُحدَّث الأداة مع تقدم المهمة، دون أن يستدعي الوكيل get_job بنفسه.
أزرار إجراءات لإعادة محاولة التوليد أو إلغاء المهمة من داخل الأداة.
شريط مقارنة بملء الشاشة قبل/بعد لنتائج التحسين (enhance).

تُكشف الأداة بوصفها المورد ui://krea-public-api/job-result-frame وتُجهَّز تلقائيًا — لا يلزم أي إعداد من جانب العميل. أما العملاء الذين لا يدعمون MCP Apps فيتجاهلون المورد ببساطة ويعودون إلى مخرجات الأداة المُهيكلة. ولأن الأداة تستطلع نيابة عنك، فضّل التوليد غير المتزامن (الوضع الافتراضي) عندما تريد أن تعرض الواجهة التقدم. استخدم الوضع المتزامن فقط عندما يطلب المستخدم صراحةً الانتظار للحصول على النتيجة النهائية في استجابة الأداة.

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

المشكلة	الحل
فشل المصادقة	أعد الاتصال بخادم MCP وأكمل تدفق Krea OAuth في متصفحك. إذا كنت تستخدم رمز API، فتأكد من أن الترويسة هي بالضبط `Authorization: Bearer KREA_API_TOKEN` وأن الرمز لم يُلغَ.
العميل لا يستطيع الاتصال	تأكد من أن العميل مهيأ لاستخدام Streamable HTTP ويستعمل `https://api.krea.ai/mcp`.
رُفض التوليد بسبب الفوترة	إذا اتصلت عبر OAuth، فتحقق من وحدات الحوسبة في مساحة العمل التي اخترتها أثناء الموافقة — أعد الاتصال إذا كنت بحاجة إلى ربط الجلسة بمساحة عمل مختلفة. إذا اتصلت برمز API، فأضف رصيدًا إلى API على krea.ai/app/api.
فشل استدعاء النموذج	اطلب من وكيلك فحص مخطط النموذج قبل إعادة المحاولة. تستخدم طلبات MCP المدخلات نفسها للنموذج المستخدمة في API.

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

مفاتيح API والفوترة

أنشئ رموز API وأدر رصيد API للطلبات المصادق عليها بالرموز.

بيئة تجريبية تفاعلية

جرّب الطلبات في تطبيق Krea قبل أن تطلب من وكيل تشغيلها.

الإيقافات

اطّلع على كيفية كشف MCP لبيانات ترحيل النماذج الوصفية.

واجهات برمجة النماذج

تصفّح مخططات نقاط النهاية ومعلمات النماذج.

البدء

Krea 2

المفاهيم الأساسية

أمثلة على الكود

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

المصادقة

اختر مساحة عمل أثناء الموافقة

Claude Code

Codex

Cursor

استخدام Krea عبر MCP

الأدوات

إلغاء مهمة

توفير مدخلات وسائط

رفع ملف محلي باستخدام `get_upload_url`

أداة واجهة MCP Apps

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

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

مفاتيح API والفوترة

بيئة تجريبية تفاعلية

الإيقافات

واجهات برمجة النماذج

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

​المصادقة

​اختر مساحة عمل أثناء الموافقة

​Claude Code

​Codex

​Cursor

​استخدام Krea عبر MCP

​الأدوات

​إلغاء مهمة

​توفير مدخلات وسائط

​رفع ملف محلي باستخدام get_upload_url

​أداة واجهة MCP Apps

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

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

مفاتيح API والفوترة

بيئة تجريبية تفاعلية

الإيقافات

واجهات برمجة النماذج

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

المصادقة

اختر مساحة عمل أثناء الموافقة

Claude Code

Codex

Cursor

استخدام Krea عبر MCP

الأدوات

إلغاء مهمة

توفير مدخلات وسائط

رفع ملف محلي باستخدام `get_upload_url`

أداة واجهة MCP Apps

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

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