# Generování a export PPT

Vytvořte prezentaci, sledujte její průběh, exportujte PPTX a spravujte její životnost.

Vytvořte prezentaci asynchronně a poté exportujte soubor PPTX. Udržujte kroky generování a exportu oddělené: vytvořená úloha ještě není hotový soubor.

Všechny příklady používají `FELO_API_KEY` z [přehledu](https://openapi.felo.ai/cs/docs/data-api/guides/felo-overview.md). Volání používají **zůstatek platformy**, nikoli Felo Pro credits. Příklady odpovědí jsou ilustrativní; živý obsah a volitelná pole se liší.

## Workflow a identifikátory

1. Vytvořte úlohu generování; uložte `task_id`, `ppt_business_id` a `expires_at`.
2. Pravidelně dotazujte stav generování pomocí `task_id`.
3. Čtěte výsledky generování pomocí `task_id`.
4. Spusťte export PPTX pomocí `ppt_business_id`.
5. Pravidelně dotazujte stav exportu a stáhněte dokončený soubor.
6. Volitelně prezentaci dříve smažte.

V zástupných symbolech tras znamená `{business_id}` vrácené **`ppt_business_id`**, nikoli `task_id`, `resource_id` nebo `livedoc_short_id`. Používejte pro celý workflow stejný účet API. ID v příkladech jsou zástupné.

## 1. Vytvořte prezentaci

`POST /api/v1/data/ppts`

| Pole | Typ | Povinné | Význam |
|---|---|---|---|
| `query` | string | Ano | Pokyny k vygenerování, 1–25 000 znaků |
| `stream_protocol` | string | Ne | Výchozí `message_center_v1`; obvykle ponechte beze změny |
| `ppt_config` | objekt | Ne | Volitelná konfigurace; současná implementace čte `ai_theme_id` |
| `livedoc_short_id` | string | Ne | ID existujícího kontextu, až 100 znaků; musí projít nativními kontrolami vlastnictví API a vypršení |
| `resource_ids` | pole stringů | Ne | Až 100 UUID resource ID; podléhá stejným kontrolám přístupu ke kontextu |

Pro první integraci vynechte pole kontextu a konfigurace. Kontext vytvořený přes `/v2` zde není automaticky způsobilý k opětovnému použití.

```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 vrací identifikátory v kořeni:

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

Mohou být přítomny další identifikátory, jako `resource_id`, `stream_key` a `thread_short_id`. Úspěšná odpověď na vytvoření znamená, že úloha byla přijata, nikoli že generování bylo dokončeno. Požadovaný počet snímků je instrukce; účtování používá skutečný počet vygenerovaných stran.

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

### Čtení událostí generování pomocí SSE

Pokud vytvoření vrátí `stream_key`, připojte se okamžitě pomocí API Key patřícího stejnému účtu. Pokud není vrácen žádný stream key, použijte níže uvedené dotazy na stav a výsledek.

```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 dotazu | Význam |
|---|---|
| `format` | `raw` (výchozí) zachová řetězec `content`; `structured` dekóduje platný JSON na objekt nebo pole |
| `offset` | Volitelná upstream pozice pro obnovení po opětovném připojení; neodvozujte ji z počtu místních událostí |

Přečtěte každou kompletní SSE událost, dekódujte její vnější JSON a poté zpracujte `content`. Událost aplikace `answer` obsahuje text v `data.text`; `finished` signalizuje dokončení generování v proudu. Zpracujte také upstream signály `done`, `[DONE]` a `error`. Pokud se spojení uzavře bez signálu dokončení, dotazujte stav úlohy.

Použijte pravidla parsování a ukázku klienta v [SuperAgent SSE](https://openapi.felo.ai/cs/docs/api-reference/superagent.md#2-zpracov-n-sse-streamu) s URL této sekce `/api/v1/data/conversations/stream/{stream_key}`. Po skončení streamu přečtěte výsledek úlohy; export PPTX zůstává samostatným krokem. Tento koncový bod nepovoluje `stream: true` na `/api/v1/data/chat`.

## 2. Dotazování stavu generování

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

Odpověď má v kořeni řetězec `status`, například `RUNNING` nebo `COMPLETED`. Dotazujte se v omezeném intervalu (například 2–5 sekund) a s termínem. Po dokončení pokračujte k výsledkům; selhání a neočekávané stavy řešte bez předpokladu úspěchu. Deadline pro dotazování úlohu neruší.

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

## 3. Čtení výsledků generování

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

Toto je **POST**, bez nutného těla 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
}
```

Před použitím `history_data` si přečtěte `task_status`. Historický payload se může lišit podle úlohy a může být null. `ai_page_html` a `thread_short_id` jsou volitelné. Tato odpověď není zaručená URL ke stažení PPTX; použijte nejprve export.

## 4. Spusťte export 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}
```

Před exportem musí být generování dokončeno. Opakování POST, zatímco běží stejný export, jej znovu použije. Spuštění dalšího exportu po dokončení vytvoří nový export a může způsobit další poplatek. Pro dotazování a obnovení odkazu ke stažení použijte GET.

## 5. Dotazování exportu a stažení

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

| Stav | Další akce |
|---|---|
| `NOT_STARTED` | Jednou odešlete export |
| `PROCESSING` | Počkejte, poté znovu dotazujte GET |
| `COMPLETED` | Přečtěte `download_url` a stáhněte soubor |
| `FAILED` | Před odesláním nového exportu prozkoumejte chybu a stav úlohy |

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

Ukázková URL je ilustrativní. Použijte skutečnou podepsanou URL z odpovědi. Platí **30 minut**; stav exportu GET může vrátit čerstvý odkaz, zatímco prezentace zůstává dostupná. Uložte soubor během jeho platnosti. Neposílejte svůj Felo API klíč hostiteli pro stahování souboru.

## 6. Smazání prezentace

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

Úspěch vrací **HTTP 204 bez těla**. Neparsuйте to jako JSON. Smazání během probíhajícího generování vrací 409.

## Životnost, vlastnictví a účtování

- Prezentace vyprší **sedm dní po vytvoření**. Dotazy a exporty tuto dobu neprodlužují. `expires_at` prezentace a `expires_at` podepsané URL ke stažení popisují odlišné životnosti.
- K úlohám a prezentacím může přistupovat pouze účet API, který je vytvořil. Chybějící nebo nepřístupný zdroj může vrátit 404; vypršelý nebo smazaný zdroj může vrátit 410, nebo po vyčištění 404.
- Generování je účtováno za vygenerovanou stránku (`ppt.generate`). Při ceně za stránku rezervuje vytvoření cenu deseti stránek, poté zúčtuje skutečný úspěšný výstup a uvolní nevyužitou rezervaci. Váš účet potřebuje dostatečný dostupný zůstatek pro rezervaci, i když prompt požaduje méně stránek.
- Export má samostatnou cenu za požadavek (`ppt.export`). Dotazy na stav, dotazy na výsledky, dotazy na stav exportu a smazání nevytvářejí nový poplatek.
- Po timeoutu dotazujte uloženou úlohu místo vytváření další prezentace. Viz [Účtování a chyby](https://openapi.felo.ai/cs/docs/data-api/guides/felo-billing.md).