# Crea presentazione Felo

POST /api/v1/data/ppts

Genera una presentazione in modo asincrono, poi esporta un file PPTX. Mantieni separati i passaggi di generazione ed esportazione: un task creato non è ancora un file completato.

Tutti gli esempi usano `FELO_API_KEY` dalla [panoramica](https://openapi.felo.ai/it/docs/data-api/guides/felo-overview.md). Le chiamate usano **il saldo della piattaforma**, non i crediti Felo Pro. Gli esempi di risposta sono illustrativi; il contenuto live e i campi opzionali variano.





## 1. Crea la presentazione

`POST /api/v1/data/ppts`

| Campo | Tipo | Obbligatorio | Significato |
|---|---|---|---|
| `query` | string | Sì | Istruzioni di generazione, 1–25.000 caratteri |
| `stream_protocol` | string | No | Predefinito `message_center_v1`; normalmente lascia invariato |
| `ppt_config` | object | No | Configurazione opzionale; l'implementazione attuale legge `ai_theme_id` |
| `livedoc_short_id` | string | No | ID contesto esistente, fino a 100 caratteri; deve superare i controlli nativi di proprietà API e scadenza |
| `resource_ids` | array di stringhe | No | Fino a 100 ID risorsa UUID; soggetto agli stessi controlli di accesso al contesto |

Per una prima integrazione, ometti i campi di contesto e configurazione. Un contesto creato tramite `/v2` non è automaticamente idoneo al riutilizzo qui.

```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 restituisce gli identificatori alla radice:

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

Possono essere presenti anche identificatori aggiuntivi come `resource_id`, `stream_key` e `thread_short_id`. Una risposta di creazione riuscita significa che il task è stato accettato, non che la generazione sia completata. Il numero di slide richiesto è un'istruzione; la fatturazione usa il numero effettivo di pagine generate.

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

### Leggi gli eventi di generazione con SSE

Se la creazione restituisce un `stream_key`, connettiti immediatamente con una API Key appartenente allo stesso account. Se non viene restituito alcun stream key, usa le query di stato e di risultato qui sotto.

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

| Parametro di query | Significato |
|---|---|
| `format` | `raw` (predefinito) preserva la stringa `content`; `structured` decodifica JSON valido in un oggetto o array |
| `offset` | Posizione di ripresa upstream opzionale per la riconnessione; non inferirla dal conteggio degli eventi locali |

Leggi ogni evento SSE completo, decodifica il suo JSON esterno, poi elabora `content`. Un evento applicativo `answer` contiene testo in `data.text`; `finished` segnala il completamento della generazione nello stream. Gestisci anche i segnali upstream `done`, `[DONE]` ed `error`. Se la connessione si chiude senza un segnale di completamento, interroga lo stato del task.

Usa le regole di parsing e l'esempio client in [SuperAgent SSE](https://openapi.felo.ai/it/docs/api-reference/superagent.md#2-consuma-lo-stream-sse), con l'URL `/api/v1/data/conversations/stream/{stream_key}` di questa sezione. Leggi il risultato del task dopo la fine dello stream; l'esportazione PPTX resta un passaggio separato. Questo endpoint non abilita `stream: true` su `/api/v1/data/chat`.



## Durata, proprietà e fatturazione

- Le presentazioni scadono **sette giorni dopo la creazione**. Le query e le esportazioni non estendono questo periodo. L'`expires_at` della presentazione e l'`expires_at` dell'URL di download firmato descrivono durate diverse.
- Solo l'account API che ha creato la presentazione può accedere ai propri task e presentazioni. Una risorsa mancante o non accessibile può restituire 404; una risorsa scaduta o eliminata può restituire 410, oppure 404 dopo la pulizia.
- La generazione è fatturata per pagina generata (`ppt.generate`). Con la tariffazione per pagina, la creazione riserva il prezzo di dieci pagine, poi effettua il saldo dell'output effettivamente riuscito e libera la riserva inutilizzata. Il tuo account deve avere saldo disponibile sufficiente per la riserva anche se il prompt richiede meno pagine.
- L'esportazione ha un prezzo separato per richiesta (`ppt.export`). Le query di stato, le query di risultato, le query di stato esportazione e l'eliminazione non creano nuovi addebiti.
- Dopo un timeout, interroga il task salvato invece di creare un'altra presentazione. Vedi [Fatturazione ed errori](https://openapi.felo.ai/it/docs/data-api/guides/felo-billing.md).