# Генерація та експорт PPT

Створюйте презентацію, відстежуйте її прогрес, експортуйте файл PPTX і керуйте її життєвим циклом.

Генеруйте презентацію асинхронно, а потім експортуйте файл PPTX. Тримайте кроки генерації та експорту окремо: створене завдання ще не є готовим файлом.

У всіх прикладах використовується `FELO_API_KEY` з [огляду](https://openapi.felo.ai/uk/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 протягом усього робочого процесу. ID в прикладах є заповнювачами.

## 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 | Ні | Існуючий ID контексту, до 100 символів; має проходити нативні перевірки власності API та терміну дії |
| `resource_ids` | масив string | Ні | До 100 UUID ID ресурсів; підлягає тим самим перевіркам доступу до контексту |

Для першої інтеграції пропустіть поля контексту та конфігурації. Контекст, створений через `/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/uk/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` є необов’язковими. Ця відповідь не є гарантованим 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 під час роботи того самого експорту повторно використовує його. Запуск іншого експорту після завершення створює новий експорт і може спричинити ще одне списання. Для опитування та оновлення посилання для завантаження використовуйте 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"
}
```

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`). Запити статусу, запити результатів, запити статусу експорту та видалення не створюють нового списання.
- Після тайм-ауту запитуйте збережене завдання, а не створюйте ще одну презентацію. Дивіться [Білінг і помилки](https://openapi.felo.ai/uk/docs/data-api/guides/felo-billing.md).