# יצירה וייצוא של PPT

צור מצגת, עקוב אחר ההתקדמות שלה, ייצא PPTX ונהל את משך חייה.

צרו מצגת באופן אסינכרוני, ואז ייצאו קובץ PPTX. הפרידו בין שלב היצירה לשלב הייצוא: משימה שנוצרה עדיין אינה קובץ גמור.

כל הדוגמאות משתמשות ב-`FELO_API_KEY` מתוך [הסקירה הכללית](https://openapi.felo.ai/he/docs/data-api/guides/felo-overview.md). הקריאות משתמשות ב-**יתרת הפלטפורמה**, ולא ב-Felo Pro credits. דוגמאות התגובה הן להמחשה; תוכן חי ושדות אופציונליים משתנים.

## זרימה ומזהים

1. צרו משימת יצירה; שמרו `task_id`, `ppt_business_id` ו-`expires_at`.
2. שאלו ב-poll את סטטוס היצירה באמצעות `task_id`.
3. קראו את תוצאות היצירה באמצעות `task_id`.
4. התחילו ייצוא PPTX באמצעות `ppt_business_id`.
5. שאלו ב-poll את סטטוס הייצוא והורידו את הקובץ המוגמר.
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 Key השייך לאותו חשבון. אם לא מוחזר 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/he/docs/api-reference/superagent.md#2-consume-sse-stream), עם כתובת ה-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`. בצעו polling במרווח מוגבל (למשל, 2–5 שניות) ועם דדליין. המשיכו לתוצאות לאחר השלמה; טפלו בכשל ובסטטוסים לא צפויים מבלי להניח הצלחה. דדליין של polling אינו מבטל את המשימה.

```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` הם אופציונליים. תגובה זו אינה URL מובטח להורדת 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 בזמן שאותו ייצוא עדיין רץ עושה reuse שלו. התחלת ייצוא נוסף לאחר השלמה יוצרת ייצוא חדש ויכולה לגרור חיוב נוסף. השתמשו ב-GET לצורך polling ורענון קישור ההורדה.

## 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"
}
```

כתובת ה-URL בדוגמה היא להמחשה. השתמשו ב-URL החתום בפועל מהתגובה. הוא תקף למשך **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` של URL ההורדה החתום מתארים משכי חיים שונים.
- רק חשבון ה-API שיצר יכול לגשת למשימות ולמצגות שלו. משאב חסר או לא נגיש יכול להחזיר 404; משאב שפג תוקפו או נמחק יכול להחזיר 410, או 404 לאחר ניקוי.
- היצירה מחויבת לפי עמוד שנוצר (`ppt.generate`). לפי תמחור עמודים, היצירה שומרת את המחיר של עשרה עמודים, ואז מסדירה את הפלט המוצלח בפועל ומשחררת את ההחזקה שלא נוצלה. לחשבון שלכם חייבת להיות יתרה זמינה מספקת עבור ההחזקה גם אם הפרומפט מבקש פחות עמודים.
- לייצוא יש מחיר בקשה נפרד (`ppt.export`). שאילתות סטטוס, שאילתות תוצאות, שאילתות סטטוס-ייצוא ומחיקה אינן יוצרות חיוב חדש.
- לאחר timeout, שאבו את המשימה השמורה במקום ליצור מצגת נוספת. ראו [חיוב ושגיאות](https://openapi.felo.ai/he/docs/data-api/guides/felo-billing.md).