Felo APIs

PPT Task API

Crea attività di generazione PPT, elenca i temi e interroga gli endpoint delle attività condivise.

POST/v2/ppts

Autenticazione

Bearer API key

Tipo di contenuto

application/json

Note sui limiti

Possono applicarsi limiti specifici dell'endpoint.

LiveDoc API Landing Page Task API

La PPT Task API offre capacità asincrone di generazione di PPT. Puoi creare un'attività e poi interrogare lo stato tramite task_id. Puoi anche sfogliare i temi PPT disponibili e applicarli quando crei le attività.

Questa è un'API asincrona. Per lo schema condiviso di invio, polling e recupero, vedi Attività asincrone.

Autenticazione

Tutte le richieste richiedono una chiave API nell'header Authorization:

Authorization: Bearer YOUR_API_KEY

Uso con agenti IA

Per creare slide da un agente, installa il pacchetto completo felo-ai invece di un sottoinsieme fisso di Skill. Il suo installer individua dinamicamente ogni directory del pacchetto che contiene SKILL.md, compresa la Skill PPT e le aggiunte future. Installa tutte le Skill trovate nella directory nativa del tuo agente: Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills o Hermes Agent ~/.hermes/skills. Segui la guida alla configurazione manuale degli agenti IA per la configurazione della chiave API e la verifica su ogni piattaforma.

1. Elencare i temi PPT

Interroga i temi PPT disponibili con paginazione, ricerca per parola chiave e filtro per lingua e tipo.

Endpoint

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

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`lang`	string	No	Codice lingua per i contenuti localizzati (ad es. `en`, `zh-Hans`). Predefinito: `en`
`type`	string	No	Filtra per tipo di tema (ad es. `default`, `custom`)
`keyword`	string	No	Parola chiave di ricerca, cerca nei titoli dei temi
`page`	integer	No	Numero di pagina, a partire da 1. Predefinito: `1`
`size`	integer	No	Dimensione della pagina, massimo 100. Predefinito: `20`

Esempio

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'

Risposta di successo (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"
      }
    ]
  }
}

Campi della risposta dei temi

Campo	Tipo	Descrizione
`total`	integer	Numero totale di temi corrispondenti al filtro
`page`	integer	Numero di pagina corrente
`size`	integer	Dimensione della pagina
`items`	array	Elenco di oggetti tema
`items[].id`	string	ID del tema, da usare come `ai_theme_id` quando crei il PPT
`items[].title`	string	Titolo del tema (localizzato)
`items[].subtitle`	string	Sottotitolo del tema (localizzato)
`items[].description`	string	Descrizione del tema (localizzata)

2. Creare un'attività PPT

Endpoint

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

Header della richiesta

Header	Obbligatorio	Descrizione
`Authorization`	Sì	La tua chiave API nel formato `Bearer YOUR_API_KEY`
`Content-Type`	Sì	`application/json` o `multipart/form-data`

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Prompt di richiesta per la generazione del PPT
`livedoc_short_id`	string	No	ID breve di un LiveDoc esistente da associare alla sessione PPT. Se omesso, viene creato automaticamente un nuovo LiveDoc.
`resource_ids`	array di stringhe	No	Elenco di ID delle risorse LiveDoc da usare come contesto per la generazione del PPT
`ppt_config`	object	No	Opzioni di configurazione del PPT
`ppt_config.ai_theme_id`	string	No	ID del tema dall'endpoint Elencare i temi PPT

Esempio

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

Creare da un file caricato

Usa multipart/form-data per caricare un file e creare un'attività PPT in un'unica richiesta. La piattaforma carica prima il file come risorsa LiveDoc, poi passa il suo ID risorsa all'attività PPT.

Parte	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Prompt di richiesta per la generazione del PPT
`file`	file	Sì	File di origine usato come contesto per il PPT
`stream_protocol`	string	No	Protocollo di streaming; valore predefinito `message_center_v1`
`livedoc_short_id`	string	No	LiveDoc esistente che riceve il file. Se omesso, viene creato un nuovo LiveDoc.
`ppt_config`	JSON	No	Configurazione PPT con la stessa struttura del corpo della richiesta JSON. Invia questa parte come `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]'

La risposta usa lo stesso schema della richiesta JSON. Il livedoc_short_id restituito identifica il LiveDoc che contiene la risorsa caricata.

Risposta di successo (200)

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

3. Consultare lo stato dell'attività

Endpoint

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

Esempio

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'

Risposta di successo (200)

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

4. Consultare le informazioni storiche dell'attività

Endpoint

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

Esempio

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'

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

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

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

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

Campi della risposta storica

Campo	Tipo	Descrizione
`task_id`	string	ID dell'attività
`task_status`	string	Stato attuale dell'attività
`ppt_biz_id`	string	ID business del PPT (mappato da `thread_short_id` del backend)
`ppt_url`	string	URL del PPT, formato: `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	Presente per `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; stringa vuota `""` quando il downstream non fornisce dettagli sull'errore
`ai_page_html`	string	Presente quando l'attività viene eseguita in modalità AI_PAGE e il risultato storico del downstream restituisce un URL HTML
`live_doc_short_id`	string	ID breve del LiveDoc. Per `COMPLETED` proviene da `live_doc_short_id` del downstream; per gli stati di errore terminali viene restituito quando disponibile
`live_doc_url`	string	URL del LiveDoc corrispondente a `live_doc_short_id`

Esportare il PPTX

Dopo che l'attività di generazione PPT raggiunge COMPLETED, invia un'esportazione asincrona usando ppt_business_id dalla risposta di creazione (oppure ppt_biz_id dalla risposta storica):

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

Interroga GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export con la stessa chiave API Bearer ogni 2–5 secondi. Il proprietario della chiave API deve possedere il PPT. Entrambi gli endpoint restituiscono data.status: NOT_STARTED, PROCESSING, COMPLETED o FAILED. Solo COMPLETED include download_url e expires_at.

L'URL di download firmato scade 30 minuti dopo l'emissione. Chiama di nuovo l'endpoint GET per ottenere un URL aggiornato; questo non rigenera il PPTX. POST usa application/json e accetta {}. Ripetere POST mentre un'esportazione è in corso non avvia un altro job; chiamarlo dopo il completamento rigenera il PPTX e comporta l'addebito esistente per l'esportazione PPT. Crediti insufficienti restituiscono HTTP 402. Possono applicarsi rate limit specifici dell'endpoint; riprova più tardi in caso di HTTP 429. Un'esportazione non riuscita può essere inviata di nuovo.

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

Consigli sul polling

Usa il task_id dalla risposta di creazione e interroga lo stato ogni 2-5 secondi finché non diventa uno stato terminale.

Esempi di stati comuni:

RUNNING: l'attività è ancora in elaborazione
COMPLETED: l'attività è stata completata con successo
FAILED / PENDING / EXPIRED / CANCELED: l'attività ha raggiunto uno stato terminale con error_message; anche live_doc_url viene restituito quando disponibile

Con l'evoluzione del backend possono comparire valori di stato sconosciuti; trattali come non terminali, salvo diversa indicazione nella documentazione.

Codici di errore

Codice	Stato HTTP	Descrizione
`UNAUTHORIZED`	401	La chiave API non è valida o è revocata
`PPT_TASK_CREATE_FAILED`	502	Chiamata downstream di creazione dell'attività non riuscita
`PPT_TASK_QUERY_FAILED`	502	Chiamata downstream di interrogazione dello stato non riuscita