الواجهة البرمجية وخادم MCP

نظرة عامة

يوفّر MangaMade للمطوّرين طريقتين. تجيب واجهة REST البرمجية بصيغة JSON عبر HTTPS. ويتيح خادم MCP لمساعدي الذكاء الاصطناعي مثل Claude Code وCursor وVS Code استدعاء MangaMade كأدوات. تستخدم الطريقتان المفاتيح نفسها والحدود نفسها، وهما مشمولتان في باقات الهواية والمبدع والاستوديو.

واجهة REST: https://api.mangamade.com/api/v1
خادم MCP: https://api.mangamade.com/api/mcp

البدء السريع

اختر باقة لمساحة عملك. لا تتيح التجربة المجانية إنشاء مفاتيح API.
من الإعدادات، افتح مفاتيح API وأنشئ مفتاحًا (للمسؤولين والمالك فقط). انسخه، فهو لا يظهر إلا مرة واحدة.

استدعِ الواجهة مع المفتاح كرمز Bearer:

curl https://api.mangamade.com/api/v1/series \
  -H "Authorization: Bearer mm_live_…"

المصادقة

أرسل المفتاح في ترويسة Authorization مع كل طلب. يعمل المفتاح باسم الشخص الذي أنشأه، في مساحة العمل التي أُنشئ فيها، ولا يعمل في غيرها أبدًا.

Authorization: Bearer mm_live_…

تصل المفاتيح إلى السلاسل والشخصيات والفصول والصفحات والتوليد والتصدير والأرصدة. أما الفوترة والفريق والحساب والإدارة وإدارة المفاتيح فتتطلب دائمًا جلسة تسجيل دخول، وتجيب أي مفتاح بالرمز session_required.

لا يحفظ MangaMade إلا بصمة مشفّرة لكل مفتاح، لذا لا يمكن عرض مفتاح مفقود مرة أخرى: ألغِه وأنشئ غيره. يمكن أن تنتهي صلاحية المفتاح بعد 30 أو 90 أو 365 يومًا، أو ألا تنتهي أبدًا.

حدود الاستخدام

تُطبَّق الحدود لكل مساحة عمل في الدقيقة، على واجهة REST وخادم MCP معًا: تتشاركها جميع مفاتيح مساحة العمل. ويُحتسب استدعاء أداة MCP طلبًا واحدًا.

الباقة	الطلبات في الدقيقة	الطلبات المكلفة في الدقيقة
الهواية	60	10
المبدع	120	20
الاستوديو	300	40

الطلبات المكلفة

تُحتسب هذه الطلبات في الحدّين معًا:

تخطيط الفصول
أوراق الشخصيات
مراجع الأسلوب
توليد اللوحات وإعادة رسمها
التصدير
روابط المشاركة
الترجمات

الترويسات

يحمل كل رد على طلب موثّق بمفتاح ما يلي:

RateLimit-Limit: حدّ النافذة الحالية
RateLimit-Remaining: الطلبات المتبقية في النافذة
RateLimit-Reset: الثواني المتبقية حتى تبدأ نافذة جديدة
RateLimit-Policy: الحدّ والنافذة المطبّقان

RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 42
RateLimit-Policy: 120;w=60

عند تجاوز الحد، تجيب الواجهة بالرمز 429 rate_limited مع ترويسة Retry-After بالثواني. انتظر تلك المدة ثم أعد المحاولة.

الأخطاء

كل خطأ هو JSON يحوي رمزًا ورسالة مقروءة، وأحيانًا تفاصيل.

{
  "code": "rate_limited",
  "message": "Too many requests",
  "details": {}
}

الرمز	الحالة	المعنى
`invalid_api_key`	401	المفتاح غير معروف أو ملغى أو منتهي الصلاحية.
`api_plan_required`	403	لا باقة لمساحة العمل؛ والوصول إلى الواجهة مشمول في كل الباقات.
`session_required`	403	يتطلب المسار جلسة تسجيل دخول، ولا يتاح للمفاتيح.
`validation_failed`	400	لا يطابق جسم الطلب أو معاملاته المخطط؛ ويسرد الحقل details الحقول المعنية.
`insufficient_credits`	402	لا تملك مساحة العمل أرصدة كافية لهذا.
`rate_limited`	429	نفد حدّ الدقيقة؛ أعد المحاولة بعد عدد ثواني Retry-After.

منع التكرار

تأخذ الطلبات التي تستهلك أرصدة (مراجع الأسلوب وأوراق الشخصيات وتوليد الفصول وإعادة رسم اللوحات) الحقل idempotencyKey في جسم الطلب، بطول من 8 إلى 100 حرف. أرسل المفتاح نفسه عند إعادة المحاولة، فلا يخصم MangaMade إلا مرة واحدة مهما حدث للمحاولة الأولى. واستخدم مفتاحًا جديدًا لكل عمل جديد.

curl -X POST https://api.mangamade.com/api/v1/panels/{id}/regenerate \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"panel-42-retry-1"}'

مسارات REST

المسارات نسبية إلى عنوان URL الأساسي أدناه. أجسام الطلبات بصيغة JSON. ويقبل كل مسار ويعيد البُنى نفسها التي يستخدمها تطبيق MangaMade.

عنوان URL الأساسي

https://api.mangamade.com/api/v1

مكلف: يُحتسب في حدّ الطلبات المكلفة. يستهلك أرصدة: يأخذ الحقل idempotencyKey.

السلاسل والأساليب

الطريقة	المسار	الوظيفة
`GET`	`/style-presets`	سرد الأساليب الجاهزة
`GET`	`/series`	سرد سلاسل مساحة العمل
`POST`	`/series`	إنشاء سلسلة
`GET`	`/series/:id`	جلب سلسلة
`PATCH`	`/series/:id`	تعديل سلسلة
`DELETE`	`/series/:id`	حذف سلسلة
`POST`	`/series/:id/style-anchor`	رسم مرجع الأسلوب أو رفعهمكلفيستهلك أرصدة

الشخصيات

الطريقة	المسار	الوظيفة
`GET`	`/series/:seriesId/characters`	سرد شخصيات سلسلة
`POST`	`/series/:seriesId/characters`	إنشاء شخصية
`GET`	`/characters/:id`	جلب شخصية
`PATCH`	`/characters/:id`	تعديل شخصية
`DELETE`	`/characters/:id`	حذف شخصية
`POST`	`/characters/:id/references`	إرفاق صورة مرجعية مرفوعة بشخصية
`DELETE`	`/characters/:id/references/:assetId`	إزالة صورة مرجعية من شخصية
`POST`	`/characters/:id/sheet`	رسم ورقة شخصية أو رفعهامكلفيستهلك أرصدة

الرفع

الطريقة	المسار	الوظيفة
`POST`	`/uploads/presign`	الحصول على نموذج موقّع مسبقًا لرفع صورة إلى التخزين
`POST`	`/uploads/complete`	التحقق من الرفع والحصول على مفتاحه لاستخدامه في referenceKeys أو uploadKey أو كمرجع

الفصول

الطريقة	المسار	الوظيفة
`GET`	`/series/:seriesId/chapters`	سرد فصول سلسلة
`POST`	`/series/:seriesId/chapters`	إنشاء فصل
`GET`	`/chapters/:id`	جلب فصل مع نصه
`PATCH`	`/chapters/:id`	تعديل فصل
`DELETE`	`/chapters/:id`	حذف فصل
`POST`	`/chapters/:id/plan`	كتابة نص الفصل من ملخصهمكلف
`PUT`	`/chapters/:id/script`	استبدال النص
`POST`	`/chapters/:id/translate`	إنشاء نسخة مترجمةمكلف

الصفحات واللوحات

الطريقة	المسار	الوظيفة
`GET`	`/chapters/:id/pages`	سرد صفحات فصل
`GET`	`/pages/:id`	جلب صفحة مع لوحاتها وكتابتها
`PATCH`	`/pages/:id/layout`	تغيير تخطيط الصفحة
`PATCH`	`/pages/:id/lettering`	تعديل كتابة صفحة
`PATCH`	`/panels/:id`	تعديل إرشادات رسم لوحة

التوليد

الطريقة	المسار	الوظيفة
`POST`	`/chapters/:id/estimate`	تقدير الأرصدة اللازمة لرسم فصل
`POST`	`/chapters/:id/generate`	رسم لوحات فصلمكلفيستهلك أرصدة
`GET`	`/chapters/:id/batches`	سرد دفعات توليد فصل
`POST`	`/panels/:id/regenerate`	إعادة رسم لوحةمكلفيستهلك أرصدة
`POST`	`/panels/:id/select`	اختيار الرسمة التي تستخدمها لوحة

التصدير وروابط المشاركة

الطريقة	المسار	الوظيفة
`POST`	`/chapters/:id/exports`	بدء تصدير (PNG أو PDF أو CBZ)مكلف
`GET`	`/chapters/:id/exports`	سرد عمليات تصدير فصل
`GET`	`/exports/:id`	جلب عملية تصدير وحالتها
`GET`	`/exports/:id/download`	جلب رابط تنزيل تصدير مكتمل
`POST`	`/chapters/:id/share-links`	إنشاء رابط مشاركة للقراءة فقطمكلف
`GET`	`/chapters/:id/share-links`	سرد روابط مشاركة فصل
`DELETE`	`/share-links/:id`	حذف رابط مشاركة

الأرصدة

الطريقة	المسار	الوظيفة
`GET`	`/credits`	جلب رصيد الأرصدة
`GET`	`/credits/ledger`	سرد سجل الأرصدة

خادم MCP

يعمل خادم MCP عبر Streamable HTTP، بلا حالة، مع ردود JSON. وجّه أي عميل MCP إلى العنوان أدناه بمفتاح Bearer نفسه.

عنوان الخادم

https://api.mangamade.com/api/mcp

Claude Code

claude mcp add --transport http mangamade \
  https://api.mangamade.com/api/mcp \
  --header "Authorization: Bearer mm_live_…"

Cursor وVS Code وغيرها (إعداد JSON)

{
  "mcpServers": {
    "mangamade": {
      "url": "https://api.mangamade.com/api/mcp",
      "headers": {
        "Authorization": "Bearer mm_live_…"
      }
    }
  }
}

الأدوات

get_account: مساحة العمل وباقتها ورصيدها وحدودها.
list_style_presets: الأساليب الجاهزة المتاحة للسلسلة.
list_series: سلاسل مساحة العمل.
get_series: سلسلة واحدة مع أسلوبها ومرجع قصتها.
create_series: إنشاء سلسلة من عنوان وشكل وأسلوب وفكرة.
create_style_anchor: رسم المرجع البصري لسلسلة، أو استخدام عيّنة مرفوعة (يستهلك أرصدة).
list_characters: شخصيات سلسلة.
create_character: إضافة شخصية إلى سلسلة.
generate_character_sheet: رسم ورقة شخصية (يستهلك أرصدة).
list_chapters: فصول سلسلة.
create_chapter: إنشاء فصل من ملخص.
get_chapter: فصل واحد مع نصه وحالته.
plan_chapter: كتابة نص الفصل من ملخصه.
get_chapter_pages: صفحات فصل ولوحاته.
estimate_generation: كلفة رسم فصل بالأرصدة.
generate_chapter: رسم لوحات فصل (يستهلك أرصدة).
list_generation_batches: تقدّم دفعات رسم فصل.
create_export: تصدير فصل بصيغة PNG أو PDF أو CBZ، وانتظار الملف وإرجاع رابط تنزيله.
get_export: حالة عملية تصدير ورابط تنزيلها.

للنماذج اللغوية

ننشر ملخصًا نصيًا لـ MangaMade، يشمل هذه الصفحة، لمساعدي الذكاء الاصطناعي ومحركات الإجابة.

اقرأ llms.txt

واجهة MangaMade البرمجية وخادم MCP