Генерація та експорт 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 протягом усього робочого процесу. ID в прикладах є заповнювачами.

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, також можуть бути присутні. Успішна відповідь створення означає, що завдання прийнято, а не що генерацію завершено. Запитана кількість слайдів є інструкцією; білінг використовує фактичну кількість згенерованих сторінок.

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 сигналізує про завершення генерації у потоці. Також обробляйте сигнали upstream 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 на хост завантаження файлу.

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). Запити статусу, запити результатів, запити статусу експорту та видалення не створюють нового списання.
• Після тайм-ауту запитуйте збережене завдання, а не створюйте ще одну презентацію. Дивіться Білінг і помилки.