# Generación y exportación de PPT

Crea una presentación, consulta su progreso, exporta un PPTX y gestiona su ciclo de vida.

Genera una presentación de forma asíncrona y luego exporta un archivo PPTX. Mantén separadas las fases de generación y exportación: una tarea creada todavía no es un archivo terminado.

Todos los ejemplos usan `FELO_API_KEY` de la [vista general](https://openapi.felo.ai/es/docs/data-api/guides/felo-overview.md). Las llamadas usan **saldo de la plataforma**, no créditos Felo Pro. Los ejemplos de respuesta son ilustrativos; el contenido en vivo y los campos opcionales varían.

## Flujo de trabajo e identificadores

1. Crea una tarea de generación; guarda `task_id`, `ppt_business_id` y `expires_at`.
2. Consulta el estado de la generación usando `task_id`.
3. Lee los resultados de la generación usando `task_id`.
4. Inicia la exportación PPTX usando `ppt_business_id`.
5. Consulta el estado de exportación y descarga el archivo completado.
6. Opcionalmente, elimina la presentación antes de tiempo.

En los marcadores de ruta, `{business_id}` significa el **`ppt_business_id`** devuelto, no el `task_id`, `resource_id` ni `livedoc_short_id`. Usa la misma cuenta API durante todo el flujo de trabajo. Los IDs en los ejemplos son marcadores de posición.

## 1. Crear la presentación

`POST /api/v1/data/ppts`

| Campo | Tipo | Requerido | Significado |
|---|---|---|---|
| `query` | string | Sí | Instrucciones de generación, de 1 a 25.000 caracteres |
| `stream_protocol` | string | No | `message_center_v1` por defecto; normalmente déjalo sin cambios |
| `ppt_config` | object | No | Configuración opcional; la implementación actual lee `ai_theme_id` |
| `livedoc_short_id` | string | No | ID de contexto existente, hasta 100 caracteres; debe pasar las comprobaciones nativas de propiedad de API y caducidad |
| `resource_ids` | arreglo de strings | No | Hasta 100 IDs de recursos UUID; sujeto a las mismas comprobaciones de acceso al contexto |

Para una primera integración, omite los campos de contexto y configuración. Un contexto creado a través de `/v2` no es automáticamente apto para reutilizarse aquí.

```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 devuelve identificadores en la raíz:

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

Pueden aparecer identificadores adicionales como `resource_id`, `stream_key` y `thread_short_id`. Una respuesta de creación exitosa significa que la tarea fue aceptada, no que la generación haya terminado. El número de diapositivas solicitado es una instrucción; la facturación usa la cantidad real de páginas generadas.

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

### Leer eventos de generación con SSE

Si la creación devuelve un `stream_key`, conéctate de inmediato con una clave API perteneciente a la misma cuenta. Si no se devuelve ninguna clave de stream, usa las consultas de estado y resultados que aparecen abajo.

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

| Parámetro de consulta | Significado |
|---|---|
| `format` | `raw` (predeterminado) conserva la cadena `content`; `structured` decodifica JSON válido en un objeto o arreglo |
| `offset` | Posición opcional de reanudación upstream para reconexión; no la infieras de tu recuento local de eventos |

Lee cada evento SSE completo, decodifica su JSON externo y luego procesa `content`. Un evento de aplicación `answer` lleva texto en `data.text`; `finished` señala la finalización de la generación en la secuencia. Maneja también las señales upstream `done`, `[DONE]` y `error`. Si la conexión se cierra sin una señal de finalización, consulta el estado de la tarea.

Usa las reglas de análisis y el ejemplo de cliente de [SuperAgent SSE](https://openapi.felo.ai/es/docs/api-reference/superagent.md#2-consumir-el-flujo-sse), con la URL `/api/v1/data/conversations/stream/{stream_key}` de esta sección. Lee el resultado de la tarea después de que termine la secuencia; la exportación a PPTX sigue siendo un paso separado. Este endpoint no habilita `stream: true` en `/api/v1/data/chat`.

## 2. Consultar el estado de generación

`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 respuesta tiene una cadena `status` en la raíz, por ejemplo `RUNNING` o `COMPLETED`. Consulta con un intervalo limitado (por ejemplo, 2–5 segundos) y una fecha límite. Continúa con los resultados después de completar; maneja fallos y estados inesperados sin asumir éxito. Una fecha límite de sondeo no cancela la tarea.

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

## 3. Leer resultados de generación

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

Este es un **POST**, y no requiere cuerpo JSON.

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

Lee `task_status` antes de usar `history_data`. La carga histórica puede variar según la tarea y puede ser null. `ai_page_html` y `thread_short_id` son opcionales. Esta respuesta no es una URL de descarga PPTX garantizada; usa exportación a continuación.

## 4. Iniciar exportación 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 generación debe haberse completado antes de exportar. Repetir POST mientras la misma exportación está en curso la reutiliza. Iniciar otra exportación después de la finalización crea una nueva exportación y puede incurrir en otro cargo. Usa GET para consultar y actualizar el enlace de descarga.

## 5. Consultar exportación y descargar

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

| Estado | Próxima acción |
|---|---|
| `NOT_STARTED` | Envía la exportación una vez |
| `PROCESSING` | Espera y luego vuelve a consultar GET |
| `COMPLETED` | Lee `download_url` y descarga el archivo |
| `FAILED` | Inspecciona el error y el estado de la tarea antes de enviar una nueva exportación |

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

La URL de ejemplo es ilustrativa. Usa la URL firmada real de la respuesta. Es válida durante **30 minutos**; el estado de exportación GET puede devolver un enlace nuevo mientras la presentación siga disponible. Guarda el archivo dentro de su periodo de vida. No envíes tu clave API de Felo al host de descarga del archivo.

## 6. Eliminar la presentación

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

El éxito devuelve **HTTP 204 sin cuerpo**. No lo analices como JSON. La eliminación mientras la generación está en curso devuelve 409.

## Vida útil, propiedad y facturación

- Las presentaciones caducan **siete días después de su creación**. Las consultas y exportaciones no prolongan este periodo. El `expires_at` de la presentación y el `expires_at` de la URL firmada describen vidas útiles distintas.
- Solo la cuenta API creadora puede acceder a sus tareas y presentaciones. Un recurso ausente o inaccesible puede devolver 404; un recurso caducado o eliminado puede devolver 410, o 404 después de la limpieza.
- La generación se factura por página generada (`ppt.generate`). Con el precio por página, la creación reserva el precio de diez páginas y luego liquida la salida exitosa real y libera la reserva no utilizada. Tu cuenta necesita saldo disponible suficiente para la reserva incluso si el prompt solicita menos páginas.
- La exportación tiene un precio de solicitud separado (`ppt.export`). Las consultas de estado, las consultas de resultados, las consultas de estado de exportación y la eliminación no crean ningún nuevo cargo.
- Después de un tiempo de espera, consulta la tarea guardada en lugar de crear otra presentación. Consulta [Facturación y errores](https://openapi.felo.ai/es/docs/data-api/guides/felo-billing.md).