Geração e exportação de PPT

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

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.

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:

{
  "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.

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.

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'

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, 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

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.

{"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.

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/historical" \
  -H "Authorization: Bearer $FELO_API_KEY"

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

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"

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

curl -sS --request GET "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"

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

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.