# Generowanie i eksport PPT

Utwórz prezentację, sprawdzaj jej postęp, eksportuj PPTX i zarządzaj jej cyklem życia.

Wygeneruj prezentację asynchronicznie, a następnie wyeksportuj plik PPTX. Rozdziel krok generowania i eksportu: utworzone zadanie nie jest jeszcze gotowym plikiem.

Wszystkie przykłady używają `FELO_API_KEY` z [przeglądu](https://openapi.felo.ai/pl/docs/data-api/guides/felo-overview.md). Wywołania korzystają z **salda platformy**, a nie z kredytów Felo Pro. Przykłady odpowiedzi mają charakter poglądowy; rzeczywista treść i opcjonalne pola mogą się różnić.

## Przepływ pracy i identyfikatory

1. Utwórz zadanie generowania; zapisz `task_id`, `ppt_business_id` i `expires_at`.
2. Sprawdzaj status generowania używając `task_id`.
3. Odczytaj wyniki generowania używając `task_id`.
4. Rozpocznij eksport PPTX używając `ppt_business_id`.
5. Sprawdzaj status eksportu i pobierz gotowy plik.
6. Opcjonalnie usuń prezentację wcześniej.

W placeholderach tras `{business_id}` oznacza zwrócone **`ppt_business_id`**, a nie `task_id`, `resource_id` ani `livedoc_short_id`. Użyj tego samego konta API przez cały przepływ pracy. Identyfikatory w przykładach są symbolami zastępczymi.

## 1. Utwórz prezentację

`POST /api/v1/data/ppts`

| Pole | Typ | Wymagane | Znaczenie |
|---|---|---|---|
| `query` | string | Tak | Instrukcje generowania, 1–25 000 znaków |
| `stream_protocol` | string | Nie | Domyślnie `message_center_v1`; zwykle pozostaw bez zmian |
| `ppt_config` | object | Nie | Opcjonalna konfiguracja; bieżąca implementacja odczytuje `ai_theme_id` |
| `livedoc_short_id` | string | Nie | Istniejące ID kontekstu, do 100 znaków; musi przejść natywne sprawdzenia własności API i wygaśnięcia |
| `resource_ids` | tablica stringów | Nie | Do 100 UUID ID zasobów; obowiązują te same kontrole dostępu do kontekstu |

Dla pierwszej integracji pomiń pola kontekstu i konfiguracji. Kontekst utworzony przez `/v2` nie jest automatycznie uprawniony do ponownego użycia tutaj.

```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 zwraca identyfikatory w korzeniu:

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

Dodatkowe identyfikatory, takie jak `resource_id`, `stream_key` i `thread_short_id`, mogą być obecne. Udana odpowiedź create oznacza, że zadanie zostało przyjęte, a nie że generowanie zostało zakończone. Żądana liczba slajdów jest instrukcją; rozliczenie używa rzeczywistej liczby wygenerowanych stron.

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

### Odczyt zdarzeń generowania z SSE

Jeśli tworzenie zwróci `stream_key`, połącz się natychmiast za pomocą API Key należącego do tego samego konta. Jeśli nie zwrócono klucza strumienia, użyj poniższych zapytań o status i wyniki.

```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'
```

| Parametr zapytania | Znaczenie |
|---|---|
| `format` | `raw` (domyślnie) zachowuje ciąg `content`; `structured` dekoduje prawidłowy JSON do obiektu lub tablicy |
| `offset` | Opcjonalna pozycja wznowienia w nadrzędnym źródle przy ponownym połączeniu; nie wyprowadzaj jej z lokalnej liczby zdarzeń |

Odczytaj każde kompletne zdarzenie SSE, zdekoduj jego zewnętrzny JSON, a następnie przetwórz `content`. Zdarzenie aplikacyjne `answer` niesie tekst w `data.text`; `finished` sygnalizuje zakończenie generowania w strumieniu. Obsługuj także sygnały nadrzędne `done`, `[DONE]` i `error`. Jeśli połączenie zamknie się bez sygnału zakończenia, sprawdź status zadania.

Użyj zasad parsowania i przykładu klienta z [SuperAgent SSE](https://openapi.felo.ai/pl/docs/api-reference/superagent.md#2-odbierz-strumie-sse), z tym adresem URL sekcji `/api/v1/data/conversations/stream/{stream_key}`. Odczytaj wynik zadania po zakończeniu strumienia; eksport PPTX pozostaje osobnym krokiem. Ten punkt końcowy nie włącza `stream: true` dla `/api/v1/data/chat`.

## 2. Sprawdzaj status generowania

`GET /api/v1/data/tasks/{task_id}/status`

```bash
curl -sS --request GET "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/status" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

Odpowiedź ma w korzeniu ciąg `status`, na przykład `RUNNING` lub `COMPLETED`. Odpytywanie wykonuj w ograniczonym odstępie czasu (na przykład 2–5 sekund) i z terminem końcowym. Po zakończeniu przejdź do wyników; obsłuż niepowodzenie i nieoczekiwane statusy bez zakładania sukcesu. Termin odpytywania nie anuluje zadania.

```json
{"status":"COMPLETED"}
```

## 3. Odczytaj wyniki generowania

`POST /api/v1/data/tasks/{task_id}/historical`

To jest **POST**, bez wymaganego ciała JSON.

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/historical" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

```json
{
  "task_id":"example-task-id",
  "task_status":"COMPLETED",
  "history_data":{},
  "error_message":null
}
```

Przeczytaj `task_status` przed użyciem `history_data`. Ładunek historii może się różnić w zależności od zadania i może mieć wartość null. `ai_page_html` i `thread_short_id` są opcjonalne. Ta odpowiedź nie jest gwarantowanym adresem pobierania PPTX; użyj najpierw eksportu.

## 4. Rozpocznij eksport PPTX

`POST /api/v1/data/ppts/{business_id}/export`

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

```json
{"status":"PROCESSING","download_url":null,"expires_at":null}
```

Generowanie musi zostać zakończone przed eksportem. Powtarzanie POST, gdy ten sam eksport jest w trakcie, ponownie go wykorzystuje. Rozpoczęcie kolejnego eksportu po zakończeniu tworzy nowy eksport i może skutkować kolejną opłatą. Używaj GET do odpytywania i odświeżania linku pobierania.

## 5. Sprawdzaj eksport i pobierz plik

`GET /api/v1/data/ppts/{business_id}/export`

```bash
curl -sS --request GET "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

| Status | Następna czynność |
|---|---|
| `NOT_STARTED` | Wyślij eksport raz |
| `PROCESSING` | Poczekaj, a następnie ponownie odpytaj GET |
| `COMPLETED` | Odczytaj `download_url` i pobierz plik |
| `FAILED` | Sprawdź błąd i stan zadania przed wysłaniem nowego eksportu |

```json
{
  "status":"COMPLETED",
  "download_url":"https://example.com/presentation.pptx?signature=example",
  "expires_at":"2026-11-06T00:30:00Z"
}
```

Przykładowy URL ma charakter poglądowy. Użyj rzeczywistego podpisanego URL z odpowiedzi. Jest ważny przez **30 minut**; status eksportu GET może zwrócić świeży link, dopóki prezentacja pozostaje dostępna. Zapisz plik w czasie jego ważności. Nie wysyłaj klucza Felo API do hosta pobierania pliku.

## 6. Usuń prezentację

`DELETE /api/v1/data/ppts/{business_id}`

```bash
curl -sS --request DELETE "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID" \
  -H "Authorization: Bearer $FELO_API_KEY"
```

Sukces zwraca **HTTP 204 bez ciała**. Nie parsuj tego jako JSON. Usunięcie w trakcie generowania zwraca 409.

## Czas życia, własność i rozliczenia

- Prezentacje wygasają **siedem dni po utworzeniu**. Zapytania i eksporty nie wydłużają tego okresu. `expires_at` prezentacji i podpisany URL pobierania `expires_at` opisują różne czasy życia.
- Tylko konto API, które utworzyło zasób, może uzyskiwać dostęp do swoich zadań i prezentacji. Brakujący lub niedostępny zasób może zwrócić 404; wygasły lub usunięty zasób może zwrócić 410 albo 404 po sprzątaniu.
- Generowanie jest rozliczane za wygenerowaną stronę (`ppt.generate`). Przy cenach per strona utworzenie rezerwuje cenę dziesięciu stron, a następnie rozlicza rzeczywisty udany wynik i zwalnia niewykorzystaną rezerwację. Twoje konto potrzebuje wystarczającego dostępnego salda na rezerwację, nawet jeśli prompt prosi o mniej stron.
- Eksport ma osobną cenę za żądanie (`ppt.export`). Zapytania o status, zapytania o wyniki, zapytania o status eksportu i usuwanie nie tworzą nowej opłaty.
- Po przekroczeniu limitu czasu sprawdź zapisane zadanie, zamiast tworzyć kolejną prezentację. Zobacz [Rozliczenia i błędy](https://openapi.felo.ai/pl/docs/data-api/guides/felo-billing.md).