Felo APIs

PPT Task API

Створюйте завдання генерування PPT, переглядайте теми й опитуйте спільні endpoint завдань.

POST/v2/ppts

Автентифікація

Bearer API key

Тип вмісту

application/json

Примітки щодо обмежень

Можуть діяти обмеження для окремих endpoint.

LiveDoc API Landing Page Task API

PPT Task API надає можливості асинхронної генерації PPT. Ви можете створити завдання, а потім опитувати його статус за task_id. Також можна переглядати доступні теми PPT і застосовувати їх під час створення завдань.

Це асинхронний API. Про спільну схему надсилання, опитування та отримання див. Асинхронні завдання.

Автентифікація

Усі запити потребують API-ключа в заголовку Authorization:

Authorization: Bearer YOUR_API_KEY

Використання з агентами ШІ

Щоб створювати слайди з агента, установіть повний пакет felo-ai, а не фіксований набір Skills. Його інсталятор динамічно знаходить кожен каталог пакета, що містить SKILL.md, зокрема PPT Skill і майбутні доповнення. Установіть усі знайдені Skills у рідний каталог для вашого агента: Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills або Hermes Agent ~/.hermes/skills. Дотримуйтеся посібника з ручного налаштування агента ШІ, щоб дізнатися про налаштування API-ключа та перевірку для кожної платформи.

1. Список тем PPT

Отримайте доступні теми PPT із посторінковим виводом, пошуком за ключовим словом і фільтрацією за мовою та типом.

Endpoint

GET https://openapi.felo.ai/v2/ppt-themes

Параметри запиту

Параметр	Тип	Обов'язковий	Опис
`lang`	string	Ні	Код мови для локалізованого вмісту (напр. `en`, `zh-Hans`). За замовчуванням: `en`
`type`	string	Ні	Фільтр за типом теми (напр. `default`, `custom`)
`keyword`	string	Ні	Ключове слово для пошуку; збігається із заголовками тем
`page`	integer	Ні	Номер сторінки, починаючи з 1. За замовчуванням: `1`
`size`	integer	Ні	Розмір сторінки, до 100. За замовчуванням: `20`

Приклад

curl -X GET 'https://openapi.felo.ai/v2/ppt-themes?lang=en&page=1&size=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Успішна відповідь (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 8,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": "43122897-0d3c-4c9e-ae19-20527ad36c04",
        "title": "Inspiration Themes",
        "subtitle": "AI-tailored visual solutions",
        "description": "Style and layout, both crafted by AI from your content in real time"
      }
    ]
  }
}

Поля відповіді теми

Поле	Тип	Опис
`total`	integer	Загальна кількість тем, що відповідають фільтру
`page`	integer	Номер поточної сторінки
`size`	integer	Розмір сторінки
`items`	array	Список об'єктів тем
`items[].id`	string	ID теми; використовуйте його як `ai_theme_id` під час створення PPT
`items[].title`	string	Заголовок теми (локалізований)
`items[].subtitle`	string	Підзаголовок теми (локалізований)
`items[].description`	string	Опис теми (локалізований)

2. Створити завдання PPT

Endpoint

POST https://openapi.felo.ai/v2/ppts

Заголовки запиту

Заголовок	Обов'язковий	Опис
`Authorization`	Так	Ваш API-ключ у форматі `Bearer YOUR_API_KEY`
`Content-Type`	Так	`application/json` або `multipart/form-data`

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
`query`	string	Так	Запит-підказка для генерації PPT
`livedoc_short_id`	string	Ні	Короткий ID наявного LiveDoc, який потрібно пов'язати із сеансом PPT. Якщо не вказано, новий LiveDoc створюється автоматично.
`resource_ids`	array of strings	Ні	Список ID ресурсів LiveDoc, які використовуватимуться як контекст для генерації PPT
`ppt_config`	object	Ні	Параметри конфігурації PPT
`ppt_config.ai_theme_id`	string	Ні	ID теми з endpoint Список тем PPT

Приклад

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Felo, 2 pages",
    "ppt_config": {
      "ai_theme_id": "02968979-a69f-42c4-b136-de02c40ab2d7"
    }
  }'

Створення із завантаженого файлу

Використовуйте multipart/form-data, щоб завантажити один файл і створити завдання PPT в одному запиті. Платформа спершу завантажує файл як ресурс LiveDoc, а потім передає його ID ресурсу завданню PPT.

Частина	Тип	Обов'язкова	Опис
`query`	string	Так	Запит-підказка для генерації PPT
`file`	file	Так	Вихідний файл, що використовується як контекст PPT
`stream_protocol`	string	Ні	Протокол потокової передачі; за замовчуванням `message_center_v1`
`livedoc_short_id`	string	Ні	Наявний LiveDoc, до якого потрібно додати файл. Якщо не вказано, створюється новий LiveDoc.
`ppt_config`	JSON	Ні	Конфігурація PPT із тією самою структурою, що й тіло JSON-запиту. Надсилайте цю частину як `application/json`.

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'query=Create a 10-page presentation based on this report' \
  -F 'ppt_config={"ai_theme_id":"02968979-a69f-42c4-b136-de02c40ab2d7"};type=application/json' \
  -F '[email protected]'

Відповідь використовує ту саму схему, що й JSON-запит. Повернутий livedoc_short_id ідентифікує LiveDoc, що містить завантажений ресурс.

Успішна відповідь (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3",
    "ppt_business_id": "BfLPuQKmChk9SPmyQawxgr",
    "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9"
  }
}

3. Отримати статус завдання

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/status

Приклад

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Успішна відповідь (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "RUNNING"
  }
}

4. Отримати історію завдання

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/historical

Приклад

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cb17e-9e23-3d40-4447-48a651249460/historical' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Відповідь у стані RUNNING

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "RUNNING",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Відповідь у стані COMPLETED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "COMPLETED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Відповідь у стані COMPLETED (AI_PAGE)

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019d7a4d-6ab5-a96d-0f98-43ca434ab621",
    "task_status": "COMPLETED",
    "ppt_biz_id": "9qiLTmT77fA3aVurrMHvRJ",
    "ppt_url": "https://felo.ai/slides/9qiLTmT77fA3aVurrMHvRJ",
    "ai_page_html": "https://felo.ai/ai-page/9qiLTmT77fA3aVurrMHvRJ"
  }
}

Відповідь у стані FAILED / PENDING / EXPIRED / CANCELED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "FAILED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "error_message": "PPT generation failed",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Поля відповіді історії

Поле	Тип	Опис
`task_id`	string	ID завдання
`task_status`	string	Поточний статус завдання
`ppt_biz_id`	string	Бізнес-ID PPT (відповідає `thread_short_id` у бекенді)
`ppt_url`	string	URL-адреса PPT у форматі `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	Присутнє для `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; порожній рядок `""`, якщо нижчий рівень не надає деталей помилки
`ai_page_html`	string	Присутнє, коли завдання виконується в режимі AI_PAGE і нижчий рівень повертає URL-адресу HTML-результату
`live_doc_short_id`	string	Короткий ID LiveDoc. Для `COMPLETED` походить із поля `live_doc_short_id` нижчого рівня; для термінальних статусів помилки повертається, коли доступний
`live_doc_url`	string	URL-адреса LiveDoc, що відповідає `live_doc_short_id`

Експорт PPTX

Після досягнення завданням генерації PPT статусу COMPLETED надішліть асинхронний експорт, використовуючи ppt_business_id із відповіді на створення (або ppt_biz_id із відповіді історії):

curl -X POST 'https://openapi.felo.ai/v2/ppts/YOUR_PPT_BUSINESS_ID/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Опитуйте GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export із тим самим ключем Bearer API кожні 2–5 секунд. Власник API-ключа має бути власником PPT. Обидва endpoint повертають data.status: NOT_STARTED, PROCESSING, COMPLETED або FAILED. Лише COMPLETED містить download_url і expires_at.

Підписана URL-адреса завантаження діє 30 хвилин після видачі. Викличте GET-endpoint знову, щоб отримати свіжу URL-адресу; це не перегенеровує PPTX. POST використовує application/json і приймає {}. Повторний POST під час обробки експорту не запускає ще одне завдання; виклик після завершення перегенеровує PPTX і спричиняє чинну плату за експорт PPT у кредитах. У разі недостатніх кредитів повертається HTTP 402. Можуть застосовуватися обмеження швидкості для конкретного endpoint; у разі HTTP 429 повторіть спробу пізніше. Невдалий експорт можна надіслати повторно.

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "COMPLETED",
    "download_url": "https://example.com/presentation.pptx?signature=...",
    "expires_at": "2026-09-29T10:30:00Z"
  }
}

Коди помилок

Код	Статус HTTP	Опис
`UNAUTHORIZED`	401	API-ключ недійсний або відкликаний
`PPT_TASK_CREATE_FAILED`	502	Не вдалося виконати виклик нижчого рівня для створення завдання
`PPT_TASK_QUERY_FAILED`	502	Не вдалося виконати виклик нижчого рівня для отримання статусу завдання

PPT Task API

Автентифікація

Використання з агентами ШІ

1. Список тем PPT

Endpoint

Параметри запиту

Приклад

Успішна відповідь (200)

Поля відповіді теми

2. Створити завдання PPT

Endpoint

Заголовки запиту

Тіло запиту

Приклад

Створення із завантаженого файлу

Успішна відповідь (200)

3. Отримати статус завдання

Endpoint

Приклад

Успішна відповідь (200)

4. Отримати історію завдання

Endpoint

Приклад

Відповідь у стані RUNNING

Відповідь у стані COMPLETED

Відповідь у стані COMPLETED (AI_PAGE)

Відповідь у стані FAILED / PENDING / EXPIRED / CANCELED

Поля відповіді історії

Експорт PPTX

Рекомендації щодо опитування

Коди помилок