Generazione ed esportazione PPT

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. 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.

Workflow e identificatori

1. Crea un task di generazione; salva task_id, ppt_business_id e expires_at.
2. Interroga lo stato della generazione usando task_id.
3. Leggi i risultati della generazione usando task_id.
4. Avvia l'esportazione PPTX usando ppt_business_id.
5. Interroga lo stato dell'esportazione e scarica il file completato.
6. Facoltativamente elimina la presentazione in anticipo.

Nei segnaposto di route, {business_id} significa il `ppt_business_id` restituito, non task_id, resource_id o livedoc_short_id. Usa lo stesso account API per l'intero workflow. Gli ID negli esempi sono segnaposto.

1. Crea la presentazione

POST /api/v1/data/ppts

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

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:

{
  "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.

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.

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'

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, 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.

2. Interroga lo stato della generazione

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

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

La risposta ha una stringa status alla radice, ad esempio RUNNING o COMPLETED. Interroga con un intervallo limitato (ad esempio 2–5 secondi) e una scadenza. Continua ai risultati dopo il completamento; gestisci fallimenti e stati inattesi senza presumere il successo. Una scadenza di polling non annulla il task.

{"status":"COMPLETED"}

3. Leggi i risultati della generazione

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

Questo è un POST, senza alcun body JSON richiesto.

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

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

Leggi task_status prima di usare history_data. Il payload della cronologia può variare in base al task e può essere null. ai_page_html e thread_short_id sono opzionali. Questa risposta non è un URL di download PPTX garantito; usa l'esportazione successivamente.

4. Avvia l'esportazione PPTX

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

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

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

La generazione deve essere completata prima di esportare. Ripetere POST mentre la stessa esportazione è in esecuzione la riutilizza. Avviare un'altra esportazione dopo il completamento crea una nuova esportazione e può comportare un altro addebito. Usa GET per il polling e l'aggiornamento del link di download.

5. Interroga l'esportazione e scarica

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

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

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

L'URL di esempio è illustrativo. Usa l'URL firmato effettivo restituito dalla risposta. È valido per 30 minuti; lo stato di esportazione GET può restituire un link تازه mentre la presentazione rimane disponibile. Salva il file entro la sua durata di validità. Non inviare la tua chiave API Felo all'host di download del file.

6. Elimina la presentazione

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

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

Il successo restituisce HTTP 204 senza body. Non analizzarlo come JSON. L'eliminazione mentre la generazione è in corso restituisce 409.

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.