Felo APIs

PPT Task API

Twórz zadania generowania PPT, przeglądaj motywy i odpytuj o udostępnione endpointy zadań.

POST/v2/ppts

Uwierzytelnianie

Bearer API key

Typ zawartości

application/json

Uwagi o limitach

Mogą obowiązywać limity dla poszczególnych endpointów.

LiveDoc API Landing Page Task API

API zadań PPT zapewnia asynchroniczne możliwości generowania prezentacji PPT. Możesz utworzyć zadanie, a następnie odpytować jego stan za pomocą task_id. Możesz też przeglądać dostępne tematy PPT i stosować je przy tworzeniu zadań.

To jest API asynchroniczne. Wspólny wzorzec wysyłania, odpytywania i pobierania wyniku znajdziesz w Zadaniach asynchronicznych.

Uwierzytelnianie

Wszystkie żądania wymagają klucza API w nagłówku Authorization:

Authorization: Bearer YOUR_API_KEY

Użycie z agentami AI

Aby tworzyć slajdy z poziomu agenta, zainstaluj kompletny pakiet felo-ai, a nie stały podzbiór Skills. Jego instalator dynamicznie wykrywa każdy katalog pakietu zawierający SKILL.md, w tym Skill PPT i przyszłe dodatki. Zainstaluj wszystkie wykryte Skills w natywnym katalogu swojego agenta: Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills lub Hermes Agent ~/.hermes/skills. Postępuj według podręcznika konfiguracji agenta AI, aby poznać konfigurację klucza API i weryfikację dla poszczególnych platform.

1. Wyświetlanie tematów PPT

Odpytuj dostępne tematy PPT z paginacją, wyszukiwaniem według słów kluczowych oraz filtrowaniem według języka i typu.

Endpoint

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

Parametry zapytania

Parametr	Typ	Wymagany	Opis
`lang`	string	Nie	Kod języka zlokalizowanej treści (np. `en`, `zh-Hans`). Domyślnie: `en`
`type`	string	Nie	Filtruj według typu tematu (np. `default`, `custom`)
`keyword`	string	Nie	Słowo kluczowe wyszukiwania, dopasowuje tytuły tematów
`page`	integer	Nie	Numer strony, zaczynając od 1. Domyślnie: `1`
`size`	integer	Nie	Rozmiar strony, maks. 100. Domyślnie: `20`

Przykład

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'

Odpowiedź sukcesu (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"
      }
    ]
  }
}

Pola odpowiedzi tematu

Pole	Typ	Opis
`total`	integer	Łączna liczba tematów pasujących do filtra
`page`	integer	Bieżący numer strony
`size`	integer	Rozmiar strony
`items`	array	Lista obiektów tematów
`items[].id`	string	Identyfikator tematu; użyj go jako `ai_theme_id` przy tworzeniu PPT
`items[].title`	string	Tytuł tematu (zlokalizowany)
`items[].subtitle`	string	Podtytuł tematu (zlokalizowany)
`items[].description`	string	Opis tematu (zlokalizowany)

2. Tworzenie zadania PPT

Endpoint

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

Nagłówki żądania

Nagłówek	Wymagany	Opis
`Authorization`	Tak	Twój klucz API w formacie `Bearer YOUR_API_KEY`
`Content-Type`	Tak	`application/json` lub `multipart/form-data`

Treść żądania

Parametr	Typ	Wymagany	Opis
`query`	string	Tak	Prompt żądania generowania PPT
`livedoc_short_id`	string	Nie	Krótki identyfikator istniejącego LiveDoc do powiązania z sesją PPT. Jeśli go pominiesz, nowy LiveDoc zostanie utworzony automatycznie.
`resource_ids`	array of strings	Nie	Lista identyfikatorów zasobów LiveDoc do użycia jako kontekst generowania PPT
`ppt_config`	object	Nie	Opcje konfiguracji PPT
`ppt_config.ai_theme_id`	string	Nie	Identyfikator tematu z endpointu Wyświetlanie tematów PPT

Przykład

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"
    }
  }'

Tworzenie z przesłanego pliku

Użyj multipart/form-data, aby przesłać jeden plik i utworzyć zadanie PPT w jednym żądaniu. Platforma najpierw przesyła plik jako zasób LiveDoc, a następnie przekazuje jego identyfikator zasobu do zadania PPT.

Część	Typ	Wymagany	Opis
`query`	string	Tak	Prompt żądania generowania PPT
`file`	file	Tak	Plik źródłowy używany jako kontekst PPT
`stream_protocol`	string	Nie	Protokół przesyłania strumieniowego; domyślnie `message_center_v1`
`livedoc_short_id`	string	Nie	Istniejący LiveDoc, do którego ma trafić plik. Jeśli go pominiesz, zostanie utworzony nowy LiveDoc.
`ppt_config`	JSON	Nie	Konfiguracja PPT o tej samej strukturze co treść żądania JSON. Wyślij tę część jako `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]'

Odpowiedź używa tego samego schematu co żądanie JSON. Zwrócony livedoc_short_id identyfikuje LiveDoc zawierający przesłany zasób.

Odpowiedź sukcesu (200)

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

3. Sprawdzanie stanu zadania

Endpoint

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

Przykład

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'

Odpowiedź sukcesu (200)

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

4. Sprawdzanie informacji historycznych zadania

Endpoint

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

Przykład

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'

Odpowiedź 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"
  }
}

Odpowiedź 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"
  }
}

Odpowiedź 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"
  }
}

Odpowiedź 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"
  }
}

Pola odpowiedzi historycznej

Pole	Typ	Opis
`task_id`	string	Identyfikator zadania
`task_status`	string	Bieżący stan zadania
`ppt_biz_id`	string	Biznesowy identyfikator PPT (mapowany z backendowego `thread_short_id`)
`ppt_url`	string	Adres URL PPT, format: `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	Obecny dla `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; pusty ciąg `""`, gdy usługa podrzędna nie podaje szczegółów błędu
`ai_page_html`	string	Obecny, gdy zadanie działa w trybie AI_PAGE, a podrzędna odpowiedź historyczna zwraca adres URL wyniku HTML
`live_doc_short_id`	string	Krótki identyfikator LiveDoc. Dla `COMPLETED` pochodzi z podrzędnego `live_doc_short_id`; dla terminalnych stanów niepowodzenia jest zwracany, gdy jest dostępny
`live_doc_url`	string	Adres URL LiveDoc odpowiadający `live_doc_short_id`

Eksport PPTX

Gdy zadanie generowania PPT osiągnie stan COMPLETED, wyślij asynchroniczny eksport, używając ppt_business_id z odpowiedzi na utworzenie (lub ppt_biz_id z odpowiedzi historycznej):

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 '{}'

Odpytuj GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export z tym samym kluczem API Bearer co 2–5 sekund. Właściciel klucza API musi być właścicielem PPT. Oba endpointy zwracają data.status: NOT_STARTED, PROCESSING, COMPLETED lub FAILED. Tylko COMPLETED zawiera download_url i expires_at.

Podpisany adres URL pobierania wygasa 30 minut po wydaniu. Wywołaj ponownie endpoint GET, aby uzyskać nowy adres URL; nie generuje to ponownie pliku PPTX. POST używa application/json i akceptuje {}. Powtórzenie POST podczas trwającego eksportu nie uruchamia kolejnego zadania; wywołanie po ukończeniu ponownie generuje PPTX i wiąże się z istniejącą opłatą kredytową za eksport PPT. Niewystarczające kredyty zwracają HTTP 402. Mogą obowiązywać limity szybkości specyficzne dla endpointu; przy HTTP 429 ponów później. Nieudany eksport można wysłać ponownie.

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

Zalecenia dotyczące odpytywania

Użyj task_id z odpowiedzi na utworzenie i odpytuj stan co 2–5 sekund, aż stan stanie się terminalny.

Typowe przykłady stanów:

RUNNING: zadanie jest wciąż przetwarzane
COMPLETED: zadanie ukończone pomyślnie
FAILED / PENDING / EXPIRED / CANCELED: zadanie osiągnęło stan terminalny z error_message; live_doc_url jest też zwracany, gdy jest dostępny

Wraz z rozwojem backendu mogą pojawiać się nieznane wartości stanu; traktuj je jako nieterminalne, chyba że dokumentacja mówi inaczej.

Kody błędów

Kod	Status HTTP	Opis
`UNAUTHORIZED`	401	Klucz API jest nieprawidłowy lub unieważniony
`PPT_TASK_CREATE_FAILED`	502	Niepowodzenie podrzędnego wywołania tworzenia zadania
`PPT_TASK_QUERY_FAILED`	502	Niepowodzenie podrzędnego wywołania sprawdzania stanu zadania