# المقدمة يوفر فريق PPT.AI الهندسي مجموعة كاملة من واجهات API. يمكنك التكامل باستخدام أي لغة برمجة تفضلها. # المتطلبات المسبقة **نطاق واجهة برمجة التطبيقات (API) الأساسي هو نفس المضيف الذي تزوره الآن.** **يجب تضمين الرؤوس التالية في جميع طلبات API:** ```json { "Api-Secret": "Api-Secret لحسابك", "X-Requested-With": "XMLHttpRequest" // يساعد على التعرف على الطلب كاستدعاء API } ``` # استجابات API **عادةً ما يكون رمز حالة HTTP هو 200. ويكون جسم الاستجابة كما يلي:** ```json { "code": 200, // 200 تعني نجاح، القيم الأخرى أخطاء "message": "success", // في حال الخطأ تتضمن الرسالة تفاصيل "data": { ... } } ``` # إنشاء مهمة **الوصف:** استدعِ هذه الواجهة للحصول على **معرّف مهمة** لبدء مهمة إنشاء PPT. تتطلب الخطوات اللاحقة هذا المعرّف. **الطلب** - Url: /api/ppt/createTask - Method: POST | الحقل | القيم | مطلوب | الوصف | |---------|----------------------|-------|-------| | type | text\|url\|file | نعم | النوع:
text: نص
url: رابط ويب
file: رفع ملف | | content | String | لا | المحتوى:
type=text: نص (≤ 20000 حرف)
type=url: رابط (http/https)
type=file: اتركه فارغًا | | file | File | لا | مطلوب عند type=file (≤ 51200 بايت)
مدعوم: .doc,.docx,.pdf,.ppt,.pptx,.txt,.md,.xls,.xlsx,.csv,.html,.epub,.mobi,.xmind,.mm | **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "id": "xxx" // معرف المهمة } } ``` # إنشاء المخطط والمحتوى **الوصف:** إنشاء المخطط والمحتوى بناءً على **معرّف المهمة**. **الطلب** - Url: /api/ppt/generateContent - Method: POST **جسم الطلب** ```json { "id": "xxx", // معرف المهمة "length": "medium", // طول المحتوى "scene": null, // سياق العرض "audience": null, // الجمهور "lang": null, // اللغة "prompt": null // طلب المستخدم (أقل من 50 حرفًا) } ``` **ملاحظات** حقل "prompt" يعمل فقط عند كون نوع المهمة text أو upload، ويتم تجاهله لغير ذلك. **استجابة متدفقة (event-stream)** ```json {"text": "#", "status": 3} {"text": " ", "status": 3} {"text": "الموضوع", "status": 3} {"text": "1.1 المخطط", "status": 3} ...... ``` # إنشاء PPT **الوصف:** إنشاء PPT استنادًا إلى مخطط بصيغة Markdown. **الطلب** - Url: /api/ppt/generatePptx - Method: POST **جسم الطلب** ```json { "task_id": "xxx", // معرف المهمة "template_id": "xxx", // معرف القالب "content": "# الموضوع ## القسم ### عنوان الصفحة #### عنوان المحتوى - المحتوى", // مخطط Markdown } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "id": "xxx" // ppt id } } ``` # تنزيل PPT **الوصف:** الحصول على رابط تنزيل PPT. **الطلب** - Url: /api/ppt/downloadPptx - Method: GET **معاملات URL** ```json { "id": "xxx" // ppt id } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "link": "xxx" // رابط التنزيل } } ``` # الحصول على خيارات الإنشاء **الوصف:** استدعِ هذه الواجهة للحصول على قوائم الخيارات المستخدمة لإنشاء المخطط. **الطلب** - Url: /api/ppt/options - Method: GET **معاملات URL** ```json { "lang": null // يحدد لغة حقول data.name أدناه، الافتراضي en } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "lang": [ {"name": "الصينية المبسطة", "value": "zh"}, {"name": "English", "value": "en"}, ... ], "scene": [ {"name": "عام", "value": "通用场景"}, ... ], "audience": [ {"name": "الجمهور العام", "value": "大众"}, ... ] } } ``` # الحصول على قائمة القوالب **الوصف:** استعلام عن القوالب مع ترقيم الصفحات. **الطلب** - Url: /api/ppt/templates - Method: GET **معاملات URL** ```json { "page": 1, "size": 10, "lang": null, "category": null, "style": null, "themeColor": null, } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "templates": [ { "id": 1792803733332242432, "cover": "https://xxx.png", "lang": "zh", "category": "企业介绍", "style": "创意时尚", "color": "#7664FA" } ... ] } } ``` # الحصول على خيارات تصفية القوالب **الوصف:** الحصول على خيارات التصفية لاستعلام القوالب. **الطلب** - Url: /api/ppt/template/options - Method: GET **معاملات URL** ```json { "lang": null // يحدد لغة حقول data.name أدناه، الافتراضي en } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "themeColor": [ { "name": "ALL", "value": "" }, { "name": "Orange", "value": "#FA920A" } ... ], "style": [ { "name": "ALL", "value": "" }, { "name": "Flat and simple", "value": "扁平简约" } ... ], "category": [ { "name": "ALL", "value": "" }, { "name": "Year end summary", "value": "年终总结" } ... ] } } ``` # رفع قالب مخصص **الوصف:** رفع القوالب المعرّفة من قبل المستخدم **الطلب** - الرابط: /api/ppt/uploadTemplate - الطريقة: POST **جسم الطلب** ```json { "file": file upload // مدعوم: .pptx(≤ 10,240 بايت) } ``` **نص الاستجابة** ```json { "code": 200, "message": "success", "data": { "id": 1792803733332242432, "cover": "xxxx", // بيانات صورة PNG مشفرة بـ base64 الخام (بدون بادئة URI للبيانات) } } ``` # نظرة عامة على النسخة الاحترافية تصمم النسخة الاحترافية العرض التقديمي صفحةً تلو الأخرى باستخدام الذكاء الاصطناعي. وهي تدعم وضعين للإخراج يُختاران عبر المعامل `mode` عند إنشاء الجلسة: | mode | الناتج | ملاحظات | |------|--------|---------| | professional | كل صفحة بصيغة HTML | يبقى النص والتخطيط قابلين للتعديل؛ التصدير إلى PDF / PPTX (صور أو قابل للتعديل) / PNG / HTML | | creative | كل صفحة صورة كاملة مولّدة بالذكاء الاصطناعي (مغلّفة في HTML) | أغنى بصريًا، ولا يمكن تعديل نص الصفحة مباشرةً؛ تتم المراجعة عبر الدردشة | **سير العمل** 1. (اختياري) ارفع مستندًا مرجعيًا للحصول على `attachment_id` 2. أنشئ جلسة. يُنشئ النظام استبيانًا قصيرًا بشكل غير متزامن 3. استعلم عن حالة الجلسة دوريًا. عندما تكون `phase=questions` و`generating=false`، اقرأ `questions` 4. استدعِ advance مع `answers`: يُنشأ المخطط (بشكل متزامن، وقد يستغرق 10–60 ثانية) وتصبح `phase` هي `outline` 5. استدعِ advance مرة أخرى لتأكيد المخطط: تصبح `phase` هي `templates` 6. استدعِ advance مع `template_id`: **يتم خصم الأرصدة هنا**، وتُنشأ الصفحات بشكل غير متزامن وتصبح `phase` هي `slides` 7. استعلم عن حالة الجلسة حتى `phase=done`، ثم اجلب HTML الصفحات أو صدّر الملفات 8. استخدم الدردشة لمواصلة تحسين العرض (تعديل الصفحات، إضافتها أو حذفها، تغيير نمط العرض بالكامل) **الفوترة** - يتم احتساب الإنشاء مرة واحدة عند بدء إنشاء الصفحات: `generate_base + generate_per_page × pages`. تُعاد الأسعار لكل نموذج ووضع عبر واجهة الخيارات - تُحتسب تعديلات الدردشة على العرض المكتمل لكل عملية (`edit` لكل صفحة معدّلة، و`add` لكل صفحة مضافة؛ حذف الصفحات مجاني). الدردشة في مرحلة الاستبيان / المخطط مجانية - إذا فشل الإنشاء أو التعديل، تُعاد الأرصدة غير المستخدمة تلقائيًا. تظهر عمليات الخصم والاسترداد في قائمة الفواتير - يمكن تشغيل عدة جلسات في الحساب نفسه في الوقت ذاته. تُعالج الطلبات على الجلسة نفسها واحدًا تلو الآخر؛ ويُعيد الطلب المتعارض `409` **مراحل الجلسة (phase)** | phase | المعنى | الخطوة التالية | |-------|--------|----------------| | questions | الاستبيان | advance (answers) | | outline | المخطط جاهز | advance للتأكيد، أو chat لتعديل المخطط | | templates | اختيار القالب | advance (template_id) | | slides | إنشاء الصفحات | استعلام دوري؛ استدعِ retry إذا كان `error` محددًا | | done | مكتمل | page / export / chat / retheme | **رموز أخطاء النسخة الاحترافية** | code | message | المعنى | |------|---------|--------| | 402 | need_recharge | الأرصدة غير كافية، `data.need_points` هو السعر و`data.points` رصيدك | | 409 | conflict | غير مسموح في المرحلة الحالية، أو أن الرسالة السابقة ما زالت قيد المعالجة | | 422 | validation_error / moderation_text / moderation_image | معاملات غير صالحة، أو رُفض المحتوى من قبل الإشراف | | 404 | not_found | الجلسة غير موجودة | | 429 | frequently | طلبات كثيرة جدًا على الجلسة نفسها، أعد المحاولة لاحقًا | | 202 | export_generating | ملف التصدير قيد المعالجة، أعد المحاولة لاحقًا | # النسخة الاحترافية: حالة الجلسة **الوصف:** استعلم عن هذه الواجهة دوريًا (يُنصح كل 3–5 ثوانٍ) لمتابعة التقدم. تُعيد واجهات advance وchat وretheme وretry وstop الكائن نفسه. **الطلب** - Url: /api/slides/{uuid} - Method: GET **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "uuid": "xxx", "phase": "questions", // questions | outline | templates | slides | done "status": "pending", // تصبح success عند اكتمال العرض "mode": "professional", // professional | creative "model": "google/gemini-3-flash-preview", "language": "en", "title": "xxx", // عنوان العرض "generating": true, // جارٍ إنشاء الاستبيان أو الصفحات "chat_pending": false, // رسالة دردشة قيد المعالجة "progress": {"done": 3, "total": 8, "current": "xxx"}, // تقدم إنشاء الصفحات، في مرحلة slides فقط "error": null, // نص الخطأ عند فشل الإنشاء؛ استدعِ retry "questions": [ { "id": "q_slide_count", "title": "كم عدد الشرائح؟", "type": "single", // single | multi | text "options": ["5-8", "9-12", "دع الذكاء الاصطناعي يقرر"], "recommended": null, "allow_other": true } ], "answers": {}, "outline": [ {"page": 1, "title": "xxx", "layout": "cover", "key_message": "xxx"} ], "template_id": "12", "page_count": 8, "pages": [ {"index": 0, "title": "xxx"} ], "messages": [ {"role": "user", "content": "xxx", "ts": 1760000000}, {"role": "assistant", "content": "xxx", "ts": 1760000000} ], "points": 1000 // الأرصدة المتبقية } } ``` **ملاحظات** عندما تتطلب رسالة دردشة على عرض creative إعادة رسم أكثر من صفحتين، تحمل آخر رسالة من المساعد الحقل `confirm` (مع `cost`). أرسل الرسالة نفسها مرة أخرى مع `confirm_cost` للمتابعة. # النسخة الاحترافية: الحصول على الخيارات **الوصف:** الحصول على الأوضاع والنماذج المتاحة ونطاق عدد الصفحات والأسعار ورصيدك الحالي. **الطلب** - Url: /api/slides/options - Method: GET **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "modes": ["professional", "creative"], "models": [ {"value": "google/gemini-3-flash-preview", "label": "Gemini 3 Flash"} ], "min_pages": 4, "max_pages": 40, "pricing": { "professional": { "google/gemini-3-flash-preview": {"generate_base": 9, "generate_per_page": 3, "edit": 1, "add": 2} }, "creative": {"generate_base": 9, "generate_per_page": 4, "edit": 4, "add": 4} }, "points": 1000 } } ``` # النسخة الاحترافية: قائمة القوالب **الوصف:** القوالب الرسمية مع ترقيم الصفحات، 12 قالبًا في كل صفحة. **الطلب** - Url: /api/slides/templates - Method: GET **معاملات URL** ```json { "offset": 0 // 0, 12, 24 ... } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "templates": [ {"id": "12", "cover": "https://xxx.jpg", "brand_color": "#2B59FF", "dark_mode": false, "mine": false} ], "hasMore": true } } ``` # النسخة الاحترافية: رفع مرفق **الوصف:** رفع مستند مرجعي. يُستخدم نصه كمادة مصدرية للاستبيان والمخطط والدردشة. صالح لمدة ساعتين. **الطلب** - Url: /api/slides/attachment - Method: POST (multipart/form-data) | الحقل | القيم | مطلوب | الوصف | |-------|-------|-------|-------| | file | File | نعم | .txt / .md / .pdf / .docx / .pptx، بحد أقصى 15 ميغابايت | **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "id": "xxx", // attachment_id "name": "report.pdf", "chars": 12000 } } ``` # النسخة الاحترافية: إنشاء جلسة **الوصف:** أرسل موضوعًا لإنشاء جلسة. يُنشأ الاستبيان بشكل غير متزامن. لا يتم خصم أي أرصدة في هذه الخطوة. **الطلب** - Url: /api/slides/create - Method: POST **جسم الطلب** ```json { "topic": "xxx", // مطلوب، بحد أقصى 5000 حرف "mode": "professional", // professional | creative، الافتراضي professional "model": null, // قيمة من options.models؛ الافتراضي هو الأول (يُتجاهل لصور صفحات creative) "language": null, // لغة العرض مثل en وzh-CN وja؛ تُكتشف تلقائيًا عند إغفالها "attachment_id": null // من واجهة رفع المرفق } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "uuid": "xxx" // معرّف الجلسة } } ``` # النسخة الاحترافية: التقدم للمرحلة التالية **الوصف:** نقل الجلسة إلى المرحلة التالية. يعتمد ما يحدث على المرحلة الحالية: | المرحلة الحالية | المعاملات | النتيجة | |-----------------|-----------|---------| | questions | answers | يُنشئ المخطط (بشكل متزامن)، وينتقل إلى outline | | outline | لا يوجد | يؤكد المخطط، وينتقل إلى templates | | templates | template_id | **يخصم الأرصدة** ويبدأ إنشاء الصفحات، وينتقل إلى slides | **الطلب** - Url: /api/slides/{uuid}/advance - Method: POST **جسم الطلب** ```json { "answers": { "q_slide_count": "10", // معرّف السؤال => الإجابة؛ يقبل عدد الصفحات رقمًا "q_audience": "المستثمرون" // أسئلة الاختيار المتعدد تقبل مصفوفة }, "template_id": "12" // مطلوب في مرحلة templates } ``` **جسم الاستجابة**: كائن حالة الجلسة # النسخة الاحترافية: الدردشة **الوصف:** واجهة محادثة واحدة لجميع التعديلات. تُوجّه الطلب تلقائيًا حسب المرحلة: - questions / outline: تعديل الاستبيان أو المخطط (مجانًا) - done: تعديل الصفحات، إضافة الصفحات أو حذفها، تغيير نمط العرض بالكامل. يحوّل الذكاء الاصطناعي الرسالة إلى عمليات ويحتسب كل عملية تُعالج الرسالة بشكل غير متزامن؛ استعلم عن حالة الجلسة حتى `chat_pending=false` واقرأ الرد في `messages`. **الطلب** - Url: /api/slides/{uuid}/chat - Method: POST **جسم الطلب** ```json { "message": "اجعل الصفحة 3 جدول مقارنة", // مطلوب، بحد أقصى 2000 حرف "page": null, // الصفحة المستهدفة (تبدأ من 1)، في مرحلة done فقط؛ يحدد الذكاء الاصطناعي الصفحة عند إغفالها "attachment_id": null, // مادة مرجعية إضافية "confirm_cost": 0 // إعادة رسم عدة صفحات في creative: أرسل cost من رسالة confirm للمتابعة } ``` **جسم الاستجابة**: كائن حالة الجلسة # النسخة الاحترافية: تغيير القالب **الوصف:** إعادة إنشاء عرض مكتمل (phase=done) بقالب آخر. يُحتسب مثل الإنشاء الكامل. **الطلب** - Url: /api/slides/{uuid}/retheme - Method: POST **جسم الطلب** ```json { "template_id": "12" } ``` **جسم الاستجابة**: كائن حالة الجلسة # النسخة الاحترافية: إعادة المحاولة **الوصف:** استخدمها عندما يكون `error` محددًا. في مرحلة questions يُعاد إنشاء الاستبيان؛ وفي مرحلة slides يُستأنف الإنشاء من حيث توقف (تُحفظ الصفحات المُنشأة مسبقًا ولا تُحتسب مرة أخرى). **الطلب** - Url: /api/slides/{uuid}/retry - Method: POST **جسم الاستجابة**: كائن حالة الجلسة # النسخة الاحترافية: الإيقاف **الوصف:** إيقاف إنشاء الاستبيان / الصفحات أو تعديل دردشة قيد التنفيذ. تُحفظ الصفحات المُنشأة مسبقًا؛ استدعِ retry للمتابعة. **الطلب** - Url: /api/slides/{uuid}/stop - Method: POST **جسم الاستجابة**: كائن حالة الجلسة # النسخة الاحترافية: HTML الصفحة **الوصف:** الحصول على HTML الكامل لصفحة واحدة (يبدأ index من 0). كل صفحة مستند HTML مستقل بنسبة 16:9 يمكن عرضه في iframe أو WebView. **الطلب** - Url: /api/slides/{uuid}/page/{index} - Method: GET **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "index": 0, "file": "01.html", "title": "xxx", "html": "..." } } ``` # النسخة الاحترافية: التصدير **الوصف:** تصدير عرض مكتمل. عندما يكون الملف ما زال قيد المعالجة، يُعاد `code=202`؛ أعد الاستدعاء بعد بضع ثوانٍ حتى يُعاد رابط التنزيل. الرابط صالح لمدة 5 دقائق. **الطلب** - Url: /api/slides/{uuid}/export - Method: POST **جسم الطلب** ```json { "format": "pptx", // pdf | pptx | png (zip) | html "mode": "visual" // لـ pptx فقط: visual (صور الصفحات) | editable (نص قابل للتعديل) } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "download_url": "https://xxx" } } ``` # النسخة الاحترافية: قائمة الجلسات **الوصف:** جلسات حسابك مع ترقيم الصفحات، الأحدث أولًا. **الطلب** - Url: /api/slides/list - Method: GET **معاملات URL** ```json { "page": 1, "per_page": 20 // بحد أقصى 50 } ``` **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": { "slides": [ {"uuid": "xxx", "subject": "xxx", "cover": "https://xxx.jpg", "created_at": 1760000000, "page_count": 8, "mode": "professional", "phase": "done", "draft": false} ], "page": 1, "per_page": 20, "total": 1, "has_more": false } } ``` # النسخة الاحترافية: حذف الجلسة **الوصف:** حذف الجلسة وجميع ملفاتها نهائيًا. لا يمكن التراجع عن هذا الإجراء. **الطلب** - Url: /api/slides/{uuid}/delete - Method: POST **جسم الاستجابة** ```json { "code": 200, "message": "success", "data": [] } ```