# Geração e exportação de PPT

Crie uma apresentação, acompanhe seu progresso, exporte um PPTX e gerencie sua duração.

Gere uma apresentação de forma assíncrona e depois exporte um arquivo PPTX. Mantenha as etapas de geração e exportação separadas: uma tarefa criada ainda não é um arquivo concluído.

Todos os exemplos usam `FELO_API_KEY` a partir da [visão geral](https://openapi.felo.ai/pt-BR/docs/data-api/guides/felo-overview.md). As chamadas usam **saldo da plataforma**, não créditos Pro da Felo. Os exemplos de resposta são ilustrativos; o conteúdo ao vivo e os campos opcionais variam.

## Fluxo de trabalho e identificadores

1. Crie uma tarefa de geração; salve `task_id`, `ppt_business_id` e `expires_at`.
2. Consulte o status da geração usando `task_id`.
3. Leia os resultados da geração usando `task_id`.
4. Inicie a exportação de PPTX usando `ppt_business_id`.
5. Consulte o status da exportação e baixe o arquivo concluído.
6. Opcionalmente, exclua a apresentação antecipadamente.

Nos espaços reservados de rota, `{business_id}` significa o **`ppt_business_id`** retornado, não o `task_id`, `resource_id` ou `livedoc_short_id`. Use a mesma conta de API durante todo o fluxo. Os IDs nos exemplos são espaços reservados.

## 1. Crie a apresentação

`POST /api/v1/data/ppts`

| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
| `query` | string | Sim | Instruções de geração, 1–25.000 caracteres |
| `stream_protocol` | string | Não | Padrão `message_center_v1`; normalmente deixe sem alteração |
| `ppt_config` | object | Não | Configuração opcional; a implementação atual lê `ai_theme_id` |
| `livedoc_short_id` | string | Não | ID de contexto existente, até 100 caracteres; deve passar pelas verificações nativas de propriedade da API e expiração |
| `resource_ids` | array de strings | Não | Até 100 IDs de recursos UUID; sujeito às mesmas verificações de acesso ao contexto |

Para uma primeira integração, omita os campos de contexto e configuração. Um contexto criado por meio de `/v2` não é automaticamente elegível para reutilização aqui.

```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 retorna identificadores na raiz:

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

Identificadores adicionais como `resource_id`, `stream_key` e `thread_short_id` podem estar presentes. Uma resposta bem-sucedida de criação significa que a tarefa foi aceita, não que a geração foi concluída. A contagem de slides solicitada é uma instrução; a cobrança usa a contagem real de páginas geradas.

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

### Leia eventos de geração com SSE

Se a criação retornar uma `stream_key`, conecte-se imediatamente com uma API Key pertencente à mesma conta. Se nenhuma stream key for retornada, use as consultas de status e de resultado abaixo.

```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` (padrão) preserva a string `content`; `structured` decodifica JSON válido em um objeto ou array |
| `offset` | Posição opcional de retomada upstream para reconexão; não a infira da contagem local de eventos |

Leia cada evento SSE completo, decodifique seu JSON externo e então processe `content`. Um evento de aplicativo `answer` carrega texto em `data.text`; `finished` sinaliza a conclusão da geração no stream. Também lide com sinais upstream `done`, `[DONE]` e `error`. Se a conexão for encerrada sem um sinal de conclusão, consulte o status da tarefa.

Use as regras de análise e o exemplo de cliente em [SuperAgent SSE](https://openapi.felo.ai/pt-BR/docs/api-reference/superagent.md#2-consumir-o-stream-sse), com a URL desta seção `/api/v1/data/conversations/stream/{stream_key}`. Leia o resultado da tarefa após o término do stream; a exportação de PPTX continua sendo uma etapa separada. Este endpoint não habilita `stream: true` em `/api/v1/data/chat`.

## 2. Consulte o status da geração

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

A resposta tem uma string `status` na raiz, por exemplo `RUNNING` ou `COMPLETED`. Consulte em intervalo limitado (por exemplo, 2–5 segundos) e com um prazo final. Continue para os resultados após a conclusão; trate falhas e estados inesperados sem assumir sucesso. Um prazo de consulta não cancela a tarefa.

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

## 3. Leia os resultados da geração

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

Este é um **POST**, sem necessidade de corpo 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
}
```

Leia `task_status` antes de usar `history_data`. A carga do histórico pode variar conforme a tarefa e pode ser nula. `ai_page_html` e `thread_short_id` são opcionais. Esta resposta não é uma URL garantida para download do PPTX; use a exportação em seguida.

## 4. Inicie a exportação de 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}
```

A geração deve ter sido concluída antes da exportação. Repetir o POST enquanto a mesma exportação está em execução a reutiliza. Iniciar outra exportação após a conclusão cria uma nova exportação e pode gerar outra cobrança. Use GET para consultar e atualizar o link de download.

## 5. Consulte a exportação e baixe

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

| Status | Próxima ação |
|---|---|
| `NOT_STARTED` | Envie a exportação uma vez |
| `PROCESSING` | Aguarde e consulte o GET novamente |
| `COMPLETED` | Leia `download_url` e baixe o arquivo |
| `FAILED` | Inspecione o erro e o estado da tarefa antes de enviar uma nova exportação |

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

A URL de exemplo é ilustrativa. Use a URL assinada real da resposta. Ela é válida por **30 minutos**; o GET de status da exportação pode retornar um link novo enquanto a apresentação permanecer disponível. Salve o arquivo dentro do período de validade. Não envie sua chave da API Felo para o host de download do arquivo.

## 6. Exclua a apresentação

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

O sucesso retorna **HTTP 204 sem corpo**. Não o analise como JSON. A exclusão durante a geração em andamento retorna 409.

## Vida útil, propriedade e cobrança

- As apresentações expiram **sete dias após a criação**. Consultas e exportações não estendem esse período. O `expires_at` da apresentação e o `expires_at` da URL assinada de download descrevem durações diferentes.
- Apenas a conta de API que criou a apresentação pode acessar suas tarefas e apresentações. Um recurso ausente ou inacessível pode retornar 404; um recurso expirado ou excluído pode retornar 410, ou 404 após a limpeza.
- A geração é cobrada por página gerada (`ppt.generate`). No preço por página, a criação reserva o preço de dez páginas, depois acerta a saída real bem-sucedida e libera a reserva não utilizada. Sua conta precisa de saldo disponível suficiente para a reserva, mesmo que o prompt solicite menos páginas.
- A exportação tem um preço de solicitação separado (`ppt.export`). Consultas de status, consultas de resultado, consultas de status de exportação e exclusão não criam nova cobrança.
- Após um timeout, consulte a tarefa salva em vez de criar outra apresentação. Veja [Cobrança e Erros](https://openapi.felo.ai/pt-BR/docs/data-api/guides/felo-billing.md).