Felo APIs

PPT Task API

Créez des tâches de génération PPT, listez les thèmes et interrogez les endpoints de tâches partagés.

POST/v2/ppts

Authentification

Bearer API key

Type de contenu

application/json

Notes sur les limites

Des limites propres à l'endpoint peuvent s'appliquer.

LiveDoc API Landing Page Task API

L'API PPT Task fournit des capacités asynchrones de génération de PPT. Vous pouvez créer une tâche, puis interroger l'état de la tâche par task_id. Vous pouvez aussi parcourir les thèmes PPT disponibles et les appliquer lors de la création de tâches.

Il s'agit d'une API asynchrone. Pour le schéma commun de soumission, d'interrogation et de récupération, consultez Tâches asynchrones.

Authentification

Toutes les requêtes nécessitent une clé API dans l'en-tête Authorization :

Authorization: Bearer YOUR_API_KEY

Utilisation avec des agents IA

Pour créer des présentations depuis un agent, installez le paquet complet felo-ai plutôt qu'un sous-ensemble figé de Skills. Son installateur découvre dynamiquement chaque répertoire de paquet contenant SKILL.md, y compris le Skill PPT et les ajouts futurs. Installez tous les Skills découverts dans le répertoire natif de votre agent : Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills ou Hermes Agent ~/.hermes/skills. Suivez le guide d'installation manuelle des agents IA pour la configuration des clés API et la vérification propres à chaque plateforme.

1. Lister les thèmes PPT

Interrogez les thèmes PPT disponibles avec pagination, recherche par mot-clé et filtrage par langue et par type.

Endpoint

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

Paramètres de requête

Paramètre	Type	Requis	Description
`lang`	string	Non	Code de langue pour le contenu localisé (par exemple `en`, `zh-Hans`). Par défaut : `en`
`type`	string	Non	Filtre par type de thème (par exemple `default`, `custom`)
`keyword`	string	Non	Mot-clé de recherche, correspond aux titres des thèmes
`page`	integer	Non	Numéro de page, à partir de 1. Par défaut : `1`
`size`	integer	Non	Taille de page, 100 maximum. Par défaut : `20`

Exemple

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'

Réponse de succès (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"
      }
    ]
  }
}

Champs de réponse des thèmes

Champ	Type	Description
`total`	integer	Nombre total de thèmes correspondant au filtre
`page`	integer	Numéro de page actuel
`size`	integer	Taille de page
`items`	array	Liste d'objets thème
`items[].id`	string	ID du thème, à utiliser comme `ai_theme_id` lors de la création d'un PPT
`items[].title`	string	Titre du thème (localisé)
`items[].subtitle`	string	Sous-titre du thème (localisé)
`items[].description`	string	Description du thème (localisée)

2. Créer une tâche PPT

Endpoint

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

En-têtes de requête

En-tête	Requis	Description
`Authorization`	Oui	Votre clé API au format `Bearer YOUR_API_KEY`
`Content-Type`	Oui	`application/json` ou `multipart/form-data`

Corps de requête

Paramètre	Type	Requis	Description
`query`	string	Oui	Prompt de génération du PPT
`livedoc_short_id`	string	Non	ID court d'un LiveDoc existant à associer à la session PPT. S'il est omis, un nouveau LiveDoc est créé automatiquement.
`resource_ids`	array of strings	Non	Liste d'ID de ressources LiveDoc à utiliser comme contexte pour la génération du PPT
`ppt_config`	object	Non	Options de configuration du PPT
`ppt_config.ai_theme_id`	string	Non	ID de thème issu de l'endpoint Lister les thèmes PPT

Exemple

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

Créer à partir d'un fichier importé

Utilisez multipart/form-data pour importer un fichier et créer une tâche PPT en une seule requête. La plateforme importe d'abord le fichier comme ressource LiveDoc, puis transmet son ID de ressource à la tâche PPT.

Partie	Type	Requis	Description
`query`	string	Oui	Prompt de génération du PPT
`file`	file	Oui	Fichier source utilisé comme contexte du PPT
`stream_protocol`	string	Non	Protocole de streaming ; par défaut `message_center_v1`
`livedoc_short_id`	string	Non	LiveDoc existant devant recevoir le fichier. Un nouveau LiveDoc est créé s'il est omis.
`ppt_config`	JSON	Non	Configuration PPT avec la même structure que le corps de requête JSON. Envoyez cette partie en `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 réponse utilise le même schéma que la requête JSON. Le livedoc_short_id renvoyé identifie le LiveDoc contenant la ressource importée.

Réponse de succès (200)

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

3. Interroger l'état d'une tâche

Endpoint

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

Exemple

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'

Réponse de succès (200)

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

4. Interroger l'historique d'une tâche

Endpoint

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

Exemple

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'

Réponse 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"
  }
}

Réponse 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"
  }
}

Réponse 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"
  }
}

Réponse 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"
  }
}

Champs de réponse historique

Champ	Type	Description
`task_id`	string	ID de tâche
`task_status`	string	État actuel de la tâche
`ppt_biz_id`	string	ID métier du PPT (mappé depuis `thread_short_id` du backend)
`ppt_url`	string	URL du PPT, format : `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	Présent pour `FAILED` / `PENDING` / `EXPIRED` / `CANCELED` ; chaîne vide `""` lorsque l'aval ne fournit pas de détails d'erreur
`ai_page_html`	string	Présent lorsque la tâche s'exécute en mode AI_PAGE et que l'historique aval renvoie une URL de résultat HTML
`live_doc_short_id`	string	ID court du LiveDoc. Pour `COMPLETED`, il provient du `live_doc_short_id` aval ; pour les statuts d'échec terminaux, il est renvoyé lorsqu'il est disponible
`live_doc_url`	string	URL LiveDoc correspondant à `live_doc_short_id`

Exporter en PPTX

Une fois la tâche de génération PPT parvenue à COMPLETED, soumettez un export asynchrone en utilisant ppt_business_id de la réponse de création (ou ppt_biz_id de la réponse historique) :

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

Interrogez GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export avec la même clé API Bearer toutes les 2 à 5 secondes. Le propriétaire de la clé API doit posséder le PPT. Les deux endpoints renvoient data.status : NOT_STARTED, PROCESSING, COMPLETED ou FAILED. Seul COMPLETED inclut download_url et expires_at.

L'URL de téléchargement signée expire 30 minutes après son émission. Appelez à nouveau l'endpoint GET pour obtenir une URL fraîche ; cela ne régénère pas le PPTX. POST utilise application/json et accepte {}. Répéter le POST pendant qu'un export est en cours ne lance pas un autre job ; l'appeler après la fin régénère le PPTX et entraîne les frais de crédits d'export PPT existants. Des crédits insuffisants renvoient HTTP 402. Des limites de débit propres à l'endpoint peuvent s'appliquer ; réessayez plus tard en cas de HTTP 429. Un export échoué peut être soumis à nouveau.

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

Recommandation d'interrogation

Utilisez le task_id de la réponse de création et interrogez l'état toutes les 2 à 5 secondes jusqu'à ce qu'il atteigne un état terminal.

Exemples de statuts courants :

RUNNING : la tâche est toujours en cours de traitement
COMPLETED : la tâche s'est terminée avec succès
FAILED / PENDING / EXPIRED / CANCELED : la tâche a atteint un statut terminal avec error_message ; live_doc_url est aussi renvoyé lorsqu'il est disponible

Des valeurs de statut inconnues peuvent apparaître à mesure que le backend évolue ; traitez-les comme non terminales sauf indication contraire.

Codes d'erreur

Code	Statut HTTP	Description
`UNAUTHORIZED`	401	La clé API est invalide ou révoquée
`PPT_TASK_CREATE_FAILED`	502	L'appel aval de création de tâche a échoué
`PPT_TASK_QUERY_FAILED`	502	L'appel aval d'interrogation de l'état de la tâche a échoué