# إنشاء عرض تقديمي Felo

POST /api/v1/data/ppts

أنشئ عرضًا تقديميًا بشكل غير متزامن، ثم صدّر ملف PPTX. افصل بين مرحلتي الإنشاء والتصدير: فالمهمة المُنشأة ليست ملفًا مكتملًا بعد.

تستخدم جميع الأمثلة `FELO_API_KEY` من [نظرة عامة](https://openapi.felo.ai/ar/docs/data-api/guides/felo-overview.md). تستخدم الاستدعاءات **رصيد المنصة**، وليس أرصدة Felo Pro. أمثلة الاستجابة توضيحية؛ ويختلف المحتوى الحي والحقول الاختيارية.





## 1. أنشئ العرض التقديمي

`POST /api/v1/data/ppts`

| الحقل | النوع | مطلوب | المعنى |
|---|---|---|---|
| `query` | string | نعم | تعليمات الإنشاء، 1–25,000 حرف |
| `stream_protocol` | string | لا | الافتراضي `message_center_v1`; اتركه عادة دون تغيير |
| `ppt_config` | object | لا | إعداد اختياري؛ يقرأ التنفيذ الحالي `ai_theme_id` |
| `livedoc_short_id` | string | لا | معرّف سياق موجود، حتى 100 حرف؛ يجب أن يجتاز فحوص ملكية واجهة API الأصلية وانتهاء الصلاحية |
| `resource_ids` | string array | لا | حتى 100 معرّف مورد UUID؛ ويخضع لنفس فحوص الوصول إلى السياق |

لأول تكامل، اترك حقول السياق والإعدادات فارغة. لا يصبح سياق أُنشئ عبر `/v2` مؤهلًا لإعادة الاستخدام هنا تلقائيًا.

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/ppts" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Create a 5-slide introduction to retrieval augmented generation for software developers."}'
```

يعيد HTTP 200 المعرفات في الجذر:

```json
{
  "task_id":"example-task-id",
  "ppt_business_id":"example-ppt-id",
  "livedoc_short_id":"example-livedoc-id",
  "expires_at":"2026-11-13T00:00:00Z"
}
```

قد تظهر معرفات إضافية مثل `resource_id` و`stream_key` و`thread_short_id`. تعني استجابة الإنشاء الناجحة أن المهمة قُبلت، لا أن الإنشاء قد اكتمل. عدد الشرائح المطلوب هو تعليمات؛ أما الفوترة فتستخدم العدد الفعلي للصفحات المُنشأة.

```bash
TASK_ID="example-task-id"
PPT_ID="example-ppt-id"
```

### اقرأ أحداث الإنشاء عبر SSE

إذا أعاد الإنشاء قيمة `stream_key`، فاتصل فورًا باستخدام مفتاح API يعود إلى الحساب نفسه. إذا لم يُعاد stream key، فاستخدم استعلامات الحالة والنتيجة أدناه.

```bash
curl -N 'https://openapi.felo.ai/api/v1/data/conversations/stream/YOUR_STREAM_KEY?format=structured' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream'
```

| معلمة الاستعلام | المعنى |
|---|---|
| `format` | يحافظ `raw` (الافتراضي) على سلسلة `content`; ويفك `structured` ترميز JSON الصالح إلى كائن أو مصفوفة |
| `offset` | موضع استئناف upstream اختياري لإعادة الاتصال؛ لا تستنتجه من عدد الأحداث المحلي لديك |

اقرأ كل حدث SSE مكتمل، وفك ترميز JSON الخارجي له، ثم عالج `content`. يحمل حدث التطبيق `answer` النص في `data.text`; ويشير `finished` إلى اكتمال الإنشاء في البث. تعامل أيضًا مع إشارات upstream `done` و`[DONE]` و`error`. إذا أُغلقت الاتصال دون إشارة اكتمال، فاستعلم عن حالة المهمة.

استخدم قواعد التحليل ومثال العميل في [SuperAgent SSE](https://openapi.felo.ai/ar/docs/api-reference/superagent.md#2-sse)، مع عنوان URL هذا القسم `/api/v1/data/conversations/stream/{stream_key}`. اقرأ نتيجة المهمة بعد انتهاء البث؛ يظل تصدير PPTX خطوة منفصلة. لا تُمكِّن هذه النقطة `stream: true` في `/api/v1/data/chat`.



## المدة والملكية والفوترة

- تنتهي صلاحية العروض التقديمية **بعد سبعة أيام من الإنشاء**. لا تؤدي الاستعلامات والتصديرات إلى تمديد هذه المدة. يصف `expires_at` الخاص بالعرض التقديمي و`expires_at` الخاص برابط التنزيل الموقّع مددًا مختلفة.
- لا يمكن الوصول إلى المهام والعروض التقديمية إلا عبر حساب API المنشئ لها. قد يؤدي مورد مفقود أو غير متاح إلى 404؛ وقد يؤدي مورد منتهي الصلاحية أو محذوف إلى 410، أو 404 بعد التنظيف.
- يُفوتر الإنشاء لكل صفحة مُنشأة (`ppt.generate`). وبموجب تسعير الصفحات، يحجز الإنشاء سعر عشر صفحات، ثم يسوّي المخرجات الناجحة الفعلية ويُحرر الحجز غير المستخدم. يحتاج حسابك إلى رصيد متاح كافٍ للحجز حتى لو طلب النص صفحات أقل.
- للتصدير سعر طلب منفصل (`ppt.export`). استعلامات الحالة، واستعلامات النتائج، واستعلامات حالة التصدير، والحذف لا تنشئ رسومًا جديدة.
- بعد انتهاء المهلة، استعلم عن المهمة المحفوظة بدلًا من إنشاء عرض آخر. راجع [الفوترة والأخطاء](https://openapi.felo.ai/ar/docs/data-api/guides/felo-billing.md).