# Génération et export PPT

Créer une présentation, interroger sa progression, exporter un fichier PPTX et gérer sa durée de vie.

Générez une présentation de façon asynchrone, puis exportez un fichier PPTX. Gardez les étapes de génération et d'export séparées : une tâche créée n'est pas encore un fichier terminé.

Tous les exemples utilisent `FELO_API_KEY` depuis l'[aperçu](https://openapi.felo.ai/fr/docs/data-api/guides/felo-overview.md). Les appels utilisent **le solde de plateforme**, et non les crédits Felo Pro. Les exemples de réponse sont illustratifs ; le contenu réel et les champs facultatifs varient.

## Workflow et identifiants

1. Créez une tâche de génération ; enregistrez `task_id`, `ppt_business_id` et `expires_at`.
2. Interrogez le statut de génération à l'aide de `task_id`.
3. Lisez les résultats de génération à l'aide de `task_id`.
4. Lancez l'export PPTX à l'aide de `ppt_business_id`.
5. Interrogez le statut d'export et téléchargez le fichier terminé.
6. Supprimez éventuellement la présentation plus tôt.

Dans les espaces réservés de route, `{business_id}` signifie le **`ppt_business_id`** renvoyé, et non `task_id`, `resource_id` ou `livedoc_short_id`. Utilisez le même compte API pendant tout le workflow. Les IDs dans les exemples sont des espaces réservés.

## 1. Créer la présentation

`POST /api/v1/data/ppts`

| Champ | Type | Requis | Signification |
|---|---|---|---|
| `query` | string | Oui | Instructions de génération, 1–25 000 caractères |
| `stream_protocol` | string | Non | `message_center_v1` par défaut ; laissez généralement inchangé |
| `ppt_config` | objet | Non | Configuration facultative ; l'implémentation actuelle lit `ai_theme_id` |
| `livedoc_short_id` | string | Non | ID de contexte existant, jusqu'à 100 caractères ; doit passer les contrôles natifs d'API de propriété et d'expiration |
| `resource_ids` | tableau de strings | Non | Jusqu'à 100 IDs de ressources UUID ; soumis aux mêmes contrôles d'accès au contexte |

Pour une première intégration, omettez les champs de contexte et de configuration. Un contexte créé via `/v2` n'est pas automatiquement éligible à la réutilisation ici.

```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 renvoie les identifiants à la racine :

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

Des identifiants supplémentaires tels que `resource_id`, `stream_key` et `thread_short_id` peuvent être présents. Une réponse de création réussie signifie que la tâche a été acceptée, pas que la génération est terminée. Le nombre de diapositives demandé est une instruction ; la facturation utilise le nombre réel de pages générées.

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

### Lire les événements de génération avec SSE

Si la création renvoie une `stream_key`, connectez-vous immédiatement avec une clé API appartenant au même compte. Si aucune clé de flux n'est renvoyée, utilisez les requêtes de statut et de résultat ci-dessous.

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

| Paramètre de requête | Signification |
|---|---|
| `format` | `raw` (par défaut) préserve la chaîne `content` ; `structured` décode le JSON valide en objet ou tableau |
| `offset` | Position de reprise amont facultative pour la reconnexion ; ne l'inférez pas de votre nombre local d'événements |

Lisez chaque événement SSE complet, décodez son JSON externe, puis traitez `content`. Un événement d'application `answer` contient du texte dans `data.text` ; `finished` signale l'achèvement de la génération dans le flux. Gérez aussi les signaux amont `done`, `[DONE]` et `error`. Si la connexion se ferme sans signal d'achèvement, interrogez le statut de la tâche.

Utilisez les règles d'analyse et l'exemple client de [SuperAgent SSE](https://openapi.felo.ai/fr/docs/api-reference/superagent.md#2-consommer-le-flux-sse), avec l'URL `/api/v1/data/conversations/stream/{stream_key}` de cette section. Lisez le résultat de la tâche après la fin du flux ; l'export PPTX reste une étape séparée. Ce point de terminaison n'active pas `stream: true` sur `/api/v1/data/chat`.

## 2. Interroger le statut de génération

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

La réponse comporte une chaîne `status` à la racine, par exemple `RUNNING` ou `COMPLETED`. Interrogez à intervalles bornés (par exemple 2 à 5 secondes) et avec une échéance. Passez aux résultats après l'achèvement ; gérez l'échec et les statuts inattendus sans supposer le succès. Une échéance d'interrogation ne cancel pas la tâche.

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

## 3. Lire les résultats de génération

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

Il s'agit d'un **POST**, sans corps JSON requis.

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

Lisez `task_status` avant d'utiliser `history_data`. La charge utile historique peut varier selon la tâche et peut être nulle. `ai_page_html` et `thread_short_id` sont facultatifs. Cette réponse n'est pas une URL de téléchargement PPTX garantie ; utilisez ensuite l'export.

## 4. Démarrer l'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}
```

La génération doit être terminée avant l'export. Répéter un POST pendant que le même export est en cours le réutilise. Démarrer un autre export après l'achèvement en crée un nouveau et peut entraîner un autre frais. Utilisez GET pour l'interrogation et l'actualisation du lien de téléchargement.

## 5. Interroger l'export et télécharger

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

| Statut | Action suivante |
|---|---|
| `NOT_STARTED` | Soumettez l'export une fois |
| `PROCESSING` | Attendez, puis interrogez GET à nouveau |
| `COMPLETED` | Lisez `download_url` et téléchargez le fichier |
| `FAILED` | Inspectez l'erreur et l'état de la tâche avant de soumettre un nouvel export |

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

L'URL d'exemple est illustrative. Utilisez l'URL signée réelle fournie par la réponse. Elle est valable pendant **30 minutes** ; le statut d'export GET peut renvoyer un nouveau lien tant que la présentation reste disponible. Enregistrez le fichier pendant sa durée de vie. N'envoyez pas votre clé API Felo à l'hôte de téléchargement du fichier.

## 6. Supprimer la présentation

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

Le succès renvoie **HTTP 204 sans corps**. Ne l'analysez pas comme du JSON. La suppression pendant qu'une génération est en cours renvoie 409.

## Durée de vie, propriété et facturation

- Les présentations expirent **sept jours après leur création**. Les requêtes et les exports ne prolongent pas cette période. Le `expires_at` de la présentation et le `expires_at` de l'URL signée de téléchargement décrivent des durées de vie différentes.
- Seul le compte API créateur peut accéder à ses tâches et présentations. Une ressource manquante ou inaccessible peut renvoyer 404 ; une ressource expirée ou supprimée peut renvoyer 410, ou 404 après nettoyage.
- La génération est facturée par page générée (`ppt.generate`). Avec la tarification par page, la création réserve le prix de dix pages, puis régularise la production réussie réelle et libère la réservation inutilisée. Votre compte doit disposer d'un solde disponible suffisant pour la réservation, même si l'invite demande moins de pages.
- L'export a un prix de requête séparé (`ppt.export`). Les requêtes de statut, de résultat, de statut d'export et la suppression ne créent aucun nouveau frais.
- Après un délai d'attente, interrogez la tâche enregistrée plutôt que de créer une autre présentation. Consultez [Facturation et erreurs](https://openapi.felo.ai/fr/docs/data-api/guides/felo-billing.md).