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

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

تستخدم جميع الأمثلة FELO_API_KEY من نظرة عامة. تستخدم الاستدعاءات رصيد المنصة، وليس أرصدة 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

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

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 المعرفات في الجذر:

{
  "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. تعني استجابة الإنشاء الناجحة أن المهمة قُبلت، لا أن الإنشاء قد اكتمل. عدد الشرائح المطلوب هو تعليمات؛ أما الفوترة فتستخدم العدد الفعلي للصفحات المُنشأة.

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

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

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

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'

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

استخدم قواعد التحليل ومثال العميل في SuperAgent 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

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 ثوانٍ) ومع مهلة نهائية. واصل إلى النتائج بعد الاكتمال؛ وتعامل مع الفشل والحالات غير المتوقعة دون افتراض النجاح. لا يؤدي تحديد مهلة للاستطلاع إلى إلغاء المهمة.

{"status":"COMPLETED"}

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

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

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

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

{
  "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

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

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

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

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

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

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

{
  "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}

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). استعلامات الحالة، واستعلامات النتائج، واستعلامات حالة التصدير، والحذف لا تنشئ رسومًا جديدة.
• بعد انتهاء المهلة، استعلم عن المهمة المحفوظة بدلًا من إنشاء عرض آخر. راجع الفوترة والأخطاء.