# إنشاء وتصدير PPT

أنشئ عرضًا تقديميًا، وتابع تقدمه، وصدّر ملف PPTX، وأدر مدة بقائه.

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

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

## سير العمل والمعرّفات

1. أنشئ مهمة إنشاء؛ واحفظ `task_id` و`ppt_business_id` و`expires_at`.
2. استطلع حالة الإنشاء باستخدام `task_id`.
3. اقرأ نتائج الإنشاء باستخدام `task_id`.
4. ابدأ تصدير PPTX باستخدام `ppt_business_id`.
5. استطلع حالة التصدير ونزّل الملف المكتمل.
6. يمكن حذف العرض التقديمي مبكرًا اختياريًا.

في عناصر نائب المسار، يعني `{business_id}` القيمة المُعادة **`ppt_business_id`**، وليس `task_id` أو `resource_id` أو `livedoc_short_id`. استخدم حساب API نفسه طوال سير العمل بأكمله. المعرفات في الأمثلة مجرد عناصر نائبة.

## 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`.

## 2. استطلع حالة الإنشاء

`GET /api/v1/data/tasks/{task_id}/status`

```bash
curl -sS --request GET "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/status" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

تحتوي الاستجابة على سلسلة `status` في الجذر، مثل `RUNNING` أو `COMPLETED`. استطلع ضمن فاصل زمني محدود (مثلًا، 2–5 ثوانٍ) ومع مهلة نهائية. واصل إلى النتائج بعد الاكتمال؛ وتعامل مع الفشل والحالات غير المتوقعة دون افتراض النجاح. لا يؤدي تحديد مهلة للاستطلاع إلى إلغاء المهمة.

```json
{"status":"COMPLETED"}
```

## 3. اقرأ نتائج الإنشاء

`POST /api/v1/data/tasks/{task_id}/historical`

هذه عملية **POST**، ولا تتطلب جسم JSON.

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/historical" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

```json
{
  "task_id":"example-task-id",
  "task_status":"COMPLETED",
  "history_data":{},
  "error_message":null
}
```

اقرأ `task_status` قبل استخدام `history_data`. قد يختلف حمولة السجل بحسب المهمة وقد تكون null. كل من `ai_page_html` و`thread_short_id` اختياريان. هذه الاستجابة ليست رابط تنزيل PPTX مضمونًا؛ استخدم التصدير بعد ذلك.

## 4. ابدأ تصدير PPTX

`POST /api/v1/data/ppts/{business_id}/export`

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

```json
{"status":"PROCESSING","download_url":null,"expires_at":null}
```

يجب أن يكون الإنشاء قد اكتمل قبل أن تصدّر. يؤدي تكرار POST أثناء تشغيل التصدير نفسه إلى إعادة استخدامه. إن بدء تصدير آخر بعد الاكتمال ينشئ تصديرًا جديدًا وقد يترتب عليه خصم آخر. استخدم GET للاستطلاع وتجديد رابط التنزيل.

## 5. استطلع التصدير ونزّل الملف

`GET /api/v1/data/ppts/{business_id}/export`

```bash
curl -sS --request GET "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

| الحالة | الإجراء التالي |
|---|---|
| `NOT_STARTED` | أرسل التصدير مرة واحدة |
| `PROCESSING` | انتظر، ثم استطلع GET مرة أخرى |
| `COMPLETED` | اقرأ `download_url` ونزّل الملف |
| `FAILED` | افحص الخطأ وحالة المهمة قبل إرسال تصدير جديد |

```json
{
  "status":"COMPLETED",
  "download_url":"https://example.com/presentation.pptx?signature=example",
  "expires_at":"2026-11-06T00:30:00Z"
}
```

رابط المثال توضيحي. استخدم رابط التوقيع الفعلي من الاستجابة. وهو صالح لمدة **30 دقيقة**; يمكن لاستعلام حالة التصدير عبر GET أن يعيد رابطًا جديدًا بينما يظل العرض التقديمي متاحًا. احفظ الملف ضمن فترة صلاحيته. لا ترسل مفتاح Felo API الخاص بك إلى مضيف تنزيل الملف.

## 6. احذف العرض التقديمي

`DELETE /api/v1/data/ppts/{business_id}`

```bash
curl -sS --request DELETE "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

يعيد النجاح **HTTP 204 بدون جسم**. لا تحلله كـ JSON. يؤدي الحذف أثناء تشغيل الإنشاء إلى 409.

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

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