Felo APIs

PPT Task API

أنشئ مهام توليد PPT، واعرض القوالب، واستعلم عن نقاط endpoint المهام المشتركة.

POST/v2/ppts

المصادقة

Bearer API key

نوع المحتوى

application/json

ملاحظات السعر

قد تنطبق حدود خاصة بـ endpoint.

LiveDoc API Landing Page Task API

يوفر PPT Task API قدرات توليد PPT غير متزامنة. يمكنك إنشاء مهمة ثم استطلاع حالة المهمة عبر task_id. ويمكنك أيضًا تصفح قوالب PPT المتاحة وتطبيقها عند إنشاء المهام.

هذا API غير متزامن. للنمط المشترك للإرسال والاستطلاع والاسترداد، راجع المهام غير المتزامنة.

المصادقة

تتطلب كل الطلبات مفتاح API في رأس Authorization:

Authorization: Bearer YOUR_API_KEY

الاستخدام مع وكلاء الذكاء الاصطناعي

لإنشاء شرائح من وكيل، ثبّت حزمة felo-ai الكاملة بدلًا من مجموعة مهارات ثابتة. يكتشف مثبّتها ديناميكيًا كل دليل حزمة يحتوي SKILL.md، بما في ذلك مهارة PPT والإضافات المستقبلية. ثبّت كل المهارات المكتشفة في الدليل الأصلي لوكيلك: Codex ~/.codex/skills أو Claude Code ~/.claude/skills أو OpenClaw ~/.agents/skills أو Hermes Agent ~/.hermes/skills. اتبع دليل إعداد وكيل الذكاء الاصطناعي اليدوي لضبط مفتاح API والتحقق منه حسب كل منصة.

1. List PPT Themes (قوالب العروض التقديمية)

استعلم عن قوالب PPT المتاحة مع ترقيم الصفحات والبحث بالكلمات المفتاحية والتصفية حسب اللغة والنوع.

Endpoint

GET https://openapi.felo.ai/v2/ppt-themes

معاملات الاستعلام

المعامل	النوع	مطلوب	الوصف
`lang`	string	لا	رمز اللغة للمحتوى المترجم (مثل `en` و`zh-Hans`). الافتراضي: `en`
`type`	string	لا	التصفية حسب نوع القالب (مثل `default` و`custom`)
`keyword`	string	لا	كلمة البحث المفتاحية، تطابق عناوين القوالب
`page`	integer	لا	رقم الصفحة، بدءًا من 1. الافتراضي: `1`
`size`	integer	لا	حجم الصفحة، بحد أقصى 100. الافتراضي: `20`

مثال

curl -X GET 'https://openapi.felo.ai/v2/ppt-themes?lang=en&page=1&size=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 8,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": "43122897-0d3c-4c9e-ae19-20527ad36c04",
        "title": "Inspiration Themes",
        "subtitle": "AI-tailored visual solutions",
        "description": "Style and layout, both crafted by AI from your content in real time"
      }
    ]
  }
}

حقول استجابة القوالب

الحقل	النوع	الوصف
`total`	integer	إجمالي عدد القوالب المطابقة للتصفية
`page`	integer	رقم الصفحة الحالية
`size`	integer	حجم الصفحة
`items`	array	قائمة كائنات القوالب
`items[].id`	string	معرّف القالب، استخدمه كـ`ai_theme_id` عند إنشاء PPT
`items[].title`	string	عنوان القالب (مترجم)
`items[].subtitle`	string	العنوان الفرعي للقالب (مترجم)
`items[].description`	string	وصف القالب (مترجم)

2. إنشاء مهمة PPT

Endpoint

POST https://openapi.felo.ai/v2/ppts

رؤوس الطلب

الرأس	مطلوب	الوصف
`Authorization`	نعم	مفتاح API الخاص بك بالصيغة `Bearer YOUR_API_KEY`
`Content-Type`	نعم	`application/json` أو `multipart/form-data`

نص الطلب

المعامل	النوع	مطلوب	الوصف
`query`	string	نعم	موجّه طلب توليد PPT
`livedoc_short_id`	string	لا	معرّف LiveDoc مختصر موجود لربطه بجلسة PPT. إذا حُذف، يُنشأ LiveDoc جديد تلقائيًا.
`resource_ids`	array of strings	لا	قائمة معرّفات موارد LiveDoc لاستخدامها كسياق لتوليد PPT
`ppt_config`	object	لا	خيارات إعداد PPT
`ppt_config.ai_theme_id`	string	لا	معرّف القالب من endpoint List PPT Themes

مثال

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Felo, 2 pages",
    "ppt_config": {
      "ai_theme_id": "02968979-a69f-42c4-b136-de02c40ab2d7"
    }
  }'

الإنشاء من ملف مرفوع

استخدم multipart/form-data لرفع ملف واحد وإنشاء مهمة PPT في طلب واحد. ترفع المنصة الملف أولًا كمورد LiveDoc، ثم تمرّر معرّف المورد إلى مهمة PPT.

الجزء	النوع	مطلوب	الوصف
`query`	string	نعم	موجّه طلب توليد PPT
`file`	file	نعم	ملف المصدر المستخدم كسياق لـPPT
`stream_protocol`	string	لا	بروتوكول البث؛ الافتراضي `message_center_v1`
`livedoc_short_id`	string	لا	LiveDoc موجود لاستقبال الملف. يُنشأ LiveDoc جديد عند حذفه.
`ppt_config`	JSON	لا	إعداد PPT بالبنية نفسها كنص طلب JSON. أرسل هذا الجزء كـ`application/json`.

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'query=Create a 10-page presentation based on this report' \
  -F 'ppt_config={"ai_theme_id":"02968979-a69f-42c4-b136-de02c40ab2d7"};type=application/json' \
  -F '[email protected]'

تستخدم الاستجابة المخطط نفسه كنص طلب JSON. ويحدد livedoc_short_id المُعاد LiveDoc الذي يحتوي المورد المرفوع.

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3",
    "ppt_business_id": "BfLPuQKmChk9SPmyQawxgr",
    "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9"
  }
}

3. استعلام حالة المهمة

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/status

مثال

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "RUNNING"
  }
}

4. الاستعلام عن المعلومات التاريخية للمهمة

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/historical

مثال

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cb17e-9e23-3d40-4447-48a651249460/historical' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة RUNNING

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "RUNNING",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

استجابة COMPLETED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "COMPLETED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

استجابة COMPLETED (AI_PAGE)

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019d7a4d-6ab5-a96d-0f98-43ca434ab621",
    "task_status": "COMPLETED",
    "ppt_biz_id": "9qiLTmT77fA3aVurrMHvRJ",
    "ppt_url": "https://felo.ai/slides/9qiLTmT77fA3aVurrMHvRJ",
    "ai_page_html": "https://felo.ai/ai-page/9qiLTmT77fA3aVurrMHvRJ"
  }
}

استجابة FAILED / PENDING / EXPIRED / CANCELED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "FAILED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "error_message": "PPT generation failed",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

حقول الاستجابة التاريخية

الحقل	النوع	الوصف
`task_id`	string	معرّف المهمة
`task_status`	string	حالة المهمة الحالية
`ppt_biz_id`	string	معرّف أعمال PPT (مأخوذ من `thread_short_id` في الواجهة الخلفية)
`ppt_url`	string	عنوان URL لـPPT، الصيغة: `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	يظهر في `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`؛ سلسلة فارغة `""` عندما لا توفّر الخدمة اللاحقة تفاصيل الخطأ
`ai_page_html`	string	يظهر عندما تعمل المهمة في وضع AI_PAGE وتعيد الخدمة اللاحقة التاريخية عنوان URL نتيجة HTML
`live_doc_short_id`	string	معرّف LiveDoc المختصر. في `COMPLETED` يأتي من `live_doc_short_id` في الخدمة اللاحقة؛ وفي حالات الفشل النهائية يُعاد عند توفره
`live_doc_url`	string	عنوان URL لـLiveDoc المقابل لـ`live_doc_short_id`

تصدير PPTX

بعد أن تصل مهمة توليد PPT إلى COMPLETED، أرسل تصديرًا غير متزامن باستخدام ppt_business_id من استجابة الإنشاء (أو ppt_biz_id من الاستجابة التاريخية):

curl -X POST 'https://openapi.felo.ai/v2/ppts/YOUR_PPT_BUSINESS_ID/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

استطلع GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export بمفتاح Bearer API نفسه كل 2–5 ثوانٍ. ويجب أن يكون مالك مفتاح API مالك PPT. يعيد endpointان الحقل data.status: NOT_STARTED أو PROCESSING أو COMPLETED أو FAILED. ولا يتضمن COMPLETED إلا download_url وexpires_at.

تنتهي صلاحية عنوان URL الموقّع للتنزيل بعد 30 دقيقة من إصداره. استدعِ endpoint GET مجددًا للحصول على عنوان جديد؛ وهذا لا يعيد توليد PPTX. يستخدم POST التنسيق application/json ويقبل {}. إعادة POST أثناء معالجة تصدير لا تبدأ مهمة أخرى؛ واستدعاؤه بعد الاكتمال يعيد توليد PPTX ويحتسب رسم أرصدة تصدير PPT الحالي. الأرصدة غير الكافية تعيد HTTP 402. وقد تُطبّق حدود معدل خاصة بـendpoint؛ أعد المحاولة لاحقًا عند HTTP 429. ويمكن إرسال التصدير الفاشل مرة أخرى.

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "COMPLETED",
    "download_url": "https://example.com/presentation.pptx?signature=...",
    "expires_at": "2026-09-29T10:30:00Z"
  }
}

توصية الاستطلاع

استخدم task_id من استجابة الإنشاء واستطلع الحالة كل 2-5 ثوانٍ حتى تصبح الحالة نهائية.

أمثلة الحالات الشائعة:

RUNNING: المهمة لا تزال قيد المعالجة
COMPLETED: اكتملت المهمة بنجاح
FAILED / PENDING / EXPIRED / CANCELED: وصلت المهمة إلى حالة نهائية مع error_message؛ ويُعاد live_doc_url أيضًا عند توفره

قد تظهر قيم حالة غير معروفة مع تطور الواجهة الخلفية؛ تعامل معها على أنها غير نهائية ما لم يذكر خلاف ذلك.

رموز الأخطاء

الرمز	حالة HTTP	الوصف
`UNAUTHORIZED`	401	مفتاح API غير صالح أو مُبطَل
`PPT_TASK_CREATE_FAILED`	502	فشل استدعاء إنشاء المهمة في الخدمة اللاحقة
`PPT_TASK_QUERY_FAILED`	502	فشل استدعاء استعلام حالة المهمة في الخدمة اللاحقة