# Felo Створення презентації

POST /api/v1/data/ppts

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

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



## Життєвий цикл, право доступу та білінг

- Презентації закінчують термін дії **через сім днів після створення**. Запити та експорти не подовжують цей період. `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).