# Crear presentación de Felo

POST /api/v1/data/ppts

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.





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



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