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

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

Читайте события генерации через SSE

Если при создании возвращается stream_key, подключитесь немедленно с API key, принадлежащим той же учетной записи. Если 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 сигнализирует о завершении генерации в потоке. Также обрабатывайте сигналы вышестоящего 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 необязательны. Этот ответ не является гарантированным URL для загрузки 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"
}

Пример URL носит иллюстративный характер. Используйте фактический подписанный URL из ответа. Он действителен 30 минут; GET статуса экспорта может вернуть новую ссылку, пока презентация остается доступной. Сохраните файл в пределах срока его действия. Не отправляйте свой Felo API key хосту загрузки файла.

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 подписанного URL загрузки описывают разные сроки жизни.
• Только API-аккаунт, создавший презентацию, может получать доступ к своим задачам и презентациям. Отсутствующий или недоступный ресурс может вернуть 404; просроченный или удаленный ресурс может вернуть 410, либо 404 после очистки.
• Генерация тарифицируется за каждую сгенерированную страницу (ppt.generate). При тарификации по страницам создание резервирует стоимость десяти страниц, затем окончательно учитывает фактически успешный результат и освобождает неиспользованный резерв. На вашем аккаунте должно быть достаточно доступного баланса для резерва, даже если в запросе указано меньше страниц.
• Экспорт имеет отдельную цену за запрос (ppt.export). Запросы статуса, запросы результатов, запросы статуса экспорта и удаление не создают нового списания.
• После тайм-аута запросите сохраненную задачу, а не создавайте другую презентацию. См. Биллинг и ошибки.