# Создать презентацию Felo

POST /api/v1/data/ppts

Генерируйте презентацию асинхронно, затем экспортируйте файл PPTX. Разделяйте шаги генерации и экспорта: созданная задача — это еще не готовый файл.

Во всех примерах используется `FELO_API_KEY` из [обзора](https://openapi.felo.ai/ru/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 array | Нет | До 100 UUID resource IDs; подлежат тем же проверкам доступа к контексту |

Для первой интеграции опустите поля контекста и конфигурации. Контекст, созданный через `/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`, могут присутствовать. Успешный ответ create означает, что задача принята, но не что генерация завершена. Запрошенное число слайдов — это инструкция; биллинг использует фактическое количество сгенерированных страниц.

```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` | Необязательная позиция возобновления на вышестоящем сервисе для переподключения; не выводите ее из числа локальных событий |

Читайте каждое полное SSE-событие, декодируйте его внешний JSON, затем обрабатывайте `content`. Событие приложения `answer` несет текст в `data.text`; `finished` сигнализирует о завершении генерации в потоке. Также обрабатывайте сигналы вышестоящего `done`, `[DONE]` и `error`. Если соединение закрывается без сигнала завершения, запросите статус задачи.

Используйте правила разбора и пример клиента из [SuperAgent SSE](https://openapi.felo.ai/ru/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/ru/docs/data-api/guides/felo-billing.md).